# daithien2004/socialbook architecture

> Architecture diagram of the GitHub repository daithien2004/socialbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daithien2004/socialbook
- Repository: https://github.com/daithien2004/socialbook

## Overview

##### Project type and purpose
- SocialBook is a full-stack social reading platform combining traditional book management with social features, gamification, and AI-driven services (summaries, TTS, vector search).

##### File structure
- Top-level: `frontend/` (Next.js 15 + TypeScript + TailwindCSS + Radix UI + Redux Toolkit + Socket.IO Client), `backend/` (NestJS 11 + TypeScript + Mongoose + Redis + ChromaDB + Passport + Socket.IO Gateway), and `docker-compose.yml` for Redis & ChromaDB.
- Backend follows a modular, feature-based directory under `src/modules/` (auth, users, books, chapters, chat, notifications, gamification, content-moderation, recommendations, search, etc.). Shared code lives in `src/shared/` (database seeds, Redis cache, Cloudinary config, logger).
- Frontend uses the App Router (`src/app/`) with two major layouts—`(auth)` and `(user)`, plus an `admin/` subtree. UI components under `src/components`, global state under `src/store`, feature slices under `src/features`, and API client wrappers under `src/lib`.

##### README for additional insights
- Tech stacks and feature list confirm: real-time chat & notifications (Socket.IO), AI integrations (Google Gemini, OpenAI/LangChain, HuggingFace, Google Cloud TTS), caching/queues (Redis), vector search (ChromaDB), file hosting (Cloudinary), and secure onboarding/auth (JWT, Passport, NextAuth).

a. Main components
- Frontend (Next.js server + browser-run React components, Redux + RTK Query)
- Backend (NestJS REST & WebSocket API)
- Data stores (MongoDB, Redis, ChromaDB)
- External AI services (Google Gemini, OpenAI, HuggingFace, Google Cloud TTS)
- File storage/CDN (Cloudinary)
- Authentication provider (JWT, Passport strategies, NextAuth middleware)
- Real-time channels (Socket.IO)
- Container orchestration (Docker Compose)
b. Relationships & interactions
- Browser ↔ Next.js (SSR + client navigation)
- Next.js ↔ NestJS (HTTP REST & WebSocket for chat/notifications)
- NestJS ↔ MongoDB (Mongoose schemas in each module)
- NestJS ↔ Redis (caching, session management, rate-limiting, queueing tasks)
- NestJS ↔ ChromaDB (vector search for embeddings)
- NestJS ↔ External AI APIs (Gemini for summaries, OpenAI/LangChain, HuggingFace, Google TTS)
- NestJS ↔ Cloudinary (image uploads)
- NestJS ↔ Redis/Socket.IO (publish real-time events to frontend)
c. Architectural patterns & principles
- Feature modularity (each domain under `modules/`)
- Layered service pattern: Controllers → Services → Repositories (via Mongoose schemas)
- Cross-cutting concerns: Guards (authentication/authorization), filters, interceptors, decorators for roles & validation
- State management on frontend: Redux Toolkit slices + RTK Query for API calls
- Separation of concerns: Frontend vs. backend vs. data stores vs. external services
d. Key technologies
- Next.js 15, TypeScript, Turbopack, TailwindCSS, Radix UI, Framer Motion
- Redux Toolkit, RTK Query, Socket.IO Client
- NestJS 11, TypeScript, Mongoose, Passport + JWT, Socket.IO Gateway
- Redis, ChromaDB, MongoDB, Cloudinary, Google Gemini, OpenAI, HuggingFace, Google Cloud TTS

##### Essential architectural elements
- Authentication flow: NextAuth in Frontend ↔ NestJS Auth Controller ↔ JWT Guard → Redis session/cache
- How Chat & Notifications modules use Socket.IO Gateway for real-time push
- AI integration path: Book Chapter → Gemini summarization → return to Frontend

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Container
    subgraph "Frontend" 
        direction TB
        SSR["Next.js App Router"]:::frontend
        AuthLayout["Auth Layout"]:::frontend
        UserLayout["User Layout"]:::frontend
        AdminLayout["Admin Layout"]:::frontend
        UIComponents["UI Components Library"]:::frontend
        Store["Global State Management (Redux + RTK Query)"]:::frontend
        Features["Feature Slices & RTK APIs"]:::frontend
        APIClient["API Client Wrappers"]:::frontend
        AuthAPI["Auth API Routes (NextAuth)"]:::frontend
        ChatWidget["WebSocket Client (Chat widget)"]:::frontend
        NotificationsHook["Notifications Hook"]:::frontend
        AIIntegration["AI Integration APIs (Gemini, TTS)"]:::frontend
    end

    %% Backend Container
    subgraph "Backend"
        direction TB
        REST["REST API Controllers"]:::backend
        WebSocket["WebSocket Gateway"]:::backend
        AuthModule["Auth Module"]:::backend
        UsersModule["Users Module"]:::backend
        BooksModule["Books Module"]:::backend
        ChaptersModule["Chapters Module"]:::backend
        ChatModule["Chat Module"]:::backend
        ChatGateway["Chat Gateway"]:::backend
        NotificationsModule["Notifications Module"]:::backend
        NotificationsGateway["Notifications Gateway"]:::backend
        Gamification["Gamification Module"]:::backend
        Moderation["Content Moderation Module"]:::backend
        Recommendations["Recommendations Module"]:::backend
        SearchModule["Search Module"]:::backend
        ChromaModule["ChromaDB Module"]:::backend
        GeminiModule["Gemini AI Module"]:::backend
        TTSModule["Text-to-Speech Module"]:::backend
        CloudinaryModule["Cloudinary Module"]:::backend
        RedisModule["Redis Cache & Queue Module"]:::backend
        Seeders["Database Seeders"]:::backend
        FiltersGuards["Global Filters, Guards & Interceptors"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores" 
        direction TB
        MongoDB[(MongoDB)]:::db
        RedisDB[(Redis)]:::db
        ChromaDB[(ChromaDB)]:::db
    end

    %% External Services
    subgraph "External AI & Services"
        direction TB
        GoogleGemini("Google Gemini"):::external
        OpenAI("OpenAI / LangChain"):::external
        HuggingFace("HuggingFace"):::external
        GoogleTTS("Google Cloud TTS"):::external
        Cloudinary("Cloudinary CDN"):::external
    end

    %% Docker Compose
    subgraph "Docker Compose"
        direction TB
        RedisDB
        ChromaDB
    end

    %% Connections - Frontend to Backend
    SSR -->|"REST calls"| REST
    SSR -->|"/api/auth"| AuthAPI
    ChatWidget ---|WebSocket| WebSocket
    NotificationsHook ---|WebSocket| WebSocket
    AIIntegration -->|"REST calls"| REST

    %% Frontend internal
    SSR --> UIComponents
    SSR --> Store
    Store --> Features
    Features --> APIClient
    APIClient --> REST

    %% Backend internal
    REST --> AuthModule
    REST --> UsersModule
    REST --> BooksModule
    REST --> ChaptersModule
    WebSocket --> ChatGateway
    WebSocket --> NotificationsGateway
    AuthModule --> RedisModule
    ChatModule --> RedisModule
    NotificationsModule --> RedisModule
    REST --> Gamification
    REST --> Moderation
    REST --> Recommendations
    REST --> SearchModule
    SearchModule --> ChromaModule
    REST --> GeminiModule
    REST --> TTSModule
    REST --> CloudinaryModule
    AuthModule --> FiltersGuards
    UsersModule --> FiltersGuards
    BooksModule --> FiltersGuards
    ChaptersModule --> FiltersGuards
    Seeders --> MongoDB

    %% Backend to Data Stores
    REST --> MongoDB
    RedisModule --> RedisDB
    ChromaModule --> ChromaDB

    %% Backend to External AI & Services
    GeminiModule --> GoogleGemini
    REST --> OpenAI
    REST --> HuggingFace
    TTSModule --> GoogleTTS
    CloudinaryModule --> Cloudinary

    %% Click Events - Frontend
    click SSR "https://github.com/daithien2004/socialbook/blob/master/frontend/src/app/layout.tsx"
    click AuthLayout "https://github.com/daithien2004/socialbook/blob/master/frontend/src/app/(auth)/layout.tsx"
    click UserLayout "https://github.com/daithien2004/socialbook/blob/master/frontend/src/app/(user)/layout.tsx"
    click AdminLayout "https://github.com/daithien2004/socialbook/blob/master/frontend/src/app/admin/layout.tsx"
    click UIComponents "https://github.com/daithien2004/socialbook/tree/master/frontend/src/components/ui"
    click Store "https://github.com/daithien2004/socialbook/blob/master/frontend/src/store/store.ts"
    click Features "https://github.com/daithien2004/socialbook/tree/master/frontend/src/features"
    click APIClient "https://github.com/daithien2004/socialbook/blob/master/frontend/src/lib/client-api.ts"
    click APIClient "https://github.com/daithien2004/socialbook/blob/master/frontend/src/lib/nestjs-client-api.ts"
    click AuthAPI "https://github.com/daithien2004/socialbook/blob/master/frontend/src/app/api/auth/[...nextauth]/route.ts"
    click ChatWidget "https://github.com/daithien2004/socialbook/blob/master/frontend/src/components/ChatWidget.tsx"
    click NotificationsHook "https://github.com/daithien2004/socialbook/blob/master/frontend/src/components/notification/useNotifications.tsx"
    click AIIntegration "https://github.com/daithien2004/socialbook/blob/master/frontend/src/features/gemini/api/geminiApi.ts"
    click AIIntegration "https://github.com/daithien2004/socialbook/blob/master/frontend/src/features/tts/api/ttsApi.ts"

    %% Click Events - Backend
    click AuthModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/auth"
    click UsersModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/users"
    click BooksModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/books"
    click ChaptersModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/chapters"
    click ChatModule "https://github.com/daithien2004/socialbook/blob/master/backend/src/modules/chat/chat.module.ts"
    click ChatGateway "https://github.com/daithien2004/socialbook/blob/master/backend/src/modules/chat/chat.gateway.ts"
    click NotificationsModule "https://github.com/daithien2004/socialbook/blob/master/backend/src/modules/notifications/notifications.module.ts"
    click NotificationsGateway "https://github.com/daithien2004/socialbook/blob/master/backend/src/modules/notifications/notifications.gateway.ts"
    click Gamification "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/gamification"
    click Moderation "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/content-moderation"
    click Recommendations "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/recommendations"
    click SearchModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/search"
    click ChromaModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/chroma"
    click GeminiModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/gemini"
    click TTSModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/text-to-speech"
    click CloudinaryModule "https://github.com/daithien2004/socialbook/tree/master/backend/src/modules/cloudinary"
    click RedisModule "https://github.com/daithien2004/socialbook/blob/master/backend/src/shared/cache/redis.module.ts"
    click Seeders "https://github.com/daithien2004/socialbook/tree/master/backend/src/shared/database/seeds"
    click FiltersGuards "https://github.com/daithien2004/socialbook/blob/master/backend/src/common/filters/http-exception.filter.ts"
    click FiltersGuards "https://github.com/daithien2004/socialbook/blob/master/backend/src/common/guards/jwt-auth.guard.ts"
    click FiltersGuards "https://github.com/daithien2004/socialbook/blob/master/backend/src/common/interceptors/transform.interceptor.ts"
    click RedisDB "https://github.com/daithien2004/socialbook/blob/master/docker-compose.yml"
    click ChromaDB "https://github.com/daithien2004/socialbook/blob/master/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#58AFFF,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#00A85A,stroke-width:1px
    classDef db fill:#FFE0B2,stroke:#FF9800,stroke-width:1px
    classDef external fill:#E1BEE7,stroke:#9C27B0,stroke-width:1px
```
