# tonikiri666/gitdiagram architecture

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

- Interactive diagram: https://gitdiagram.com/tonikiri666/gitdiagram
- Repository: https://github.com/tonikiri666/gitdiagram

## Overview

##### Project Type & Purpose
- Frontend: Next.js + TypeScript + Tailwind CSS (deployed on Vercel)
- Backend: FastAPI + Python (deployed on EC2, behind Nginx)
- Database: PostgreSQL via Drizzle ORM
- External integrations: GitHub API, PostHog analytics

##### File Structure
- Top-level:
– `backend/` – FastAPI app, routers, services, Dockerfile, Nginx config
– `src/` – Next.js app (app directory, components, hooks, providers)
– `src/server/db/` – Drizzle schema & index
– Docker & compose configs (`docker-compose.yml`, `start-database.sh`)
- Patterns:
– **API layer**: Next.js Server Actions call the FastAPI backend.
– **Micro-services style**: Frontend and backend in separate containers.
– **ORM**: Drizzle for schema & migrations.
– **Rate-limiter**: `backend/app/core/limiter.py`.

##### README for Technical Stack & Architectural Insights
- CI/CD: GitHub Actions (see `.github/workflows/deploy.yml`)
- Caching & rate-limits: implemented at backend router level
- Prompt engineering: `backend/app/prompts.py`
- Self-hosting: Docker Compose spins up FastAPI + Postgres + Nginx

##### Main Components & Interactions
a. **Client (Browser)**
b. **Next.js Frontend**
– Pages & Server Actions (`src/app/_actions`)
– UI Components (`src/components/`)
c. **API Gateway / Reverse Proxy**
– Nginx container forwarding `/api` to FastAPI
d. **FastAPI Backend**
– Routers: `generate`, `modify`
– Services: calls to Anthropic/OpenAI (o4-mini), GitHub API, GitDiagram processing
– Utilities: formatting messages
e. **Database**
– PostgreSQL container, Drizzle ORM for schema & queries
f. **External Services**
– OpenAI (o4-mini) / Anthropic
– GitHub API (private & public repos)
– PostHog / Api-Analytics

##### Architectural Patterns & Design Principles
- **Separation of concerns**: UI vs business logic vs data layer
- **Server Actions**: leverage Next.js for SSR & API calls
- **Containerization**: isolates backend + database + reverse proxy

- **Labels**: Name each component clearly (e.g., “FastAPI: generate router”).
- **Annotations**: Note key frameworks or files (e.g., `prompts.py`, `schema.ts`).

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Presentation Layer"
    Browser["Browser (React/Next.js)"]:::frontend
    SSR["Next.js Server Actions<br/>(src/app/_actions/)"]:::frontend
    UI["UI Components<br/>(src/components/)"]:::frontend
    MD["MermaidDiagram Component<br/>(mermaid-diagram.tsx)"]:::frontend
  end

  Browser -->|"diagram request"| SSR
  SSR -->|"HTTP POST /api/generate"| NGinx
  UI --> MD
  MD --> Browser

  subgraph "Application/API Layer"
    NGinx["Nginx Reverse Proxy<br/>(api.conf)"]:::infra
    FastAPI["FastAPI Main<br/>(main.py)"]:::backend
    GenRouter["Generate Router<br/>(generate.py)"]:::backend
    ModRouter["Modify Router<br/>(modify.py)"]:::backend
    Limiter["Rate Limiter<br/>(limiter.py)"]:::backend
    Prompts["Prompts Module<br/>(prompts.py)"]:::backend
    FormatMsg["Format Utility<br/>(format_message.py)"]:::backend
  end

  NGinx --> FastAPI
  FastAPI --> GenRouter
  FastAPI --> ModRouter
  GenRouter --> Limiter
  GenRouter --> Prompts
  GenRouter --> FormatMsg
  ModRouter --> Limiter
  ModRouter --> Prompts
  ModRouter --> FormatMsg

  subgraph "Services"
    Claude["Claude Service<br/>(claude_service.py)"]:::external
    O4["OpenAI o4-mini Service<br/>(o4_mini_openai_service.py)"]:::external
    O3["OpenAI o3-mini Service<br/>(o3_mini_openai_service.py)"]:::external
    OR3["OpenRouter o3-mini Service<br/>(o3_mini_openrouter_service.py)"]:::external
    GH["GitHub Service<br/>(github_service.py)"]:::external
  end

  GenRouter -->|calls| Claude
  GenRouter -->|calls| O4
  GenRouter -->|calls| O3
  GenRouter -->|calls| OR3
  GenRouter -->|calls| GH
  ModRouter -->|calls| Claude
  ModRouter -->|calls| O4
  ModRouter -->|calls| O3
  ModRouter -->|calls| OR3
  ModRouter -->|calls| GH

  subgraph "Data Layer"
    Postgres["PostgreSQL<br/>(Drizzle ORM)"]:::database
    Schema["Schema<br/>(schema.ts)"]:::database
    DBIndex["DB Client<br/>(index.ts)"]:::database
    DrizzleCfg["Drizzle Config<br/>(drizzle.config.ts)"]:::database
  end

  GenRouter -->|reads/writes| Postgres
  ModRouter -->|reads/writes| Postgres

  subgraph "Infra"
    DockerCompose["Docker Compose<br/>(docker-compose.yml)"]:::infra
    FastAPIDocker["FastAPI Dockerfile<br/>(Dockerfile)"]:::infra
    Entrypoint["Entrypoint Script<br/>(entrypoint.sh)"]:::infra
    SetupDB["DB Startup Script<br/>(start-database.sh)"]:::infra
    SetupNG["Nginx Setup<br/>(setup_nginx.sh)"]:::infra
    CI["CI/CD Workflow<br/>(deploy.yml)"]:::infra
    Env["Env Example<br/>(.env.example)"]:::infra
  end

  subgraph "External Services"
    OpenAIExt["OpenAI API"]:::external
    GitHubExt["GitHub API"]:::external
    PostHog["PostHog Analytics"]:::external
  end

  GenRouter -->|uses| OpenAIExt
  GenRouter -->|uses| GitHubExt
  MD -->|sends events| PostHog

  classDef frontend fill:#cfe2f3,stroke:#0366d6;
  classDef backend fill:#d6eaff,stroke:#005cc5;
  classDef database fill:#ffebcc,stroke:#d27a00;
  classDef external fill:#e8d9ff,stroke:#6f42c1;
  classDef infra fill:#f0f0f0,stroke:#333;

  click SSR "https://github.com/tonikiri666/gitdiagram/tree/main/src/app/_actions/"
  click UI "https://github.com/tonikiri666/gitdiagram/tree/main/src/components/"
  click MD "https://github.com/tonikiri666/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
  click FastAPI "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/main.py"
  click GenRouter "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/routers/generate.py"
  click ModRouter "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/routers/modify.py"
  click Claude "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/services/claude_service.py"
  click O4 "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/services/o4_mini_openai_service.py"
  click O3 "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
  click OR3 "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
  click GH "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/services/github_service.py"
  click Prompts "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/prompts.py"
  click Limiter "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/core/limiter.py"
  click FormatMsg "https://github.com/tonikiri666/gitdiagram/blob/main/backend/app/utils/format_message.py"
  click Schema "https://github.com/tonikiri666/gitdiagram/blob/main/src/server/db/schema.ts"
  click DBIndex "https://github.com/tonikiri666/gitdiagram/blob/main/src/server/db/index.ts"
  click DrizzleCfg "https://github.com/tonikiri666/gitdiagram/blob/main/drizzle.config.ts"
  click NGinx "https://github.com/tonikiri666/gitdiagram/blob/main/backend/nginx/api.conf"
  click SetupNG "https://github.com/tonikiri666/gitdiagram/blob/main/backend/nginx/setup_nginx.sh"
  click DockerCompose "https://github.com/tonikiri666/gitdiagram/blob/main/docker-compose.yml"
  click SetupDB "https://github.com/tonikiri666/gitdiagram/blob/main/start-database.sh"
  click FastAPIDocker "https://github.com/tonikiri666/gitdiagram/tree/main/backend/Dockerfile"
  click Entrypoint "https://github.com/tonikiri666/gitdiagram/blob/main/backend/entrypoint.sh"
  click CI "https://github.com/tonikiri666/gitdiagram/blob/main/.github/workflows/deploy.yml"
  click Env "https://github.com/tonikiri666/gitdiagram/blob/main/.env.example"
```
