How jabdy86/gitdiagram works
Project type and purpose
• Frontend: Next.js + TypeScript + Tailwind CSS + ShadCN
• Database: PostgreSQL (Drizzle ORM)
• External services: OpenAI/Anthropic AI models, GitHub API
File structure
Top level:
• docker-compose.yml, start-database.sh – orchestrate local Docker services (backend, Postgres)
• backend/ – FastAPI service, routers, AI & GitHub service clients, Nginx config, Dockerfile, deploy/entrypoint scripts
• src/ – Next.js app with React components, server/db (Drizzle ORM), server actions, hooks, styles, public assets
• .github/workflows/deploy.yml – CI/CD for deploying frontend to Vercel and backend to EC2
• drizzle.config.ts – Drizzle ORM config for Postgres
Key patterns:
• Clear separation of concerns (frontend vs backend)
• Modular “services” in backend to encapsulate calls to each AI provider or GitHub API
• Server Actions in Next.js (src/app/_actions) for “backend-lite” operations (e.g., caching)
• PostHog + custom analytics instrumented in both layers
Main components
a. User’s Browser (UI)
– Next.js pages & React components
– UI state/hooks (useDiagram, useStarReminder)
– API calls via fetch-backend.ts / server actions
b. Frontend Hosting (Vercel)
c. Backend API (FastAPI)
– Routers: /generate, /modify
– Core rate-limiter
– Prompt pipeline (prompts.py)
– Services: anthropic/Claude, OpenAI variants, OpenRouter, GitHub service
d. Reverse Proxy (Nginx)
e. Database (PostgreSQL via Drizzle ORM)
– Usage logs, caching, rate-limit state
f. External Services
– OpenAI / Anthropic AI endpoints
– GitHub REST API
– Analytics (PostHog, Api-Analytics)
g. CI/CD (GitHub Actions)
Relationships & data flows
1) User interacts with Frontend UI → triggers HTTP request (REST or Server Action).
2) Frontend → Backend (via nginx reverse proxy) /generate or /modify.
3) Backend Router
– Applies rate limiting
– Invokes prompt pipeline → calls AI service client(s)
– Calls GitHub service client to fetch repo file tree / README if needed
– Persists metadata/logs to PostgreSQL
5) User clicks nodes → navigates to source files/dirs (client-side routing).
6) Analytics events sent in parallel to PostHog / Api-Analytics.
Architectural patterns & principles
• Layered architecture: UI ↔ API ↔ DB ↔ External services
• “Service” abstraction in backend for each external integration
• Drizzle ORM for type-safe DB interactions
• Server Actions in Next.js for light backend tasks (e.g., cache)
• Containerized deployment with Docker + Nginx
• CI/CD pipeline orchestrated in GitHub Actions