# clarkchan123/gitdiagram architecture

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

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

## Overview

##### Main Components
- Frontend: Built with Next.js, TypeScript, Tailwind CSS, and ShadCN. It’s responsible for the user interface including:
- Pages under src/app (e.g., page.tsx, layout.tsx)
- Server Actions (found in src/app/_actions for caching, GitHub calls, etc.)
- Backend: Powered by FastAPI and Python (inside the backend/ directory). Key directories and files include:
- The API entry point (backend/app/main.py)
- Routers (generate.py and modify.py) which handle specific endpoints
- Core logic for rate limiting, prompt engineering, and requests (backend/app/core/limiter.py, prompts.py)
- Service layers invoking external AI and GitHub integrations (found within backend/app/services)
- Utility scripts (e.g., format_message.py)
- Database: PostgreSQL is used along with Drizzle ORM. The backend’s database integration is contained in:
- The start-database.sh script for launching a database container
- Database-related code in src/server/db (index.ts, schema.ts)
- External Services & Integrations:
- AI Services: Utilizes OpenAI (o3-mini) and formerly Claude 3.5 Sonnet, which are leveraged through dedicated service modules.
- GitHub Services: Uses GitHub integration for extracting repository information.
- CI/CD & Deployment: Docker, docker-compose (docker-compose.yml), GitHub Actions (workflows), and Nginx (in backend/nginx) for routing.
- Analytics (PostHog, Api-Analytics) as mentioned in the README.

##### Relationships and Interactions
- The Frontend consumes REST API endpoints exposed by the Backend.
- External API service modules (e.g., claude_service, o3_mini_openai_service) handle communication with the respective AI providers.
- CI/CD pipelines (via GitHub Actions) and Docker configurations manage deployment and orchestration between the different containers (frontend on Vercel; backend on EC2 or Docker).

##### Architectural Patterns and Design Principles
- Separation of concerns is clearly observed: the frontend (UI and presentation) is separate from the backend (logic, API, prompt engineering).
- Microservices- or service-oriented principles are evident in how the backend organizes functionality into routers, services, and utility modules.
- Use of Docker containers and orchestration (docker-compose) for encapsulating environments and dependency isolation.
- API-driven architecture connecting user interactions through a clear request-response flow.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: Next.js, React, TypeScript, Tailwind CSS, and ShadCN for UI components.
- Backend: FastAPI, Python, and supplementary libraries for rate limiting and prompt engineering.
- Database: PostgreSQL paired with Drizzle ORM, and database interaction layers in the src/server/db directory.
- External Integrations: Communication with AI endpoints (OpenAI o3-mini, Claude) and GitHub API.
- Other Dev Tools: Docker (with Dockerfile for backend), GitHub Actions for continuous integration and deployment, and Nginx for API routing configuration.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Frontend (Next.js)"]:::frontend
        FE2["Pages & Layout"]:::frontend
        FE3["React Components"]:::frontend
        FE4["Server Actions"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE1["Backend (FastAPI)"]:::backend
        BE2["API Entry Point"]:::backend
        BE3["Routers"]:::backend
        BE4["Core Logic"]:::backend
        BE5["Service Layers"]:::backend
        BE6["Utility Scripts"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        DB1["PostgreSQL Database"]:::db
        DB2["Drizzle ORM Integration"]:::db
        DB3["Database Startup Script"]:::db
    end

    %% External Services
    subgraph "External Services"
        EX1["AI Services (OpenAI, Claude)"]:::external
        EX2["GitHub API Service"]:::external
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        CI1["Docker & Compose"]:::cicd
        CI2["Deployment Scripts"]:::cicd
        CI3["Nginx Configuration"]:::cicd
        CI4["GitHub Actions"]:::cicd
    end

    %% Relationships and Data Flow
    FE1 -->|"APIRequest"| BE2
    BE2 -->|"routes"| BE3
    BE2 -->|"processing"| BE4
    BE4 -->|"invokes"| BE5
    BE5 -->|"calls"| EX1
    BE5 -->|"calls"| EX2
    BE4 -->|"persists/fetches"| DB1
    DB2 --- DB1
    BE1 --- BE2
    CI1 --- FE1
    CI1 --- BE1

    %% Class Definitions for coloring
    classDef frontend fill:#C9E6FF,stroke:#333,stroke-width:2px;
    classDef backend fill:#C9FFC9,stroke:#333,stroke-width:2px;
    classDef db fill:#FFE6CC,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD9D9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#E6E6FA,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend
    click FE2 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/page.tsx"
    click FE2 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/layout.tsx"
    click FE2 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/[username]/[repo]/page.tsx"
    click FE3 "https://github.com/clarkchan123/gitdiagram/blob/main/src/components/header.tsx"
    click FE3 "https://github.com/clarkchan123/gitdiagram/blob/main/src/components/footer.tsx"
    click FE3 "https://github.com/clarkchan123/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
    click FE3 "https://github.com/clarkchan123/gitdiagram/blob/main/src/components/action-button.tsx"
    click FE4 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/_actions/cache.ts"
    click FE4 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/_actions/github.ts"
    click FE4 "https://github.com/clarkchan123/gitdiagram/blob/main/src/app/_actions/repo.ts"

    %% Click Events for Backend
    click BE2 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/main.py"
    click BE3 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/routers/generate.py"
    click BE3 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/routers/modify.py"
    click BE4 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/core/limiter.py"
    click BE4 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/prompts.py"
    click BE5 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click BE5 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/services/github_service.py"
    click BE5 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click BE5 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click BE5 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click BE6 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/app/utils/format_message.py"

    %% Click Events for Database
    click DB2 "https://github.com/clarkchan123/gitdiagram/blob/main/src/server/db/index.ts"
    click DB2 "https://github.com/clarkchan123/gitdiagram/blob/main/src/server/db/schema.ts"
    click DB3 "https://github.com/clarkchan123/gitdiagram/blob/main/start-database.sh"

    %% Click Events for CI/CD & Deployment
    click CI1 "https://github.com/clarkchan123/gitdiagram/tree/main/backend/Dockerfile"
    click CI1 "https://github.com/clarkchan123/gitdiagram/blob/main/docker-compose.yml"
    click CI2 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/deploy.sh"
    click CI2 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/entrypoint.sh"
    click CI3 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/nginx/api.conf"
    click CI3 "https://github.com/clarkchan123/gitdiagram/blob/main/backend/nginx/setup_nginx.sh"
    click CI4 "https://github.com/clarkchan123/gitdiagram/blob/main/.github/workflows/deploy.yml"
```
