How mdsami/gitdiagram works
Project type and purpose
• The frontend is built in Next.js (TypeScript + Tailwind + ShadCN), and the backend is a FastAPI (Python) service. A PostgreSQL database (via Drizzle ORM) stores any necessary metadata, rate-limit tracking, or user tokens.
File structure
• Top-level directories & files
• src/ → Next.js application (pages, server actions, React components, hooks, styles)
• backend/ → FastAPI application (routers, services, core utilities, Docker, Nginx config)
• server/db/ under src/ → Drizzle ORM schema and database client for Next.js server actions
• docker-compose.yml, start-database.sh → orchestrate backend + Postgres locally
• Config files: next.config.js, tailwind.config.ts, drizzle.config.ts, .env.example, GitHub CI (.github/workflows/deploy.yml)
• Patterns & Layers
• Frontend “Server Actions” in Next.js call backend through REST.
• Backend organizes logic into routers (generate.py, modify.py), service classes (AI adapters, GitHub integration), core utils (rate limiter, formatters).
• Reverse proxy (Nginx) sits in front of FastAPI in Docker.
• Database migrations and client setups live in server/db.
Key insights from README
• Tech stack overview, deployment targets (Vercel for frontend, EC2 + Docker for backend).
• External integrations: OpenAI o4-mini (and other AI services), GitHub API, PostHog analytics, Api-Analytics.
• Self-hosting instructions reveal Docker + docker-compose orchestration and Drizzle ORM usage.
a. Main Components
• User & Browser UI: The Next.js React app (pages under src/app/)
• Frontend Data Fetch/Server Actions: Custom hooks (useDiagram.ts) and REST fetches (src/lib/fetch-backend.ts)
• Backend API: FastAPI application (routers & services) behind Nginx reverse proxy in Docker
• Database: PostgreSQL container managed via Drizzle ORM
• AI Providers: OpenAI o4-mini, Claude, custom OpenRouter endpoints
• GitHub Service: GitHub REST API calls for repo trees and file contents
• Analytics: PostHog & Api-Analytics (external)
• CI/CD & Deployment: GitHub Actions → Vercel (frontend) & EC2 (backend Docker)
b. Component Interactions
• Browser ↔ Next.js frontend (user clicks, navigates, triggers server actions)
• Frontend → FastAPI endpoints (/generate, /modify) via HTTP
• FastAPI → PostgreSQL (Drizzle ORM) for persisting rate-limits or tokens
• FastAPI → AI Provider services (via HTTP) for prompt processing
• FastAPI → GitHub API to fetch file trees and README content
• Analytics events flow from both frontend and backend to PostHog/Api-Analytics
c. Architectural Patterns & Principles
• Layered architecture: UI → API → Services → Data
• Service abstraction: One service class per external API (e.g., claude_service.py, github_service.py)
• Rate limiting: Centralized limiter in core/limiter.py
• Infrastructure as code: Dockerfiles, Compose, Nginx scripts, scripts for DB initialization
• Server Actions: Next.js’s experimental full-stack pattern
d. Key Technologies & Frameworks
• Frontend: Next.js, React Server Actions, TypeScript, Tailwind CSS, ShadCN UI components
• Backend: FastAPI, Uvicorn, Python 3.x, Pydantic, asyncio
• Data: PostgreSQL, Drizzle ORM (TypeScript)
• AI: OpenAI's o4-mini, Anthropic/Claude, mini-openrouter clients
• DevOps: Docker, docker-compose, Nginx, GitHub Actions, Vercel, AWS EC2