# mahmudul-islam32/ai-resume-builder architecture

> Architecture diagram of the GitHub repository mahmudul-islam32/ai-resume-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmudul-islam32/ai-resume-builder
- Repository: https://github.com/mahmudul-islam32/ai-resume-builder

## Overview

1. **High-level shape**
   - This is a two-tier product: a **SvelteKit frontend** in `frontend/` and a **FastAPI backend** in `backend/`.
   - The app is centered on a workflow for **resume upload/editing, job scraping, ATS scoring, cover-letter generation, and application tracking**.

2. **Frontend boundary**
   - The frontend is a **SvelteKit + TypeScript** SPA/SSR app with routes for each user workflow: `login`, `register`, `dashboard`, `resumes`, `jobs/search`, `match`, `cover-letters`, `applications`, and `interviews`.
   - Shared UI and feature logic live under `src/lib/`:
     - `components/` for reusable UI blocks like upload, editor, charts, job display, and dashboards.
     - `services/` for client-side API wrappers and local scoring/document utilities.
     - `stores/auth.ts` for session/auth state.
   - `src/routes/+layout.*` suggests the app shell manages navigation and cross-cutting state.

3. **Backend boundary**
   - The backend is a **FastAPI** application organized by versioned API routes in `backend/app/api/v1/`.
   - Endpoints are split by domain: `auth`, `users`, `resumes`, `jobs`, `ats`, `ai`, `applications`, and `interviews`.
   - `main.py` is the application entrypoint, and `router.py` likely composes the v1 API into the main app.

4. **Core backend layers**
   - `core/` holds cross-cutting infrastructure:
     - `config.py` for environment-driven settings.
     - `database.py` for DB session/engine setup.
     - `security.py` for JWT/auth helpers.
   - `models/base.py` and `schemas/schemas.py` show the standard separation between **database models** and **Pydantic request/response contracts**.

5. **Domain services and processing pipeline**
   - Most business logic is in `backend/app/services/`.
   - Key services are:
     - `resume_parser.py` for extracting structured text from uploaded documents.
     - `job_scraper.py` for pulling job descriptions from URLs.
     - `ats_service.py` and `ats_scoring`-related logic for comparing resumes to job requirements.
     - `ai_service.py`, `custom_model_service.py`, `model_factory.py`, and `my_custom_model.py` for AI/LLM/model integration.
   - This suggests a pipeline of **ingest → parse → analyze → score/generate → persist/return**.

6. **Primary data flow: resume analysis**
   - Users upload resumes from the frontend.
   - The backend accepts the file, stores it in the configured upload path, parses it through the resume parsing service, and returns structured content for editing/scoring.
   - The ATS layer then compares extracted resume content against a job description to produce scores and recommendations.
   - The frontend renders those results in match/analysis views and can feed them into the editor or PDF export flow.

7. **Primary data flow: job scraping and matching**
   - The jobs area lets users submit a job URL.
   - `jobs.py` routes to `job_scraper.py`, which extracts the posting and formats it for downstream use.
   - That job data becomes input for ATS scoring and for cover-letter generation, creating a tight loop between job intake and resume optimization.

8. **Primary data flow: AI generation**
   - The AI endpoints expose generic content generation and resume optimization capabilities.
   - The README and service layout indicate support for **OpenAI** and **Ollama/local LLMs**, with a factory/service abstraction so model selection is not hardcoded into the API layer.
   - This is a clear boundary: the API layer delegates to AI services, which in turn may call external model providers or local inference services.

9. **Persistence and state**
   - The system is designed around **PostgreSQL** for durable application data such as users, resumes, jobs, applications, interviews, and generated artifacts.
   - **Redis** is part of the architecture for caching, session-related concerns, or background/ephemeral workloads.
   - `docker/init.sql` indicates the database may be bootstrapped with schema/data in containerized setups.

10. **Authentication and access control**
   - `auth.py`, `security.py`, and the README together indicate **JWT-based authentication**.
   - The frontend has a dedicated auth store and login/register routes, so most user-facing areas depend on authenticated API calls.
   - The architectural boundary is: public auth endpoints vs. protected CRUD/analysis endpoints.

11. **Document and export handling**
   - The app supports **resume editing and PDF generation** on the frontend, with `RichTextEditor` and `pdfService`.
   - That implies a split responsibility: structured content and analysis come from the backend, while final document rendering/export is partly client-side.
   - Uploaded files and generated outputs are treated as first-class artifacts, not just transient API payloads.

12. **Deployment and runtime topology**
   - The repo is containerized with separate Dockerfiles for frontend and backend, plus `docker-compose.yml` and `docker-compose.dev.yml`.
   - There is an `nginx.conf` under `docker/`, suggesting a reverse-proxy layer for production routing and static delivery.
   - The documented runtime stack is: **SvelteKit frontend**, **FastAPI backend**, **PostgreSQL**, **Redis**, and optional **Ollama/OpenAI** integration.

13. **Operational and delivery boundaries**
   - GitHub Actions (`.github/workflows/ci-cd.yml`) indicates CI/CD is part of the architecture, likely building/testing containerized services.
   - The backend has multiple requirements files (`requirements.txt`, `requirements-docker.txt`, `requirements-simple.txt`), so deployment shape varies by environment.
   - Environment variables in `.env.example` are a major configuration boundary: database, CORS, secret keys, upload limits, and model/provider settings.

14. **What an architecture diagram should emphasize**
   - Put the **frontend** at the edge, with route-based feature screens calling a **versioned FastAPI API**.
   - Show the backend split into **API controllers**, **service layer**, **schema/model layer**, and **core infrastructure**.
   - Connect the service layer to **PostgreSQL**, **Redis**, **file storage/uploads**, and **external AI/model providers**.
   - Highlight the main workflows: **auth**, **resume upload/parsing**, **job scraping**, **ATS scoring**, **cover-letter generation**, and **application/interview tracking**.

Main entry points: [`frontend/src/routes/+layout.svelte`](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/+layout.svelte) (App shell), [`backend/app/services/resume_parser.py`](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/services/resume_parser.py) (Domain services), [`backend/app/api/v1/router.py`](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/router.py) (API router), [`backend/app/api/v1/endpoints/applications.py`](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/applications.py) (Tracking API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>sveltekit shell<br/>[+layout.svelte]"]
  node_frontend_auth["Auth pages<br/>route screens<br/>[+page.svelte]"]
  node_frontend_dashboard["Dashboard<br/>route screen<br/>[+page.svelte]"]
  node_frontend_resumes["Resumes<br/>route screens<br/>[+page.svelte]"]
  node_frontend_jobs["Job search<br/>route screen<br/>[+page.svelte]"]
  node_frontend_match["ATS match<br/>route screen<br/>[+page.svelte]"]
  node_frontend_cover_letters["Cover letters<br/>route screen<br/>[+page.svelte]"]
  node_frontend_applications["Applications<br/>route screen<br/>[+page.svelte]"]
  node_frontend_interviews["Interviews<br/>route screen<br/>[+page.svelte]"]
  node_frontend_shared["Shared UI<br/>lib layer"]
end

subgraph group_backend["Backend"]
  node_backend_main["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_router["API router<br/>v1 router<br/>[router.py]"]
  node_backend_identity_api["Identity API<br/>endpoints<br/>[auth.py]"]
  node_backend_resume_jobs_api["Resume/jobs API<br/>endpoints<br/>[resumes.py]"]
  node_backend_scoring_ai_api["Scoring/AI API<br/>endpoints<br/>[ats.py]"]
  node_backend_tracking_api["Tracking API<br/>endpoints<br/>[applications.py]"]
  node_backend_services["Domain services<br/>service layer<br/>[resume_parser.py]"]
  node_backend_modeling["AI models<br/>model abstraction<br/>[model_factory.py]"]
  node_backend_core["Core infra<br/>config/db/security<br/>[config.py]"]
  node_backend_schema_model["Schemas/models<br/>data contracts<br/>[schemas.py]"]
end

subgraph group_infra["Infra"]
  node_postgres[("PostgreSQL<br/>relational store<br/>[init.sql]")]
  node_redis[("Redis<br/>cache")]
  node_file_storage["Uploads<br/>file storage"]
  node_ai_providers(("AI providers<br/>external llm"))
end

node_frontend_shell -->|"navigates"| node_frontend_auth
node_frontend_shell -->|"navigates"| node_frontend_dashboard
node_frontend_shell -->|"navigates"| node_frontend_resumes
node_frontend_shell -->|"navigates"| node_frontend_jobs
node_frontend_shell -->|"navigates"| node_frontend_match
node_frontend_shell -->|"navigates"| node_frontend_cover_letters
node_frontend_shell -->|"navigates"| node_frontend_applications
node_frontend_shell -->|"navigates"| node_frontend_interviews
node_frontend_auth -->|"auth calls"| node_backend_identity_api
node_frontend_dashboard -->|"loads data"| node_backend_tracking_api
node_frontend_resumes -->|"uploads/edits"| node_backend_resume_jobs_api
node_frontend_jobs -->|"scrapes jobs"| node_backend_resume_jobs_api
node_frontend_match -->|"scores"| node_backend_scoring_ai_api
node_frontend_cover_letters -->|"generates"| node_backend_scoring_ai_api
node_frontend_applications -->|"tracks"| node_backend_tracking_api
node_frontend_interviews -->|"tracks"| node_backend_tracking_api
node_frontend_shared -->|"api client"| node_backend_identity_api
node_backend_main -->|"mounts"| node_backend_router
node_backend_router -->|"routes"| node_backend_identity_api
node_backend_router -->|"routes"| node_backend_resume_jobs_api
node_backend_router -->|"routes"| node_backend_scoring_ai_api
node_backend_router -->|"routes"| node_backend_tracking_api
node_backend_identity_api -->|"uses security"| node_backend_core
node_backend_resume_jobs_api -->|"delegates"| node_backend_services
node_backend_scoring_ai_api -->|"delegates"| node_backend_services
node_backend_tracking_api -->|"persists via"| node_backend_schema_model
node_backend_services -->|"calls models"| node_backend_modeling
node_backend_services -->|"shapes data"| node_backend_schema_model
node_backend_services -->|"reads/writes"| node_postgres
node_backend_core -->|"connects"| node_postgres
node_backend_core -->|"caches"| node_redis
node_backend_services -->|"stores files"| node_file_storage
node_backend_modeling -->|"invokes"| node_ai_providers

click node_frontend_shell "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/+layout.svelte"
click node_frontend_auth "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/login/+page.svelte"
click node_frontend_dashboard "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/dashboard/+page.svelte"
click node_frontend_resumes "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/resumes/+page.svelte"
click node_frontend_jobs "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/jobs/search/+page.svelte"
click node_frontend_match "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/match/+page.svelte"
click node_frontend_cover_letters "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/cover-letters/+page.svelte"
click node_frontend_applications "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/applications/+page.svelte"
click node_frontend_interviews "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/interviews/+page.svelte"
click node_backend_main "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/main.py"
click node_backend_router "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/router.py"
click node_backend_identity_api "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_backend_resume_jobs_api "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/resumes.py"
click node_backend_scoring_ai_api "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/ats.py"
click node_backend_tracking_api "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/applications.py"
click node_backend_services "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/services/resume_parser.py"
click node_backend_modeling "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/services/model_factory.py"
click node_backend_core "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/core/config.py"
click node_backend_schema_model "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/schemas/schemas.py"
click node_postgres "https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/docker/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_shell,node_frontend_auth,node_frontend_dashboard,node_frontend_resumes,node_frontend_jobs,node_frontend_match,node_frontend_cover_letters,node_frontend_applications,node_frontend_interviews,node_frontend_shared toneBlue
class node_backend_main,node_backend_router,node_backend_identity_api,node_backend_resume_jobs_api,node_backend_scoring_ai_api,node_backend_tracking_api,node_backend_services,node_backend_modeling,node_backend_core,node_backend_schema_model toneAmber
class node_postgres,node_redis,node_file_storage,node_ai_providers toneMint
```

## Components

### Frontend

SvelteKit user-facing app and workflow screens

- [App shell](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/+layout.svelte): sveltekit shell · Global layout and cross-cutting client state · `frontend/src/routes/+layout.svelte`
- [Auth pages](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/login/+page.svelte): route screens · Login and registration entry points · `frontend/src/routes/login/+page.svelte`
- [Dashboard](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/dashboard/+page.svelte): route screen · High-level user overview and navigation hub · `frontend/src/routes/dashboard/+page.svelte`
- [Resumes](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/resumes/+page.svelte): route screens · Resume upload, editing, and creation flows · `frontend/src/routes/resumes/+page.svelte`
- [Job search](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/jobs/search/+page.svelte): route screen · Job scraping and search workflow · `frontend/src/routes/jobs/search/+page.svelte`
- [ATS match](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/match/+page.svelte): route screen · Resume-to-job scoring and recommendations · `frontend/src/routes/match/+page.svelte`
- [Cover letters](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/cover-letters/+page.svelte): route screen · Generated letter review and editing · `frontend/src/routes/cover-letters/+page.svelte`
- [Applications](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/applications/+page.svelte): route screen · Application tracking workspace · `frontend/src/routes/applications/+page.svelte`
- [Interviews](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/frontend/src/routes/interviews/+page.svelte): route screen · Interview tracking and follow-up workflow · `frontend/src/routes/interviews/+page.svelte`
- **Shared UI**: lib layer · Reusable components, client services, and auth state

### Backend

FastAPI API, services, and domain layer

- [Main app](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/main.py): FastAPI entrypoint · Application bootstrap and server startup · `backend/app/main.py`
- [API router](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/router.py): v1 router · Composes versioned API endpoints · `backend/app/api/v1/router.py`
- [Identity API](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/auth.py): endpoints · Auth and user management endpoints · `backend/app/api/v1/endpoints/auth.py`
- [Resume/jobs API](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/resumes.py): endpoints · Resume ingestion and job scraping endpoints · `backend/app/api/v1/endpoints/resumes.py`
- [Scoring/AI API](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/ats.py): endpoints · ATS scoring and AI generation endpoints · `backend/app/api/v1/endpoints/ats.py`
- [Tracking API](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/api/v1/endpoints/applications.py): endpoints · Applications and interviews endpoints · `backend/app/api/v1/endpoints/applications.py`
- [Domain services](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/services/resume_parser.py): service layer · Resume parsing, scraping, scoring, and generation logic · `backend/app/services/resume_parser.py`
- [AI models](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/services/model_factory.py): model abstraction · Provider factory and custom model integration · `backend/app/services/model_factory.py`
- [Core infra](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/core/config.py): config/db/security · Settings, database sessions, and JWT helpers · `backend/app/core/config.py`
- [Schemas/models](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/backend/app/schemas/schemas.py): data contracts · Pydantic schemas and persistence models · `backend/app/schemas/schemas.py`

### Infra

Datastores, storage, and deployment/runtime

- [PostgreSQL](https://github.com/mahmudul-islam32/ai-resume-builder/blob/main/docker/init.sql): relational store · Durable application data and artifacts · `docker/init.sql`
- **Redis**: cache · Ephemeral state and caching layer
- **Uploads**: file storage · Resume files and generated documents
- **AI providers**: external llm · OpenAI and local Ollama-style model backends

## Connections

- App shell → Auth pages: navigates · Shell routes users into auth flows
- App shell → Dashboard: navigates · Shell exposes the main dashboard
- App shell → Resumes: navigates · Shell exposes resume workflows
- App shell → Job search: navigates · Shell exposes job search workflows
- App shell → ATS match: navigates · Shell exposes ATS analysis views
- App shell → Cover letters: navigates · Shell exposes generated letter workflows
- App shell → Applications: navigates · Shell exposes tracking views
- App shell → Interviews: navigates · Shell exposes interview tracking views
- Auth pages → Identity API: auth calls · Login and registration submit credentials
- Dashboard → Tracking API: loads data · Dashboard aggregates tracked workflow data
- Resumes → Resume/jobs API: uploads/edits · Resume editor sends files and structured content
- Job search → Resume/jobs API: scrapes jobs · Job search submits URLs for extraction
- ATS match → Scoring/AI API: scores · Match view requests ATS analysis
- Cover letters → Scoring/AI API: generates · Cover letter workflow requests AI output
- Applications → Tracking API: tracks · Application records are created and updated
- Interviews → Tracking API: tracks · Interview records are created and updated
- Shared UI → Identity API: api client · Shared client services wrap backend calls
- Main app → API router: mounts · Main app includes the versioned router
- API router → Identity API: routes · Router exposes auth and user endpoints
- API router → Resume/jobs API: routes · Router exposes resume and job endpoints
- API router → Scoring/AI API: routes · Router exposes ATS and AI endpoints
- API router → Tracking API: routes · Router exposes application and interview endpoints
- Identity API → Core infra: uses security · Identity endpoints depend on JWT and config
- Resume/jobs API → Domain services: delegates · Upload and scraping work is handled in services
- Scoring/AI API → Domain services: delegates · Scoring and generation delegate to service layer
- Tracking API → Schemas/models: persists via · Tracking endpoints exchange typed records
- Domain services → AI models: calls models · AI and custom model work is abstracted behind factories
- Domain services → Schemas/models: shapes data · Services return structured schemas and domain objects
- Domain services → PostgreSQL: reads/writes · Persistent workflow data is stored in the database
- Core infra → PostgreSQL: connects · Database engine and sessions are configured here
- Core infra → Redis: caches · Core infrastructure can use Redis for ephemeral state
- Domain services → Uploads: stores files · Uploads and generated artifacts are managed as files
- AI models → AI providers: invokes · Provider abstraction switches between hosted and local LLMs