How srbhr/resume-matcher works
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: app Next.js app · services Domain services · routers Routers · page.tsx Builder
Components 26
Frontend
Next.js app for resume editing, tailoring, preview, and print flows.
- Next.js app · App Router frontend that orchestrates the user experience.
apps/frontend/app - Home · Landing page experience and entry point.
apps/frontend/app/(default)/page.tsx - Dashboard · Resume list and upload entry flow.
apps/frontend/app/(default)/dashboard/page.tsx - Builder · Structured resume editing and regeneration workspace.
apps/frontend/app/(default)/builder/page.tsx - Tailor · Job-match and enrichment workspace.
apps/frontend/app/(default)/tailor/page.tsx - Settings · Provider and app configuration screen.
apps/frontend/app/(default)/settings/page.tsx - Print views · Dedicated print routes for resumes and cover letters.
apps/frontend/app/print - Builder UI · Forms, regeneration dialogs, drag-and-drop, and template selection.
apps/frontend/components/builder - Enrichment UI · Modal-driven workflow for collecting context and previewing enrichment.
apps/frontend/components/enrichment - Preview layer · Paginated preview and print container used for render/export flows.
apps/frontend/components/preview - Resume renderers · Template-driven resume layouts for preview and print.
apps/frontend/components/resume - API client · Typed client and feature-specific API wrappers for backend calls.
apps/frontend/lib/api - State & hooks · 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 · Backend application entry point and integration boundary.
apps/backend/app - Routers · Health, config, jobs, resumes, and enrichment endpoints.
apps/backend/app/routers - Domain services · Parser, improver, refiner, and cover-letter generation workflows.
apps/backend/app/services - Prompts · Prompt templates and builders for enrichment and refinement tasks.
apps/backend/app/prompts - Schemas · Pydantic models for resumes, enrichment, and refinement payloads.
apps/backend/app/schemas - LLM adapter · LiteLLM-based abstraction for model/provider access.
apps/backend/app/llm.py - PDF export · PDF generation support for printable resume and cover-letter output.
apps/backend/app/pdf.py - Local data · TinyDB-style JSON persistence for app data and config.
apps/backend/data
Docs & assets
Architecture notes, design specs, and reference assets.
- Architecture docs · Backend, frontend, workflow, and prompt architecture guidance.
docs/agent/architecture - Design specs · Template, print, and PDF design specifications.
docs/agent/design - PDF templates · Reference PDF templates used for layout and export validation.
assets/pdf-templates
Deploy
Containerization and CI/CD entry points.
- Docker setup · Container build and local compose orchestration.
Dockerfile - CI publish · GitHub Actions workflow for building and publishing images.
.github/workflows/docker-publish.yml
Connections 29
- 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.