# ronbell1/airesume architecture

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

- Interactive diagram: https://gitdiagram.com/ronbell1/airesume
- Repository: https://github.com/ronbell1/airesume

## Overview

##### Project type and purpose
- This is a full-stack AI-powered web application (“AI Resume Builder & ATS Checker”).
- Frontend: Next.js (App Router, TypeScript, Tailwind CSS)
- Backend API: Python FastAPI microservice (AI engine & resume analysis)
- Database: PostgreSQL via Prisma ORM
- Authentication/session management via Auth.js (or Supabase) and Next.js API routes

##### File structure
- **app/**: Next.js App Router pages (“page.tsx”, “layout.tsx”), client/server components, built-in API routes under **app/api/** (auth & resume endpoints)
- **components/** & **components/ui/**: Reusable UI primitives (buttons, dialogs, toggles, forms, etc.)
- **hooks/**: Custom React hooks for mobile detection and toast notifications
- **lib/**: Shared client/server modules (auth-client, auth-schema, prisma client, resume helpers, session utils)
- **prisma/**: Database schema and migrations for Users, Resumes, etc.
- **public/** & **styles/**: Static assets & global CSS
- Root config: next.config.mjs, tsconfig.json, tailwind.config.ts, package.json

##### README
- Confirms split between Next.js frontend (port 3000) and FastAPI backend (port 8000)
- AI model served via FastAPI
- Usage patterns: resume build pages, upload/analysis endpoints, real-time preview, user auth

- Frontend (Next.js App)
- API Layer (Next.js API Routes for auth & basic resume CRUD)
- AI Service (Python FastAPI microservice running AI/ML resume analyzer)
- Database (PostgreSQL via Prisma)
- Authentication Provider (Auth.js or Supabase)
- Static Asset store / CDN (public folder or S3)

1. User Browser → Next.js Frontend (React pages/components)
2. Frontend → Next.js API Routes (POST /api/auth, /api/resume) → Database (store user accounts, resume drafts)
3. Frontend → FastAPI Service (HTTP calls to /analyze) → AI Model → FastAPI → JSON response → Frontend
4. Next.js API Routes ↔ Auth Provider (OAuth/JWT session management)
5. Frontend ↔ Static Asset store (avatars, downloads, PDF previews)

c. Architectural patterns & design principles:
- App Router (Next.js) separating client & server components
- “API Gateway” – Next.js API for user-facing endpoints, delegating AI work to FastAPI
- Prism a ORM for type-safe DB access
- Component-based UI with a design system in **components/ui/**
- Separation of concerns: UI, business logic (lib/ and hooks/), data layer (API + DB), and ML service

d. Key technologies & frameworks:
- React & Next.js (App Directory)
- TypeScript & Tailwind CSS
- Python FastAPI + custom NLP/ML model
- Prisma ORM & PostgreSQL
- Auth.js (or Supabase) for authentication
- Vercel (or Docker/Kubernetes) for deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User Interface
    subgraph "UI Layer"
        direction TB
        User["User Browser"]:::ui
        NextUI["Next.js Frontend (3000)"]:::ui
        DesignSystem["UI Primitives / Design System"]:::ui
        SharedComponents["Shared React Components"]:::ui
        Hooks["Custom React Hooks"]:::ui
        GlobalStyles["Global Styles"]:::ui
        StaticAssets["Static Assets"]:::ui
    end

    %% Layer 2: API Layer
    subgraph "API Layer"
        direction TB
        AuthAPI["Auth API Routes"]:::api
        ResumeAPI["Resume API Routes"]:::api
        PrismaClient["Prisma Client"]:::api
        AuthClient["Authentication Client & Schemas"]:::api
        ResumeHelpers["Resume Helpers"]:::api
        Utils["Utility Functions"]:::api
    end

    %% Layer 3: Data & ML Layer
    subgraph "Data & ML Layer"
        direction TB
        FastAPI["AI Service (8000)"]:::ml
        AIModel["AI Model"]:::ml
        Postgres["PostgreSQL Database"]:::data
    end

    %% Layer 4: External Services
    subgraph "External Services"
        direction TB
        AuthProvider["Auth Provider (Auth.js/Supabase)"]:::ext
        CDN["Static Asset Store (CDN)"]:::ext
    end

    %% Connections
    User -->|uses| NextUI
    NextUI -->|calls /api/auth| AuthAPI
    NextUI -->|calls /api/resume| ResumeAPI
    NextUI -->|calls /analyze| FastAPI
    NextUI -->|fetches assets| StaticAssets

    AuthAPI <-->|"auth session"| AuthProvider
    AuthAPI -->|prisma client| PrismaClient
    ResumeAPI -->|prisma client| PrismaClient
    PrismaClient -->|stores/retrieves| Postgres

    FastAPI -->|runs inference| AIModel
    AIModel -->|response| FastAPI
    FastAPI -->|returns JSON| NextUI

    %% Click Events
    click NextUI "https://github.com/ronbell1/airesume/tree/main/app/"
    click AuthAPI "https://github.com/ronbell1/airesume/blob/main/app/api/auth/[...all]/route.ts"
    click ResumeAPI "https://github.com/ronbell1/airesume/blob/main/app/api/resume/route.ts"
    click DesignSystem "https://github.com/ronbell1/airesume/tree/main/components/ui/"
    click SharedComponents "https://github.com/ronbell1/airesume/tree/main/components/"
    click Hooks "https://github.com/ronbell1/airesume/blob/main/hooks/use-mobile.tsx"
    click Hooks "https://github.com/ronbell1/airesume/blob/main/hooks/use-toast.ts"
    click AuthClient "https://github.com/ronbell1/airesume/blob/main/lib/auth-client.ts"
    click AuthClient "https://github.com/ronbell1/airesume/blob/main/lib/auth-schema.ts"
    click AuthClient "https://github.com/ronbell1/airesume/blob/main/lib/session.ts"
    click ResumeHelpers "https://github.com/ronbell1/airesume/blob/main/lib/resume.ts"
    click PrismaClient "https://github.com/ronbell1/airesume/blob/main/lib/prisma.ts"
    click Postgres "https://github.com/ronbell1/airesume/blob/main/prisma/schema.prisma"
    click Postgres "https://github.com/ronbell1/airesume/tree/main/prisma/migrations/"
    click Utils "https://github.com/ronbell1/airesume/blob/main/lib/utils.ts"
    click GlobalStyles "https://github.com/ronbell1/airesume/blob/main/styles/globals.css"
    click GlobalStyles "https://github.com/ronbell1/airesume/blob/main/app/globals.css"
    click GlobalStyles "https://github.com/ronbell1/airesume/blob/main/tailwind.config.ts"
    click StaticAssets "https://github.com/ronbell1/airesume/tree/main/public/"

    %% Styles
    classDef ui fill:#cfe2ff,stroke:#0366d6,color:#0366d6;
    classDef api fill:#d1e7dd,stroke:#0f5132,color:#0f5132;
    classDef ml fill:#ffe5b4,stroke:#e09f3e,color:#e09f3e;
    classDef data fill:#ffd7d7,stroke:#bb2d3b,color:#bb2d3b;
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
