How alfardil/gitty works
Project type and purpose
• This is a full-stack web application called “Gitty.”
• Frontend: Next.js (TypeScript, React 18, App Router, server actions).
• Backend: FastAPI microservice (Python) for AI-powered analysis and generation.
• Database: Neon (PostgreSQL) accessed via Drizzle ORM.
• External integrations: GitHub REST API (for repo data), an LLM inference service (wrapped in o4_mini_service).
File structure
• Top-level
– Makefile, docker-compose.yml: local orchestration of frontend + backend.
– README.md: overview, tech stack, deployment.
• backend/
– FastAPI app in backend/app: routers (chat.py, generate.py), services (code_analyzer.py, github.py, o4_mini_service.py), utility scripts.
– Dockerfile, entrypoint.sh, fly.toml, requirements.txt.
• frontend/
– app/: Next.js App Router pages and API routes under app/api/auth (GitHub OAuth callbacks, logout, validate).
– components/: React UI components (Header, MermaidDiagram, RepoClientPage, many UI primitives under ui/).
– lib/: client-side hooks and fetch wrappers (fetchBackend.ts uses FastAPI base URL, fetchRepos.ts calls GitHub).
– server/src/db/: Drizzle schema, actions, index for server actions that talk to Neon.
– Configs: drizzle.config.ts, next.config.ts, pnpm-lock.yaml, tsconfig.json, eslint & postcss configs.
README for additional insights
• Hosted on Fly.io (backend) and a custom domain (frontend).
• Production DB on Neon.
Main components
a. Browser (User Agent)
– UI pages (Next.js, React components)
– OAuth flow: “Login with GitHub” → Next.js API routes under /api/auth/github → GitHub OAuth service → callback
b. Frontend Service (Next.js)
– Application Server (SSR, server actions)
– API routes (auth, session validation)
– Server-side Drizzle ORM module → Neon PostgreSQL
– Client-side fetch wrappers → FastAPI endpoints
c. Backend Service (FastAPI)
– Routers: /chat, /generate
– Services: GitHub API adapter, Code Analyzer, LLM wrapper
d. Database (Neon DB)
– Tables defined in drizzle.config.ts and server/src/db/schema.ts
e. External Services
– GitHub REST API (repo metadata, file contents)
– LLM inference endpoint (o4-mini-service or OpenAI)
Relationships and interactions
– User → Browser → Next.js UI → Next.js server actions → Neon DB
– Next.js UI → fetchBackend → FastAPI → LLM/GitHub → FastAPI returns results → UI
– OAuth sequence: Next.js API route ↔ GitHub OAuth endpoints → session stored in DB
– docker-compose (dev) or Fly.io (prod) orchestrates services
Architectural patterns and design principles
• Separation of concerns:
– Presentation (Next.js)
– Business logic / AI orchestration (FastAPI)
– Data persistence (Neon via Drizzle)
• App Router conventions in Next.js for pages and server actions
• Modular services in FastAPI (routers + services + utils)
• Infrastructure as Code for deployment (Dockerfile, fly.toml, docker-compose.yml)