# srbhr/resume-matcher architecture

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

- Interactive diagram: https://gitdiagram.com/srbhr/resume-matcher
- Repository: https://github.com/srbhr/resume-matcher

## Overview

1. **Overall shape**
   - This is a two-app monorepo: a **Next.js/React frontend** in `apps/frontend` and a **FastAPI backend** in `apps/backend`.
   - Supporting material lives in `docs/` and `assets/`, while deployment is containerized via `Dockerfile`, `docker-compose.yml`, and GitHub Actions.

2. **Frontend as the user-facing orchestration layer**
   - The frontend is a Next.js 16 app using the App Router, with main experiences for **home**, **dashboard**, **resume builder**, **job tailoring**, **settings**, and **print/export**.
   - Key routes include resume detail pages, builder pages, and dedicated print routes for resumes and cover letters.
   - UI state is spread across React components, custom hooks, and contexts, with reusable component sets for builder, enrichment, preview, and resume rendering.

3. **Backend as the API and AI workflow engine**
   - The backend is a FastAPI service exposing routers for **health**, **config**, **jobs**, **resumes**, and **enrichment**.
   - It provides the server-side API used by the frontend, plus the domain logic for parsing resumes, generating improvements, and managing AI-driven tailoring flows.
   - OpenAPI/Swagger is part of the backend surface, which makes the backend the clear integration boundary.

4. **Core domain model**
   - The repository centers on a few domain objects: **master resumes**, **job descriptions**, **tailored resume variants**, **cover letters**, **enrichment results**, and **regeneration/diff outputs**.
   - Backend schemas under `app/schemas` define the API contracts; the frontend mirrors these with TypeScript types and UI-specific models.
   - This shared structure is what allows the builder, scoring, preview, and print screens to operate on the same resume data.

5. **Resume ingestion and parsing flow**
   - A user uploads a resume in the dashboard/builder flow.
   - The backend parsing service converts the uploaded document into structured resume data that can be edited section-by-section in the UI.
   - That parsed structure becomes the “master resume” from which tailored versions are generated.

6. **AI tailoring and refinement pipeline**
   - The backend’s `llm.py` abstracts access to LLM providers through **LiteLLM**, so the app can target local or cloud models.
   - Prompt templates and prompt builders live under `app/prompts`, with separate flows for **enrichment**, **refinement**, and related generation tasks.
   - Services like `improver`, `refiner`, and `cover_letter` encapsulate the business logic for turning a resume plus job description into tailored content.

7. **Job-description matching and enrichment**
   - The “tailor” and “enrichment” experiences are centered on comparing a resume against a job description, surfacing keyword gaps, suggestions, and match-oriented guidance.
   - The frontend has specialized comparison/highlight views and a modal-based enrichment wizard to collect additional context before generation.
   - This is a distinct flow from plain editing: it is optimization against a target job, not just resume authoring.

8. **Resume builder and regeneration UX**
   - The builder UI supports structured section editing, drag-and-drop reordering, template selection, and rich-text editing.
   - Regeneration is diff-oriented: the frontend has dialogs and previews for proposed changes, while the backend validates and applies diffs.
   - This creates a loop of “generate → review diff → accept or edit,” which is a major interaction boundary in the system.

9. **Rendering and PDF export**
   - Resume and cover-letter rendering is template-driven, with multiple layouts such as classic and modern single/two-column variants.
   - The frontend includes dedicated preview and print routes, while the backend includes PDF support and the project uses **Playwright/headless Chromium** for export generation.
   - The rendering layer is separated from data editing so the same content can be previewed, printed, or exported consistently.

10. **Persistence and local data boundary**
   - Persistent application data is stored locally using **TinyDB**-style JSON storage under `apps/backend/data`.
   - This means the product is designed to work as a local-first tool, with the backend acting as the source of truth for resumes, jobs, and user configuration.
   - The data boundary is intentionally lightweight compared with a traditional SQL-backed SaaS.

11. **Configuration and provider setup**
   - Provider credentials and runtime settings are managed through the backend config routes and cached config helpers.
   - The frontend settings screen is where users choose or update their AI provider setup, which can point to Ollama or hosted LLM APIs.
   - This separates user-facing configuration from the generation pipeline while keeping provider selection dynamic.

12. **Internationalization**
   - The frontend has built-in i18n support with message bundles for English, Spanish, Japanese, Simplified Chinese, and Portuguese (Brazil).
   - The architecture supports both translated UI chrome and localized content generation paths, which matters for tailoring outputs, not just labels.

13. **Testing and quality boundaries**
   - Backend behavior is covered by unit and integration tests, especially around resume diffs, refiner logic, jobs, health, and resume APIs.
   - Frontend behavior is covered with Vitest tests for interactive UI flows like diff previews and regenerate wizards.
   - These tests mirror the key architectural seams: API correctness, generation logic, and user-review interactions.

14. **Deployment model**
   - The repo is built for local development with separate frontend/backend processes, but also for a single-container deployment where the app is served on one public port and the API is exposed under `/api`.
   - GitHub Actions publish Docker images, and the repo documents both local and containerized setups.
   - The main external dependencies are the chosen LLM provider, the browser runtime for PDF generation, and optional Ollama for local inference.

Main entry points: [`apps/frontend/app`](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/app) (Next.js app), [`apps/backend/app/services`](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/services) (Domain services), [`apps/backend/app/routers`](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/routers) (Routers), [`apps/frontend/app/(default)/builder/page.tsx`](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/builder/page.tsx) (Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>ui shell"]
  node_frontend_home["Home<br/>route<br/>[page.tsx]"]
  node_frontend_dashboard["Dashboard<br/>route<br/>[page.tsx]"]
  node_frontend_builder["Builder<br/>route<br/>[page.tsx]"]
  node_frontend_tailor["Tailor<br/>route<br/>[page.tsx]"]
  node_frontend_settings["Settings<br/>route<br/>[page.tsx]"]
  node_frontend_print["Print views<br/>routes"]
  node_frontend_builder_components["Builder UI<br/>components"]
  node_frontend_enrichment["Enrichment UI<br/>components"]
  node_frontend_preview["Preview layer<br/>components"]
  node_frontend_resume_renderers["Resume renderers<br/>templates"]
  node_frontend_api["API client<br/>data access"]
  node_frontend_state["State & hooks"]
end

subgraph group_backend["Backend"]
  node_backend_app["FastAPI app<br/>api shell"]
  node_backend_routers["Routers<br/>http api"]
  node_backend_services["Domain services<br/>business logic"]
  node_backend_prompts["Prompts<br/>prompt system"]
  node_backend_schemas["Schemas<br/>contracts"]
  node_backend_llm["LLM adapter<br/>provider layer<br/>[llm.py]"]
  node_backend_pdf["PDF export<br/>render/export<br/>[pdf.py]"]
  node_backend_data[("Local data<br/>storage")]
end

subgraph group_docs["Docs & assets"]
  node_docs_arch["Architecture docs"]
  node_docs_design["Design specs<br/>docs"]
  node_assets_templates["PDF templates<br/>assets"]
end

subgraph group_deploy["Deploy"]
  node_deploy_docker["Docker setup<br/>deployment"]
  node_deploy_ci["CI publish<br/>ci/cd<br/>[docker-publish.yml]"]
end

node_frontend_app -->|"routes to"| node_frontend_home
node_frontend_app -->|"routes to"| node_frontend_dashboard
node_frontend_app -->|"routes to"| node_frontend_builder
node_frontend_app -->|"routes to"| node_frontend_tailor
node_frontend_app -->|"routes to"| node_frontend_settings
node_frontend_app -->|"routes to"| node_frontend_print
node_frontend_builder -->|"uses"| node_frontend_builder_components
node_frontend_tailor -->|"uses"| node_frontend_enrichment
node_frontend_builder -->|"renders via"| node_frontend_preview
node_frontend_print -->|"renders with"| node_frontend_resume_renderers
node_frontend_preview -->|"reuses"| node_frontend_resume_renderers
node_frontend_state -->|"supports"| node_frontend_builder_components
node_frontend_api -->|"calls"| node_backend_routers
node_frontend_api -.->|"maps to"| node_backend_schemas
node_backend_app -->|"mounts"| node_backend_routers
node_backend_routers -->|"delegates to"| node_backend_services
node_backend_services -->|"builds"| node_backend_prompts
node_backend_services -->|"uses"| node_backend_llm
node_backend_services -->|"returns"| node_backend_schemas
node_backend_services -->|"persists"| node_backend_data
node_backend_routers -->|"reads/writes"| node_backend_data
node_backend_pdf -.->|"validated by"| node_assets_templates
node_frontend_print -->|"requests export"| node_backend_pdf
node_docs_arch -.->|"documents"| node_frontend_app
node_docs_arch -.->|"documents"| node_backend_app
node_docs_design -.->|"specifies"| node_frontend_resume_renderers
node_deploy_docker -->|"packages"| node_frontend_app
node_deploy_docker -->|"packages"| node_backend_app
node_deploy_ci -->|"publishes"| node_deploy_docker

click node_frontend_app "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/app"
click node_frontend_home "https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/page.tsx"
click node_frontend_dashboard "https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/dashboard/page.tsx"
click node_frontend_builder "https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/builder/page.tsx"
click node_frontend_tailor "https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/tailor/page.tsx"
click node_frontend_settings "https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/settings/page.tsx"
click node_frontend_print "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/app/print"
click node_frontend_builder_components "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/builder"
click node_frontend_enrichment "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/enrichment"
click node_frontend_preview "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/preview"
click node_frontend_resume_renderers "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/resume"
click node_frontend_api "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/lib/api"
click node_frontend_state "https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/hooks"
click node_backend_app "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app"
click node_backend_routers "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/routers"
click node_backend_services "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/services"
click node_backend_prompts "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/prompts"
click node_backend_schemas "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/schemas"
click node_backend_llm "https://github.com/srbhr/resume-matcher/blob/main/apps/backend/app/llm.py"
click node_backend_pdf "https://github.com/srbhr/resume-matcher/blob/main/apps/backend/app/pdf.py"
click node_backend_data "https://github.com/srbhr/resume-matcher/tree/main/apps/backend/data"
click node_docs_arch "https://github.com/srbhr/resume-matcher/tree/main/docs/agent/architecture"
click node_docs_design "https://github.com/srbhr/resume-matcher/tree/main/docs/agent/design"
click node_assets_templates "https://github.com/srbhr/resume-matcher/tree/main/assets/pdf-templates"
click node_deploy_docker "https://github.com/srbhr/resume-matcher/tree/main/Dockerfile"
click node_deploy_ci "https://github.com/srbhr/resume-matcher/blob/main/.github/workflows/docker-publish.yml"

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_app,node_frontend_home,node_frontend_dashboard,node_frontend_builder,node_frontend_tailor,node_frontend_settings,node_frontend_print,node_frontend_builder_components,node_frontend_enrichment,node_frontend_preview,node_frontend_resume_renderers,node_frontend_api,node_frontend_state toneBlue
class node_backend_app,node_backend_routers,node_backend_services,node_backend_prompts,node_backend_schemas,node_backend_llm,node_backend_pdf,node_backend_data toneAmber
class node_docs_arch,node_docs_design,node_assets_templates toneMint
class node_deploy_docker,node_deploy_ci toneRose
```

## Components

### Frontend

Next.js app for resume editing, tailoring, preview, and print flows.

- [Next.js app](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/app): ui shell · App Router frontend that orchestrates the user experience. · `apps/frontend/app`
- [Home](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/page.tsx): route · Landing page experience and entry point. · `apps/frontend/app/(default)/page.tsx`
- [Dashboard](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/dashboard/page.tsx): route · Resume list and upload entry flow. · `apps/frontend/app/(default)/dashboard/page.tsx`
- [Builder](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/builder/page.tsx): route · Structured resume editing and regeneration workspace. · `apps/frontend/app/(default)/builder/page.tsx`
- [Tailor](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/tailor/page.tsx): route · Job-match and enrichment workspace. · `apps/frontend/app/(default)/tailor/page.tsx`
- [Settings](https://github.com/srbhr/resume-matcher/blob/main/apps/frontend/app/(default)/settings/page.tsx): route · Provider and app configuration screen. · `apps/frontend/app/(default)/settings/page.tsx`
- [Print views](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/app/print): routes · Dedicated print routes for resumes and cover letters. · `apps/frontend/app/print`
- [Builder UI](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/builder): components · Forms, regeneration dialogs, drag-and-drop, and template selection. · `apps/frontend/components/builder`
- [Enrichment UI](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/enrichment): components · Modal-driven workflow for collecting context and previewing enrichment. · `apps/frontend/components/enrichment`
- [Preview layer](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/preview): components · Paginated preview and print container used for render/export flows. · `apps/frontend/components/preview`
- [Resume renderers](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/components/resume): templates · Template-driven resume layouts for preview and print. · `apps/frontend/components/resume`
- [API client](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/lib/api): data access · Typed client and feature-specific API wrappers for backend calls. · `apps/frontend/lib/api`
- [State & hooks](https://github.com/srbhr/resume-matcher/tree/main/apps/frontend/hooks): state · Custom hooks and shared contexts for upload, regeneration, language, and preview state. · `apps/frontend/hooks`

### Backend

FastAPI service for API, parsing, AI workflows, and persistence.

- [FastAPI app](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app): api shell · Backend application entry point and integration boundary. · `apps/backend/app`
- [Routers](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/routers): http api · Health, config, jobs, resumes, and enrichment endpoints. · `apps/backend/app/routers`
- [Domain services](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/services): business logic · Parser, improver, refiner, and cover-letter generation workflows. · `apps/backend/app/services`
- [Prompts](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/prompts): prompt system · Prompt templates and builders for enrichment and refinement tasks. · `apps/backend/app/prompts`
- [Schemas](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/app/schemas): contracts · Pydantic models for resumes, enrichment, and refinement payloads. · `apps/backend/app/schemas`
- [LLM adapter](https://github.com/srbhr/resume-matcher/blob/main/apps/backend/app/llm.py): provider layer · LiteLLM-based abstraction for model/provider access. · `apps/backend/app/llm.py`
- [PDF export](https://github.com/srbhr/resume-matcher/blob/main/apps/backend/app/pdf.py): render/export · PDF generation support for printable resume and cover-letter output. · `apps/backend/app/pdf.py`
- [Local data](https://github.com/srbhr/resume-matcher/tree/main/apps/backend/data): storage · TinyDB-style JSON persistence for app data and config. · `apps/backend/data`

### Docs & assets

Architecture notes, design specs, and reference assets.

- [Architecture docs](https://github.com/srbhr/resume-matcher/tree/main/docs/agent/architecture): docs · Backend, frontend, workflow, and prompt architecture guidance. · `docs/agent/architecture`
- [Design specs](https://github.com/srbhr/resume-matcher/tree/main/docs/agent/design): docs · Template, print, and PDF design specifications. · `docs/agent/design`
- [PDF templates](https://github.com/srbhr/resume-matcher/tree/main/assets/pdf-templates): assets · Reference PDF templates used for layout and export validation. · `assets/pdf-templates`

### Deploy

Containerization and CI/CD entry points.

- [Docker setup](https://github.com/srbhr/resume-matcher/tree/main/Dockerfile): deployment · Container build and local compose orchestration. · `Dockerfile`
- [CI publish](https://github.com/srbhr/resume-matcher/blob/main/.github/workflows/docker-publish.yml): ci/cd · GitHub Actions workflow for building and publishing images. · `.github/workflows/docker-publish.yml`

## Connections

- Next.js app → Home: routes to · Top-level landing route.
- Next.js app → Dashboard: routes to · Dashboard entry and upload flow.
- Next.js app → Builder: routes to · Resume editing workspace.
- Next.js app → Tailor: routes to · Job tailoring workspace.
- Next.js app → Settings: routes to · Provider and app settings.
- Next.js app → Print views: routes to · Print/export routes.
- Builder → Builder UI: uses · Builder page is composed from specialized UI pieces.
- Tailor → Enrichment UI: uses · Tailor flow drives enrichment wizard UI.
- Builder → Preview layer: renders via · Builder reviews content with preview surfaces.
- Print views → Resume renderers: renders with · Print routes rely on template renderers.
- Preview layer → Resume renderers: reuses · Preview and print share presentation templates.
- State & hooks → Builder UI: supports · Hooks and contexts coordinate builder interactions.
- API client → Routers: calls · Frontend talks to backend HTTP endpoints.
- API client → Schemas: maps to · Client models mirror backend contracts.
- FastAPI app → Routers: mounts · FastAPI app exposes feature routers.
- Routers → Domain services: delegates to · HTTP handlers invoke domain workflows.
- Domain services → Prompts: builds · Generation services assemble prompts.
- Domain services → LLM adapter: uses · Services call the provider abstraction.
- Domain services → Schemas: returns · Structured API payloads and domain models.
- Domain services → Local data: persists · Domain state is stored locally.
- Routers → Local data: reads/writes · Config and resume APIs access storage.
- PDF export → PDF templates: validated by · Export behavior aligns with reference templates.
- Print views → PDF export: requests export · Print flows depend on backend PDF generation.
- Architecture docs → Next.js app: documents · Frontend architecture and workflow guidance.
- Architecture docs → FastAPI app: documents · Backend architecture and API design guidance.
- Design specs → Resume renderers: specifies · Template and layout documentation informs renderers.
- Docker setup → Next.js app: packages · Container builds include the frontend app.
- Docker setup → FastAPI app: packages · Container builds include the backend service.
- CI publish → Docker setup: publishes · CI builds and publishes container images.
