# chapter-gtm/chapter architecture

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

- Interactive diagram: https://gitdiagram.com/chapter-gtm/chapter
- Repository: https://github.com/chapter-gtm/chapter

## Overview

##### Project type and purpose
- This is a full-stack, single-codebase GTM (go-to-market) tool for developer-tools companies.
- The frontend is a Next.js/React application (in the `frontend` folder).
- The backend is a Python Litestar service with SQLAlchemy and Alembic for PostgreSQL and uses Redis for background tasks/queueing.

##### Main components
a. Frontend (Next.js + React + Tailwind + shadcn/ui + Tiptap)
b. Backend API (Litestar framework, domain-driven structure under `src/app/domain`, OpenAPI and routers under `src/app/server`)
c. Database (PostgreSQL, SQLAlchemy models & Alembic migrations in `src/app/db`)
d. Message broker/queue (Redis, used by the SAQ worker process for background jobs)
e. Background worker (SAQ or Litestar task runner loading tasks from `domain/system/tasks`)
f. Authentication service (Supabase for front-end auth, configured under `frontend/src/utils/supabase` and `frontend/src/app/providers.tsx`)
g. External integrations/services (GitHub API, PDFShift, PitchBook, ScraperAPI, App Store, etc., implemented under `src/app/lib`)

##### Relationships and data flows
- The user’s browser loads UI assets from Next.js (static and dynamic pages).
- UI actions call the Litestar API via HTTP(S) endpoints.
- Litestar controllers (in `src/app/domain/.../controllers.py`) orchestrate requests through services → repositories → SQLAlchemy ORM → PostgreSQL.
- For long-running tasks (e.g., scraping, PDF generation, lead enrichment), the API enqueues jobs to Redis; the SAQ worker picks up jobs, invokes the same service/business logic, then writes results back to the database.
- Authentication: frontend interacts with Supabase Auth directly for login/refresh flows; the API enforces authentication and authorization via Litestar guards and dependencies.
- CI/CD pipelines (GitHub Actions in `.github/workflows`) test both frontend and backend, build docs, and manage releases.
- Docker Compose orchestrates the full stack locally: Postgres, Redis, API, frontend, docs builder (via `docker-compose.yml` and `deploy/docker`).

##### Architectural patterns and design principles
- Clean/Hexagonal architecture: domain layer (`controllers`, `services`, `repositories`, `schemas`) decoupled from transport (Litestar) and persistence (SQLAlchemy).
- Layered approach:
- Presentation: Next.js React UI
- API/Transport: Litestar routers & OpenAPI
- Domain: business logic & policies under `src/app/domain`
- Infrastructure: DB models, external clients (`src/app/lib`), queueing
- Dependency injection via Litestar’s plugins and `dependencies.py` in each domain.
- DDD: one folder per subdomain (accounts, companies, jobs, opportunities, people, repos, teams, tags).

##### Essential architectural elements to capture
- Frontend build & hosting (Vercel or Docker)
- API service container & OpenAPI docs
- Background worker container & task folder (`domain/system/tasks`)
- PostgreSQL and Alembic migrations pipeline (`src/app/db/migrations`)
- Redis broker for SAQ tasks
- Supabase Auth integration path
- Major domain modules (accounts, companies, jobs, opportunities, people, repos, teams, tags) to illustrate modularity
- CI/CD workflows (optional side panel)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Frontend)" 
        direction TB
        NextJS["Next.js Client"]:::frontend
        Routes["Pages & Routing"]:::frontend
        subgraph "Supabase Auth Integration"
            direction TB
            auth_ts["auth.ts"]:::frontend
            client_ts["client.ts"]:::frontend
            middleware_ts["middleware.ts"]:::frontend
            server_ts["server.ts"]:::frontend
            providers_tsx["providers.tsx"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Server (Litestar)" 
        direction TB
        ASGI["asgi.py\n(ASGI App)"]:::api
        Builder["builder.py"]:::api
        OpenAPI["openapi.py"]:::api
        Routers["routers.py"]:::api
        Plugins["plugins.py"]:::api
        Domain["Domain Layer\n(src/app/domain/)"]:::api
    end

    %% Worker Layer
    subgraph "Worker (SAQ)" 
        direction TB
        Worker["SAQ Worker\n(cli commands)"]:::api
        Tasks["tasks.py\n(domain/system/tasks)"]:::api
    end

    %% Data Stores
    subgraph "Database\n(PostgreSQL)" 
        direction TB
        DBModels["Models\n(src/app/db/models/)"]:::datastore
        Migrations["Migrations\n(src/app/db/migrations/)"]:::datastore
        DB["PostgreSQL DB"]:::datastore
    end

    Redis["Redis Queue"]:::datastore

    %% External Services
    subgraph "External Services" 
        direction TB
        GH["GitHub API"]:::external
        PDF["PDFShift"]:::external
        Pitch["PitchBook"]:::external
        Scraper["ScraperAPI"]:::external
        AppStore["App Store API"]:::external
    end

    %% Relationships
    NextJS -->|loads pages| Routes
    Routes -->|"Auth calls"| auth_ts
    Routes -->|"Auth calls"| client_ts
    Routes -->|"Auth calls"| middleware_ts
    Routes -->|"Auth calls"| server_ts
    Routes -->|"Auth calls"| providers_tsx

    Routes -->|"HTTP/REST"| ASGI
    ASGI --> Builder
    Builder --> Routers
    Builder --> OpenAPI
    Builder --> Plugins
    Routers --> Domain

    Routers -->|"Enqueue tasks"| Redis
    Redis -->|"Dequeue jobs"| Worker
    Worker --> Tasks
    Worker -->|"SQL"| DB
    Domain -->|"SQL"| DBModels
    DBModels --> DB
    Migrations --> DB

    Domain -->|"HTTP"| GH
    Domain -->|"HTTP"| PDF
    Domain -->|"HTTP"| Pitch
    Domain -->|"HTTP"| Scraper
    Domain -->|"HTTP"| AppStore
    Worker -->|"HTTP"| GH
    Worker -->|"HTTP"| PDF
    Worker -->|"HTTP"| Pitch
    Worker -->|"HTTP"| Scraper
    Worker -->|"HTTP"| AppStore

    %% Click Events
    click NextJS "https://github.com/chapter-gtm/chapter/tree/main/frontend/"
    click Routes "https://github.com/chapter-gtm/chapter/tree/main/frontend/src/app/"
    click auth_ts "https://github.com/chapter-gtm/chapter/blob/main/frontend/src/utils/supabase/auth.ts"
    click client_ts "https://github.com/chapter-gtm/chapter/blob/main/frontend/src/utils/supabase/client.ts"
    click middleware_ts "https://github.com/chapter-gtm/chapter/blob/main/frontend/src/utils/supabase/middleware.ts"
    click server_ts "https://github.com/chapter-gtm/chapter/blob/main/frontend/src/utils/supabase/server.ts"
    click providers_tsx "https://github.com/chapter-gtm/chapter/blob/main/frontend/src/app/providers.tsx"
    click ASGI "https://github.com/chapter-gtm/chapter/blob/main/src/app/asgi.py"
    click Builder "https://github.com/chapter-gtm/chapter/blob/main/src/app/server/builder.py"
    click OpenAPI "https://github.com/chapter-gtm/chapter/blob/main/src/app/server/openapi.py"
    click Routers "https://github.com/chapter-gtm/chapter/blob/main/src/app/server/routers.py"
    click Plugins "https://github.com/chapter-gtm/chapter/blob/main/src/app/server/plugins.py"
    click Domain "https://github.com/chapter-gtm/chapter/tree/main/src/app/domain/"
    click DBModels "https://github.com/chapter-gtm/chapter/tree/main/src/app/db/models/"
    click Migrations "https://github.com/chapter-gtm/chapter/tree/main/src/app/db/migrations/"
    click Tasks "https://github.com/chapter-gtm/chapter/blob/main/src/app/domain/system/tasks.py"
    click Redis "https://github.com/chapter-gtm/chapter/blob/main/src/app/config/constants.py"
    click Worker "https://github.com/chapter-gtm/chapter/blob/main/src/app/cli/commands.py"
    click GH "https://github.com/chapter-gtm/chapter/blob/main/src/app/lib/github.py"
    click PDF "https://github.com/chapter-gtm/chapter/blob/main/src/app/lib/pdfshift.py"
    click Pitch "https://github.com/chapter-gtm/chapter/blob/main/src/app/lib/pitchbook.py"
    click Scraper "https://github.com/chapter-gtm/chapter/blob/main/src/app/lib/scraperapi.py"
    click AppStore "https://github.com/chapter-gtm/chapter/blob/main/src/app/lib/app_store.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef api fill:#DFFFE0,stroke:#228B22,stroke-width:2px
    classDef datastore fill:#FFF5D0,stroke:#DAA520,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#555,stroke-width:2px
```
