How chapter-gtm/chapter works
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)