# alfardil/gitty architecture

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

- Interactive diagram: https://gitdiagram.com/alfardil/gitty
- Repository: https://github.com/alfardil/gitty

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser[(Browser)]:::browser
        UI["Next.js UI<br/>(React Components)"]:::frontend
    end

    %% Frontend Service
    subgraph "Frontend Service (Next.js)" 
        AppServer["App Server<br/>(SSR, Server Actions)"]:::frontend
        AuthAPI["Auth API Routes<br/>(/api/auth)"]:::frontend
        FetchBackend["fetchBackend.ts"]:::frontend
        FetchRepos["fetchRepos.ts"]:::frontend
        Hooks["React Hooks"]:::frontend
        DrizzleSchema["Drizzle ORM Module"]:::db
    end

    %% Backend Service
    subgraph "Backend Service (FastAPI)"
        Main["main.py"]:::backend
        Routers["Routers<br/>(chat.py, generate.py)"]:::backend
        Services["Business Logic Services"]:::backend
        Utils["Utilities"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        NeonDB[(Neon PostgreSQL)]:::db
    end

    %% External Services
    subgraph "External Services"
        GitHubAPI[(GitHub REST API)]:::external
        LLMService[(LLM Inference Service)]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DockerCompose["docker-compose.yml"]:::infra
        Makefile["Makefile"]:::infra
        README["README.md"]:::infra
    end

    %% Relationships
    Browser -->|"renders UI"| UI
    UI -->|"uses Auth API"| AuthAPI
    AuthAPI -->|"OAuth HTTPS"| GitHubAPI
    GitHubAPI -->|"callback"| AuthAPI
    AuthAPI -->|"store session"| DrizzleSchema

    UI -->|"calls fetchBackend"| FetchBackend
    UI -->|"calls fetchRepos"| FetchRepos
    FetchBackend -->|"REST/HTTPS"| Main
    FetchRepos -->|"REST/HTTPS"| Main

    AppServer -->|"server actions query"| DrizzleSchema
    AppServer -->|"invokes"| Main

    Main -->|"includes routers"| Routers
    Routers -->|"invokes services"| Services
    Services -->|"calls GitHub API"| GitHubAPI
    Services -->|"calls LLM"| LLMService
    Services -->|"formats"| Utils

    DrizzleSchema -->|"reads/writes"| NeonDB
    Main -->|"caches insights"| NeonDB

    DockerCompose --> AppServer
    DockerCompose --> Main
    Makefile --> DockerCompose

    %% Click Events
    click UI "https://github.com/alfardil/gitty/tree/main/frontend/components"
    click AuthAPI "https://github.com/alfardil/gitty/tree/main/frontend/app/api/auth"
    click FetchBackend "https://github.com/alfardil/gitty/blob/main/frontend/lib/fetchBackend.ts"
    click FetchRepos "https://github.com/alfardil/gitty/blob/main/frontend/lib/fetchRepos.ts"
    click Hooks "https://github.com/alfardil/gitty/tree/main/frontend/lib/hooks"
    click DrizzleSchema "https://github.com/alfardil/gitty/tree/main/frontend/server/src/db"
    click Main "https://github.com/alfardil/gitty/blob/main/backend/app/main.py"
    click Routers "https://github.com/alfardil/gitty/blob/main/backend/app/routers/chat.py"
    click Routers "https://github.com/alfardil/gitty/blob/main/backend/app/routers/generate.py"
    click Services "https://github.com/alfardil/gitty/blob/main/backend/app/services/code_analyzer.py"
    click Services "https://github.com/alfardil/gitty/blob/main/backend/app/services/github.py"
    click Services "https://github.com/alfardil/gitty/blob/main/backend/app/services/o4_mini_service.py"
    click Utils "https://github.com/alfardil/gitty/blob/main/backend/app/utils/format_user_message.py"
    click DockerCompose "https://github.com/alfardil/gitty/blob/main/docker-compose.yml"
    click Makefile "https://github.com/alfardil/gitty/tree/main/Makefile"
    click README "https://github.com/alfardil/gitty/blob/main/README.md"

    %% Styles
    classDef browser fill:#f9f,stroke:#333,stroke-width:1px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px;
    classDef backend fill:#fbb,stroke:#333,stroke-width:1px;
    classDef db fill:#bfb,stroke:#333,stroke-width:1px;
    classDef external fill:#ffd,stroke:#333,stroke-width:1px;
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px;
```
