# rekib0023/collab-doc architecture

> Architecture diagram of the GitHub repository rekib0023/collab-doc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rekib0023/collab-doc
- Repository: https://github.com/rekib0023/collab-doc

## Overview

##### Project type and purpose
- This is a full-stack, real-time collaboration platform with a microservices architecture.
- Frontend: React + TypeScript client using WebSockets for live updates.
- Backend: FastAPI services exposing REST + WebSocket endpoints, backed by PostgreSQL, Redis, and Kafka for persistence, caching, and event streaming.

##### File structure
- Top-level
- docker-compose.yml orchestrates frontend, backend, Redis, Kafka, PostgreSQL, etc.
- README.md & docs/project-overview.md describe features and architecture.
- backend/
- main.py – FastAPI app entry point, config via app/core/config.py.
- app/api/api_v1/endpoints – REST (auth, documents, users, workspaces) & WebSocket endpoints.
- app/crud, app/models, app/schemas – ORM models, Pydantic schemas, CRUD operations.
- Alembic migrations for DB schema management.
- Dockerfile, start.sh, requirements.txt for containerized deployment.
- frontend/
- Vite‐powered React app (ts / tsx) with TailwindCSS and custom UI under src/components/ui.
- RTK Query in src/store for API calls; WebSocketService in src/services for real-time.
- Pages (AuthPage, DocumentPage, WorkspacePage, etc.) wire up components.
- nginx.conf for serving static assets, Dockerfile for container build.

##### Inspect README for architectural insights
- Microservices pattern: clear separation between frontend, backend, and external systems (DB, cache, message bus).
- Real-time collaboration via custom operational transformation (OT) engine and pub/sub (Redis & Kafka).
- High availability & scalability: horizontal scaling of backend, Docker orchestration, CDN for static assets.

##### Don’t overthink—capture every logical component
- Even if OT engine lives inside the backend, represent it as a sub-module.
- Migration tool (Alembic), CI/CD pipeline if relevant (can be a sidebar).
- Docker-Compose orchestrator or Kubernetes cluster as the outer boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing
    Browser["Web Browser"]:::external
    DocsReadme["README.md"]:::infra
    DocsOverview["project-overview.md"]:::infra

    %% Infrastructure
    DockerOrchestration["Docker Orchestration"]:::infra

    %% Frontend Flow
    Browser -->|"Fetch assets (HTTP)"| CDN["CDN / Reverse Proxy (nginx)"]:::infra
    CDN -->|"Serves static files"| FrontendService["Frontend Service (React / Vite)"]:::service

    subgraph "Frontend Application"
        direction TB
        FrontendDockerfile["Dockerfile"]:::infra
        ViteConfig["vite.config.ts"]:::service
        PackageJson["package.json"]:::service
        MainTSX["main.tsx"]:::service
        APIStore["src/store/api.ts"]:::service
        StoreIndex["src/store/index.ts"]:::service
        StoreSlices["src/store/slices/"]:::service
        WebSocketService["WebSocketService.ts"]:::service
        UIComponents["src/components/ui/"]:::service
        Pages["src/pages/"]:::service
        Layouts["src/components/layout/"]:::service
        FrontendService --> FrontendDockerfile
        FrontendService --> ViteConfig
        FrontendService --> PackageJson
        FrontendService --> MainTSX
        MainTSX --> APIStore
        MainTSX --> WebSocketService
        APIStore --> StoreIndex
        StoreIndex --> StoreSlices
        MainTSX --> UIComponents
        MainTSX --> Pages
        MainTSX --> Layouts
    end

    FrontendService -->|"REST & WS"| APIGateway["API Gateway / Load Balancer"]:::service

    %% Backend Flow
    APIGateway -->|"HTTP/WS"| BackendInstances["FastAPI Backend Instances"]:::service

    subgraph "Backend Instances"
        direction TB
        BackendMain["main.py"]:::service
        BackendConfig["config.py"]:::service
        BackendDocker["Dockerfile"]:::infra
        BackendStart["start.sh"]:::infra
        subgraph "API Endpoints"
            direction TB
            Auth["auth.py"]:::service
            DocumentsEP["documents.py"]:::service
            UsersEP["users.py"]:::service
            WorkspacesEP["workspaces.py"]:::service
            WebsocketsEP["websockets.py"]:::service
        end
        subgraph "Dependencies & Security"
            Deps["deps.py"]:::service
            Security["security.py"]:::service
        end
        subgraph "CRUD Layer"
            CrudDoc["crud_document.py"]:::service
            CrudUser["crud_user.py"]:::service
            CrudWorkspace["crud_workspace.py"]:::service
        end
        subgraph "Models & Schemas"
            ModelUser["user.py (model)"]:::datastore
            ModelWorkspace["workspace.py (model)"]:::datastore
            SchemaUser["user.py (schema)"]:::datastore
            SchemaWorkspace["workspace.py (schema)"]:::datastore
        end
        subgraph "Alembic Migrations"
            AlembicEnv["env.py"]:::infra
            AlembicVersions["versions/"]:::infra
            AlembicIni["alembic.ini"]:::infra
        end
        BackendInstances --> BackendMain
        BackendMain --> BackendConfig
        BackendMain --> Auth
        BackendMain --> DocumentsEP
        BackendMain --> UsersEP
        BackendMain --> WorkspacesEP
        BackendMain --> WebsocketsEP
        Auth --> Deps
        DocumentsEP --> Deps
        UsersEP --> Deps
        WorkspacesEP --> Deps
        Deps --> Security
        Auth --> CrudUser
        DocumentsEP --> CrudDoc
        WorkspacesEP --> CrudWorkspace
        CrudDoc --> ModelUser
        CrudDoc --> ModelWorkspace
        ModelUser --> SchemaUser
        ModelWorkspace --> SchemaWorkspace
        BackendMain --> AlembicEnv
        AlembicEnv --> AlembicVersions
        AlembicEnv --> AlembicIni
    end

    %% Data Stores
    PostgreSQL["PostgreSQL"]:::datastore
    Redis["Redis Cluster"]:::datastore
    Kafka["Kafka Cluster"]:::datastore

    BackendInstances -->|"SQL (persistence)"| PostgreSQL
    BackendInstances -->|"Cache & Pub/Sub"| Redis
    BackendInstances -->|"Event streams"| Kafka

    %% OT Engine
    OTEngine["Operational Transformation Engine"]:::service
    BackendInstances -->|"Invoke OT engine"| OTEngine
    OTEngine -->|"Sync via Redis"| Redis
    OTEngine -->|"Stream via Kafka"| Kafka

    %% Documentation & Orchestration
    DockerOrchestration --> FrontendService
    DockerOrchestration --> CDN
    DockerOrchestration --> BackendInstances
    DockerOrchestration --> PostgreSQL
    DockerOrchestration --> Redis
    DockerOrchestration --> Kafka
    DockerOrchestration --> DocsReadme
    DockerOrchestration --> DocsOverview

    %% Click Events
    click DockerOrchestration "https://github.com/rekib0023/collab-doc/blob/main/docker-compose.yml"
    click DocsReadme "https://github.com/rekib0023/collab-doc/blob/main/README.md"
    click DocsOverview "https://github.com/rekib0023/collab-doc/blob/main/docs/project-overview.md"
    click FrontendDockerfile "https://github.com/rekib0023/collab-doc/tree/main/frontend/Dockerfile"
    click ViteConfig "https://github.com/rekib0023/collab-doc/blob/main/frontend/vite.config.ts"
    click PackageJson "https://github.com/rekib0023/collab-doc/blob/main/frontend/package.json"
    click MainTSX "https://github.com/rekib0023/collab-doc/blob/main/frontend/src/main.tsx"
    click APIStore "https://github.com/rekib0023/collab-doc/blob/main/frontend/src/store/api.ts"
    click StoreIndex "https://github.com/rekib0023/collab-doc/blob/main/frontend/src/store/index.ts"
    click StoreSlices "https://github.com/rekib0023/collab-doc/tree/main/frontend/src/store/slices/"
    click WebSocketService "https://github.com/rekib0023/collab-doc/blob/main/frontend/src/services/WebSocketService.ts"
    click UIComponents "https://github.com/rekib0023/collab-doc/tree/main/frontend/src/components/ui/"
    click Pages "https://github.com/rekib0023/collab-doc/tree/main/frontend/src/pages/"
    click Layouts "https://github.com/rekib0023/collab-doc/tree/main/frontend/src/components/layout/"
    click BackendMain "https://github.com/rekib0023/collab-doc/blob/main/backend/main.py"
    click BackendConfig "https://github.com/rekib0023/collab-doc/blob/main/backend/app/core/config.py"
    click BackendDocker "https://github.com/rekib0023/collab-doc/tree/main/backend/Dockerfile"
    click BackendStart "https://github.com/rekib0023/collab-doc/blob/main/backend/start.sh"
    click Auth "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/api_v1/endpoints/auth.py"
    click DocumentsEP "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/api_v1/endpoints/documents.py"
    click UsersEP "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/api_v1/endpoints/users.py"
    click WorkspacesEP "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/api_v1/endpoints/workspaces.py"
    click WebsocketsEP "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/api_v1/endpoints/websockets.py"
    click Deps "https://github.com/rekib0023/collab-doc/blob/main/backend/app/api/deps.py"
    click Security "https://github.com/rekib0023/collab-doc/blob/main/backend/app/core/security.py"
    click CrudDoc "https://github.com/rekib0023/collab-doc/blob/main/backend/app/crud/crud_document.py"
    click CrudUser "https://github.com/rekib0023/collab-doc/blob/main/backend/app/crud/crud_user.py"
    click CrudWorkspace "https://github.com/rekib0023/collab-doc/blob/main/backend/app/crud/crud_workspace.py"
    click ModelUser "https://github.com/rekib0023/collab-doc/blob/main/backend/app/models/user.py"
    click ModelWorkspace "https://github.com/rekib0023/collab-doc/blob/main/backend/app/models/workspace.py"
    click SchemaUser "https://github.com/rekib0023/collab-doc/blob/main/backend/app/schemas/user.py"
    click SchemaWorkspace "https://github.com/rekib0023/collab-doc/blob/main/backend/app/schemas/workspace.py"
    click AlembicEnv "https://github.com/rekib0023/collab-doc/blob/main/backend/alembic/env.py"
    click AlembicVersions "https://github.com/rekib0023/collab-doc/tree/main/backend/alembic/versions/"
    click AlembicIni "https://github.com/rekib0023/collab-doc/blob/main/backend/alembic.ini"

    %% Styles
    classDef external fill:#cfe2f3,stroke:#0b5394,color:#0b5394
    classDef service fill:#d9ead3,stroke:#38761d,color:#38761d
    classDef datastore fill:#fce5cd,stroke:#bf9000,color:#bf9000
    classDef infra fill:#e7e6e6,stroke:#666666,color:#333333
```
