# cpiprint/gitdiagram-cpi architecture

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

- Interactive diagram: https://gitdiagram.com/cpiprint/gitdiagram-cpi
- Repository: https://github.com/cpiprint/gitdiagram-cpi

## Overview

##### Project type and purpose
- The README confirms it uses Next.js/TypeScript/Tailwind on the frontend, FastAPI/Python on the backend, PostgreSQL via Drizzle ORM for persistence, and Claude 3.5 Sonnet as the AI engine.

##### File structure
- Frontend: `/src/app`, `/src/components`, `/src/hooks`, `/src/lib`, `/public`, Tailwind/Next config files. Uses the Next.js App Router (`app` directory) with server actions (`_actions`).
- Backend: `/backend` contains a Dockerfile + entrypoint, FastAPI app under `backend/app` (with routers, services, core logic), an Nginx config, and deploy scripts.
- Database: Drizzle config and schema in `/src/server/db` (Next.js server-side), plus Docker Compose and `start-database.sh` to spin up Postgres.
- CI/CD: `.github/workflows/deploy.yml`.
- Misc: `components.json`, analytics integrations (PostHog), env templates.

##### Key insights from README
- Frontend is deployed on Vercel, backend on EC2 behind Nginx.
- CI/CD via GitHub Actions.
- External services: Anthropic (Claude), GitHub API, PostHog analytics.
- Database: Postgres (Docker) with Drizzle ORM.

a. Main components:
- Browser (User)
- Frontend (Next.js + ShadCN UI)
- CDN / Vercel layer
- Backend API (FastAPI + Nginx) on EC2
- PostgreSQL database (Docker container)
- AI Service (Anthropic Claude 3.5)
- External GitHub API
- Analytics (PostHog, Api-Analytics)
- CI/CD (GitHub Actions)
b. Relationships & data flow:
1. User’s browser → Vercel CDN → Next.js frontend
2. Frontend calls server actions or direct REST calls to FastAPI over HTTPS
4. FastAPI → GitHub service (via `github_service.py`) to fetch repo metadata/files
6. Analytics events from frontend/backend → PostHog
7. CI/CD pipeline (GitHub Actions) builds & deploys frontend to Vercel and backend to EC2
c. Architectural patterns & principles:
- Separation of concerns: Delta between Static/SSR/UI logic and API/microservice logic
- Dockerized backend + Nginx reverse proxy
- Next.js server actions for edge/serverless calls
- Schema-driven ORM (Drizzle)
- Rate limiter in FastAPI (`limiter.py`) to throttle requests
- Event-driven analytics hooks
d. Key technologies & libraries:
- Next.js (App Router), React + TypeScript + Tailwind + ShadCN UI
- FastAPI, Python 3, Uvicorn, Nginx
- Docker, docker-compose, EC2
- PostgreSQL, Drizzle ORM
- Anthropic Claude 3.5 Sonnet
- GitHub API (REST)
- GitHub Actions, Vercel
- PostHog analytics

##### Don’t overthink—capture every logical component
- Break apart the backend into Nginx, FastAPI app, services layer, and rate limiter.
- Next.js folder structure collapsed into “UI Components & Server Actions”.
- Entrypoints (Vercel → Next.js serverless functions or static pages).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CDN
    U["User Browser"]:::user
    CDN["Vercel CDN"]:::cdnlayer
    U -->|"HTTP/HTTPS"| CDN

    subgraph "Frontend Layer (Vercel)"
        direction TB
        NextJS["Next.js Frontend"]:::frontend
        CDN --> NextJS

        subgraph "UI Components & Logic"
            direction TB
            App["src/app"]:::frontend
            Actions["src/app/_actions"]:::api
            Components["src/components"]:::frontend
            Hooks["src/hooks/useDiagram.ts"]:::frontend
            Lib["src/lib"]:::frontend
            App --> Actions
            App --> Components
            App --> Hooks
            App --> Lib
        end

        subgraph "Styles & Config"
            Styles["src/styles/globals.css"]:::config
            Tailwind["tailwind.config.ts"]:::config
        end
        NextJS --> App
        NextJS --> Styles
        NextJS --> Tailwind
    end

    %% Backend Layer
    subgraph "Backend Layer (EC2)"
        direction TB
        Nginx["Nginx Reverse Proxy"]:::infra
        NginxConf["backend/nginx/api.conf"]:::infra
        NginxSetup["backend/nginx/setup_nginx.sh"]:::infra
        NginxConf --> Nginx
        NginxSetup --> Nginx

        subgraph "FastAPI API"
            direction TB
            Entrypoint["backend/entrypoint.sh"]:::infra
            Dockerfile["backend/Dockerfile"]:::infra
            DeployScript["backend/deploy.sh"]:::infra
            Main["backend/app/main.py"]:::api
            RateLimiter["backend/app/core/limiter.py"]:::api

            subgraph "Routers"
                GenerateRouter["backend/app/routers/generate.py"]:::api
                ModifyRouter["backend/app/routers/modify.py"]:::api
                Main --> GenerateRouter
                Main --> ModifyRouter
            end

            subgraph "Services"
                ClaudeService["backend/app/services/claude_service.py"]:::api
                GitHubService["backend/app/services/github_service.py"]:::api
                RateLimiter --> ClaudeService
                RateLimiter --> GitHubService
            end

            Entrypoint --> Dockerfile
            Entrypoint --> Main
            Entrypoint --> RateLimiter
            Entrypoint --> DeployScript
            Nginx --> Entrypoint
        end

        Nginx --> Main
    end

    %% Database Layer
    subgraph "Database (Docker Compose)"
        direction TB
        Compose["docker-compose.yml"]:::infra
        DBBootstrap["start-database.sh"]:::infra
        DBContainer["PostgreSQL"]:::db
        DrizzleIndex["src/server/db/index.ts"]:::db
        DrizzleSchema["src/server/db/schema.ts"]:::db
        DrizzleConfig["drizzle.config.ts"]:::db
        Compose --> DBContainer
        DBBootstrap --> DBContainer
        DBContainer --> DrizzleIndex
        DBContainer --> DrizzleSchema
        DBContainer --> DrizzleConfig
    end

    %% External Services
    Claude["Anthropic Claude 3.5"]:::external
    GitHubAPI["GitHub API"]:::external
    PostHog["PostHog Analytics"]:::external

    Main -->|"calls AI"| Claude
    Main -->|"fetch repo data"| GitHubAPI
    NextJS -->|"analytics events"| PostHog
    Main -->|"analytics events"| PostHog
    Main -->|"read/write"| DBContainer

    %% CI/CD Pipeline
    subgraph "CI/CD"
        direction TB
        CICD[".github/workflows/deploy.yml"]:::ci
        EnvExample[".env.example"]:::config
        Gitignore[".gitignore"]:::config
    end
    CICD -->|"deploy frontend"| NextJS
    CICD -->|"deploy backend"| Entrypoint

    %% Styles
    classDef user fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,shape:rounded
    classDef cdnlayer fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef frontend fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef api fill:#E1F5FE,stroke:#0288D1,color:#01579B
    classDef infra fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef db fill:#FFFDE7,stroke:#FDD835,color:#F57F17,shape:cylinder
    classDef external fill:#ECEFF1,stroke:#546E7A,color:#263238,shape:cloud
    classDef ci fill:#FBE9E7,stroke:#D84315,color:#BF360C
    classDef config fill:#EDE7F6,stroke:#5E35B1,color:#311B92

    %% Click Events
    click App "https://github.com/cpiprint/gitdiagram-cpi/tree/main/src/app"
    click Actions "https://github.com/cpiprint/gitdiagram-cpi/tree/main/src/app/_actions"
    click Components "https://github.com/cpiprint/gitdiagram-cpi/tree/main/src/components"
    click Hooks "https://github.com/cpiprint/gitdiagram-cpi/blob/main/src/hooks/useDiagram.ts"
    click Lib "https://github.com/cpiprint/gitdiagram-cpi/tree/main/src/lib"
    click Styles "https://github.com/cpiprint/gitdiagram-cpi/blob/main/src/styles/globals.css"
    click Tailwind "https://github.com/cpiprint/gitdiagram-cpi/blob/main/tailwind.config.ts"
    click DrizzleIndex "https://github.com/cpiprint/gitdiagram-cpi/blob/main/src/server/db/index.ts"
    click DrizzleSchema "https://github.com/cpiprint/gitdiagram-cpi/blob/main/src/server/db/schema.ts"
    click DrizzleConfig "https://github.com/cpiprint/gitdiagram-cpi/blob/main/drizzle.config.ts"
    click Main "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/main.py"
    click GenerateRouter "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/routers/generate.py"
    click ModifyRouter "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/routers/modify.py"
    click ClaudeService "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/services/claude_service.py"
    click GitHubService "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/services/github_service.py"
    click RateLimiter "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/app/core/limiter.py"
    click Entrypoint "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/entrypoint.sh"
    click Dockerfile "https://github.com/cpiprint/gitdiagram-cpi/tree/main/backend/Dockerfile"
    click DeployScript "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/deploy.sh"
    click NginxConf "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/nginx/api.conf"
    click NginxSetup "https://github.com/cpiprint/gitdiagram-cpi/blob/main/backend/nginx/setup_nginx.sh"
    click Compose "https://github.com/cpiprint/gitdiagram-cpi/blob/main/docker-compose.yml"
    click DBBootstrap "https://github.com/cpiprint/gitdiagram-cpi/blob/main/start-database.sh"
    click CICD "https://github.com/cpiprint/gitdiagram-cpi/blob/main/.github/workflows/deploy.yml"
    click EnvExample "https://github.com/cpiprint/gitdiagram-cpi/blob/main/.env.example"
    click Gitignore "https://github.com/cpiprint/gitdiagram-cpi/blob/main/.gitignore"
```
