Apollo Chat

A modern real-time chat platform built with React, NestJS, GraphQL, and MongoDB

✨ Features • 🏗️ Architecture • 🛠️ Tech Stack • 📚 Documentation • 🔗 Live Demo

🌟 Overview

Apollo Chat is a full-featured real-time messaging platform that demonstrates modern web development practices. Built with a React frontend and NestJS backend, it leverages GraphQL for efficient data operations and WebSocket subscriptions for real-time updates.

Key Highlights

• GraphQL-powered Real-time Communication with filtered subscription channels and optimized payload delivery
• Multi-tier Chat Visibility Model with role-based access control and pinning capabilities
• WebSocket-driven Presence System with connection-aware status transitions and live indicators
• Token-based Authentication Architecture with refresh rotation and multi-strategy support
• MongoDB Aggregation Pipelines for efficient data retrieval with embedded latest messages
• S3-integrated Media Management for profile images with secure upload workflows
• Interactive Onboarding Experience with guided welcome tour and contextual user interface
• Subscription Lifecycle Management with dependency-aware cleanup and race condition prevention
• Secure Demo Environment with read-only access and specialized interceptors

📸 Screenshots

Screenshots of the application's key features are available in the detailed documentation. See the Features section for visual examples of the user interface.

✨ Features

💬 Real-time Messaging Instant message delivery via Graphql subscriptions Message history with pagination Optimistic UI updates with Apollo cache integration Chat-isolated PubSub channels with member filtering	👥 Chat Management Create private or public chats Add/remove members and moderate chats with ban system Pin important conversations Discover and join public chats
👤 User Profiles Custom profile pictures Connection-aware WebSocket live status indicators User search functionality Multi-state status management (online/away/busy/offline)	🔒 Security Features JWT with HTTP-only cookie rotation protocol Multi-strategy authentication (Local/OAuth/JWT) Time-limited OTP verification with throttling Session tracking with cross-device token revocation
🎨 UI Features Mobile-first responsive design across devices Optimistic UI updates with Apollo cache integration Subscription reference tracking with automatic cleanup Structured cache operations with pagination merging	📱 Mobile Experience Touch-optimized drawer interface Compact menus for small screens Bottom navigation for common actions Smart scroll management with position preservation

🏗️ Architecture

Apollo Chat follows a modern, layered architecture with clear separation of concerns:

graph TB
    subgraph "Client Layer"
        Browser[Web Browser]
        Mobile[Mobile App]
    end

    subgraph "API Layer"
        REST[REST Controllers]
        GraphQL[GraphQL Resolvers]
        WebSockets[WebSocket Gateway]
        Guards[Authentication Guards]
        Interceptors[Interceptors]
    end

    subgraph "Business Logic Layer"
        Services[Domain Services]
        PubSub[PubSub System]
        Validation[Input Validation]
    end

    subgraph "Data Access Layer"
        Repositories[Repositories]
        Entities[Entity Models]
        Migration[Database Migration]
    end

    subgraph "External Services"
        Database[(MongoDB)]
        Redis[(Redis)]
        S3[AWS S3]
        SMTP[Email Server]
        OAuth[OAuth Providers]
    end

    Browser --> REST
    Browser --> GraphQL
    Browser --> WebSockets
    Mobile --> REST
    Mobile --> GraphQL
    Mobile --> WebSockets

    REST --> Guards
    GraphQL --> Guards
    WebSockets --> Guards

    Guards --> Interceptors
    Interceptors --> Services

    Services --> Validation
    Services --> PubSub

    Services --> Repositories
    Repositories --> Entities
    Entities --> Migration

    Repositories --> Database
    PubSub --> Redis
    Services --> S3
    Services --> SMTP
    Services --> OAuth

    classDef clientLayer fill:#D4E6F1,stroke:#2874A6,stroke-width:1px,color:#000;
    classDef apiLayer fill:#D5F5E3,stroke:#1E8449,stroke-width:1px,color:#000;
    classDef businessLayer fill:#FCF3CF,stroke:#B7950B,stroke-width:1px,color:#000;
    classDef dataLayer fill:#F5CBA7,stroke:#A04000,stroke-width:1px,color:#000;
    classDef externalLayer fill:#D2B4DE,stroke:#6C3483,stroke-width:1px,color:#000;

    class Browser,Mobile clientLayer;
    class REST,GraphQL,WebSockets,Guards,Interceptors apiLayer;
    class Services,PubSub,Validation businessLayer;
    class Repositories,Entities,Migration dataLayer;
    class Database,Redis,S3,SMTP,OAuth externalLayer;

Loading

Backend Architecture

The backend follows NestJS module architecture with GraphQL, REST, and WebSocket support:

graph TB
    Client[Client Applications] -->|HTTP/WS| API[API Gateway]

    API -->|REST| REST[REST Controllers]
    API -->|GraphQL| GQL[GraphQL Resolvers]
    API -->|WebSockets| WS[WebSocket Gateway]

    REST --> Auth[Auth Service]
    REST --> UserC[Users Controller]
    REST --> ChatC[Chats Controller]
    REST --> MsgC[Messages Controller]

    GQL --> UserR[Users Resolver]
    GQL --> ChatR[Chats Resolver]
    GQL --> MsgR[Messages Resolver]
    GQL --> SubR[Subscription Resolvers]

    UserC --> UserS[Users Service]
    UserR --> UserS

    ChatC --> ChatS[Chats Service]
    ChatR --> ChatS

    MsgC --> MsgS[Messages Service]
    MsgR --> MsgS

    SubR --> PS[PubSub System]

    UserS --> UR[Users Repository]
    ChatS --> CR[Chats Repository]
    MsgS --> CR

    UR --> DB[(MongoDB)]
    CR --> DB

    PS -->|Dev| Memory[In-Memory]
    PS -->|Prod| Redis[(Redis)]

    classDef gateway fill:#D4E6F1,stroke:#2874A6,stroke-width:1px,color:#000;
    classDef controllers fill:#D5F5E3,stroke:#1E8449,stroke-width:1px,color:#000;
    classDef services fill:#FCF3CF,stroke:#B7950B,stroke-width:1px,color:#000;
    classDef repositories fill:#F5CBA7,stroke:#A04000,stroke-width:1px,color:#000;
    classDef database fill:#D2B4DE,stroke:#6C3483,stroke-width:1px,color:#000;

    class Client,API gateway;
    class REST,GQL,WS,UserC,ChatC,MsgC,UserR,ChatR,MsgR,SubR controllers;
    class Auth,UserS,ChatS,MsgS,PS services;
    class UR,CR repositories;
    class DB,Memory,Redis database;

Loading

Frontend Architecture

The frontend uses Apollo Client for state management and GraphQL operations:

graph TD
    Client[Browser Client] -->|HTTP/WS| ApolloClient[Apollo Client]
    ApolloClient -->|GraphQL| API[Backend API]
    ApolloClient -->|REST| API

    ApolloClient --> Cache[Apollo Cache]
    ApolloClient --> ReactiveVars[Reactive Variables]

    ApolloClient --> ReactComponents[React Components]
    ReactComponents --> Pages[Pages]
    ReactComponents --> SharedComponents[Shared Components]

    Pages --> Auth[Auth Pages]
    Pages --> Chat[Chat Interface]
    Pages --> Profile[Profile]
    Pages --> Explore[Explore]

    SharedComponents --> Header[Header]
    SharedComponents --> StatusIndicator[Status Indicator]
    SharedComponents --> ErrorBoundary[Error Boundary]

    Cache --> UIComponents[UI Components]

    classDef client fill:#D4E6F1,stroke:#2874A6,stroke-width:1px,color:#000;
    classDef apollo fill:#D5F5E3,stroke:#1E8449,stroke-width:1px,color:#000;
    classDef api fill:#FCF3CF,stroke:#B7950B,stroke-width:1px,color:#000;
    classDef components fill:#F5CBA7,stroke:#A04000,stroke-width:1px,color:#000;
    classDef pages fill:#D2B4DE,stroke:#6C3483,stroke-width:1px,color:#000;

    class Client client;
    class ApolloClient,Cache,ReactiveVars apollo;
    class API api;
    class ReactComponents,SharedComponents,UIComponents,Header,StatusIndicator,ErrorBoundary components;
    class Pages,Auth,Chat,Profile,Explore pages;

Loading

🛠️ Tech Stack

Frontend

• Framework: React 18 with TypeScript
• State Management: Apollo Client
• UI Components: Material UI 5
• Routing: React Router 7
• Real-time: GraphQL Subscriptions (graphql-ws)
• Type Generation: GraphQL Code Generator
• Utilities: date-fns, Framer Motion

Backend

• Framework: NestJS with TypeScript
• API: GraphQL (Apollo Server 4), REST (Express)
• Database: MongoDB with Mongoose ODM
• Real-time: GraphQL Subscriptions with PubSub
• Authentication: JWT, Google OAuth 2.0, OTP Verification
• File Storage: AWS S3
• Email: Nodemailer with SMTP
• Validation: class-validator, GraphQL input types
• Rate Limiting: NestJS Throttler

DevOps & CI/CD

• CI/CD: GitHub Actions with staging/production workflows
• Secrets Management: GitHub Encrypted Secrets
• Monitoring: AWS CloudWatch (planned)
• Logs: Pino Logger
• Monitoring (planned): AWS CloudWatch or third-party services like Sentry
• Build System: Zip deployment packages (Elastic Beanstalk), Amplify build pipelines (frontend)

Cloud Infrastructure

• Frontend Hosting: AWS Amplify
• Backend Hosting: AWS Elastic Beanstalk
• Cache Layer: Redis OSS on AWS ElastiCache
• Storage: AWS S3 (file uploads, profile pictures)
• CDN: AWS CloudFront for assets and media
• DNS Management: Custom domain managed via GoDaddy using CNAME records
• Email Services: Mailgun

Testing & Documentation

• Testing: Jest (unit, integration) and Supertest (e2e), httpyac-endpoints
• Documentation: Compodoc (NestJS), Markdown-based frontend docs

🔐 Security

Apollo Chat implements a sophisticated zero-trust security architecture with defense-in-depth principles:

Authentication Mechanisms

• JWT-based Token Authentication: Stateless cryptographic tokens with HTTP-only cookie storage
• Multi-protocol Identity Verification: OAuth 2.0 integration, credential-based authentication, and OTP verification
• Token Rotation Protocol: Secure refresh token mechanism with configurable expiration policies
• Session Management: Multi-device login support with cross-device revocation capabilities

Protection Layer

• Tiered Rate Limiting: Endpoint-specific request throttling with customized limits (1/min for OTP, 5/min for verification)
• Multi-layer Input Validation: Context-aware sanitization with XSS/injection prevention
• Access Control: Role-based permissions with creator/member-specific operations
• Network Layer Security: Strict CORS policy with proxy-aware request handling

Client-Server Security

• Reactive Authentication State: Non-persistent token management with automatic refresh mechanism
• Secure Cookie Implementation: HTTP-only, SameSite=strict, and Secure flag enforcement
• Cryptographic Password Storage: Bcrypt hashing with environment-specific configuration

For comprehensive security implementation details, see the Security Documentation and Authentication Documentation.

📚 Documentation

Comprehensive documentation is available in the docs directory:

• Backend

  • Architecture
  • API Architecture
  • API Reference
  • Database
  • PubSub System

• Frontend

  • Architecture
  • Caching
  • Features
  • Hooks
  • Lifecycle & Effects

• Core Modules

  • Authentication
  • Users
  • Chats
  • Messages

• Infrastructure

  • Deployment
  • Security

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• NestJS - The progressive Node.js framework
• React - A JavaScript library for building user interfaces
• Apollo GraphQL - The GraphQL implementation
• MongoDB - The database for modern applications
• Material UI - React components for faster and easier web development