mahmudul-islam32/ai-resume-builder

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.