# tamim662/ai-job-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/tamim662/ai-job-tracker
- Repository: https://github.com/tamim662/ai-job-tracker

## Overview

1. This is a two-tier single-user application: a Spring Boot 3.3 backend in `backend/` and a React 18 + Vite frontend in `frontend/`. The frontend is a browser client; the backend is the only API server and owns all business logic, persistence, security, and external API calls.

2. The backend is organized by classic layered boundaries: `controller` exposes REST endpoints, `service` contains orchestration and integration logic, `repository` handles Spring Data JPA access, `entity` defines the database model, and `dto` shapes request/response payloads. `JobTrackerApplication` is the Spring Boot entry point.

3. Authentication is intentionally simple and state-free. `AuthController` plus `JwtUtil` and `JwtAuthFilter` implement JWT-based login for a single set of credentials from environment variables. `SecurityConfig` and `CorsConfig` define the protected API surface and browser access rules; there is no public registration or multi-tenant user model.

4. The core domain is the job pipeline stored in PostgreSQL through JPA and Flyway. Main entities include `Job`, `Application`, `Resume`, `CoverLetter`, `GeneratedMessage`, `JobMatch`, `CompanyResearch`, and `UserProfile`. Flyway migrations in `src/main/resources/db/migration` create and evolve the schema, including later additions for company research and profile templates.

5. The main user workflow starts with profile and document setup. `ResumeController` and `CoverLetterController` manage uploaded source documents, while `UserProfileController` stores the user’s identity, job preferences, and default outreach templates. These saved inputs become the source material for all later AI-generated content.

6. Job discovery is split into structured search and broader web search. `JobSearchController` and `AdzunaService` query Adzuna for Australia-specific listings, while `TavilyService` supports web search across sites like Seek, LinkedIn, and Indeed. The backend returns paginated search DTOs, and the frontend renders them on the Jobs page.

7. Matching and ATS analysis are a distinct subsystem. `KeywordMatcher` performs local resume-to-job keyword scoring for instant match percentages, while `AtsMatchService` performs a deeper analysis using Groq. This separation means the app can show immediate local scoring without an API call, then run a heavier scan only when the user starts an application.

8. The “apply” flow is centered on job persistence and generated artifacts. `JobController` saves selected jobs into the user’s job list, updates status transitions, and exposes details for the My Jobs view. From there, `MessageController` and `CoverLetterController` generate job-specific outreach or application text, and `GeneratedMessage` records those outputs for later reuse.

9. AI integrations are split by purpose rather than by vendor. `ClaudeService` is used for adapted writing tasks like cover letters, HR emails, LinkedIn messages, and company research synthesis. `GroqService` handles ATS-style scoring and gap analysis. `CompanyResearchService` and `MessageGenerationService` orchestrate these calls and turn raw model output into structured DTOs.

10. File ingestion and storage are handled separately from text processing. `FileParserService` extracts text from uploaded PDF/DOCX files, `S3Service` manages optional object storage, and `S3Config` wires the AWS bucket settings. The extracted text feeds matching and AI generation; the stored file itself is preserved externally when S3 is enabled.

11. The frontend is a routed SPA with a small auth state boundary. `AuthContext` holds login state, `PrivateRoute` protects authenticated views, and `axios.js` centralizes API access with JWT handling. Pages map closely to backend domains: Dashboard, Jobs, Resumes, Cover Letters, and Profile, with `ApplyModal` acting as the main workflow surface for job actions.

12. The dashboard and jobs views are the two main operational surfaces. Dashboard aggregates stats from the backend into pipeline counts and recent activity, while Jobs drives search, save/apply actions, status updates, ATS results, and generated message access. This creates a single end-to-end flow from discovery to application tracking.

13. Infrastructure is meant to be self-hosted and mostly local. PostgreSQL runs via `docker-compose.yml` or AWS RDS, backend configuration comes from `.env` / `application.yml`, and optional S3 is used for document storage. External dependencies are limited to the needed APIs: Anthropic, Groq, Adzuna, and Tavily.

14. Tests mirror the main architectural boundaries. Backend controller tests cover the API layer, and service tests such as `FileParserServiceTest` validate key non-HTTP logic. That suggests the repo’s main correctness boundaries are the REST contract, the document parsing pipeline, and the AI/job orchestration services.

Main entry points: [`frontend/src/App.jsx`](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/App.jsx) (App shell), [`backend/src/main/java/com/jobtracker/service/JobService.java`](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/service/JobService.java) (Services), [`backend/src/main/java/com/jobtracker/controller/JobController.java`](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/controller/JobController.java) (REST API), [`backend/src/main/java/com/jobtracker/JobTrackerApplication.java`](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/JobTrackerApplication.java) (Spring Boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react spa<br/>[App.jsx]"]
  node_frontend_auth(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_frontend_api["API client<br/>axios client<br/>[axios.js]"]
  node_frontend_dashboard["Dashboard<br/>page<br/>[DashboardPage.jsx]"]
  node_frontend_jobs["Jobs<br/>page<br/>[JobsPage.jsx]"]
  node_frontend_profile["Profile<br/>page<br/>[ProfilePage.jsx]"]
  node_frontend_docs["Docs pages<br/>[ResumesPage.jsx]"]
  node_frontend_apply["Apply modal<br/>workflow ui<br/>[ApplyModal.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_boot(("Spring Boot<br/>entrypoint"))
  node_backend_config["Config<br/>[CorsConfig.java]"]
  node_backend_auth["Auth stack<br/>jwt security<br/>[JwtAuthFilter.java]"]
  node_backend_controllers["REST API<br/>controllers<br/>[JobController.java]"]
  node_backend_services["Services<br/>service layer<br/>[JobService.java]"]
  node_backend_match{{"Matching<br/>scoring"}}
  node_backend_domain[("Domain model<br/>entities and repos<br/>[Job.java]")]
  node_backend_dto["DTOs<br/>payload model<br/>[JobDto.java]"]
end

subgraph group_infra["Infrastructure"]
  node_infra_db[("PostgreSQL<br/>database")]
  node_infra_migrations["Flyway<br/>migrations"]
  node_infra_external{{"External APIs<br/>providers"}}
end

node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"routes"| node_frontend_dashboard
node_frontend_app -->|"routes"| node_frontend_jobs
node_frontend_app -->|"routes"| node_frontend_profile
node_frontend_app -->|"routes"| node_frontend_docs
node_frontend_jobs -->|"opens"| node_frontend_apply
node_frontend_api -->|"HTTP"| node_backend_controllers
node_backend_boot -->|"wires"| node_backend_config
node_backend_boot -->|"wires"| node_backend_auth
node_backend_boot -->|"starts"| node_backend_controllers
node_backend_controllers -->|"delegates"| node_backend_services
node_backend_controllers -->|"protected by"| node_backend_auth
node_backend_services -->|"reads/writes"| node_backend_domain
node_backend_services -->|"maps"| node_backend_dto
node_backend_services -->|"scores"| node_backend_match
node_backend_services -->|"calls"| node_infra_external
node_backend_services -->|"persists"| node_infra_db
node_backend_domain -->|"maps to"| node_infra_db
node_infra_migrations -->|"evolves"| node_infra_db

click node_frontend_app "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/App.jsx"
click node_frontend_auth "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_frontend_api "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/api/axios.js"
click node_frontend_dashboard "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_frontend_jobs "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/JobsPage.jsx"
click node_frontend_profile "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/ProfilePage.jsx"
click node_frontend_docs "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/ResumesPage.jsx"
click node_frontend_apply "https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/components/ApplyModal.jsx"
click node_backend_boot "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/JobTrackerApplication.java"
click node_backend_config "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/config/CorsConfig.java"
click node_backend_auth "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/security/JwtAuthFilter.java"
click node_backend_controllers "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/controller/JobController.java"
click node_backend_services "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/service/JobService.java"
click node_backend_match "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/util/KeywordMatcher.java"
click node_backend_domain "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/entity/Job.java"
click node_backend_dto "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/dto/JobDto.java"
click node_infra_db "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/resources/db/migration/V1__init_schema.sql"
click node_infra_migrations "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/resources/db/migration/V2__add_company_research.sql"
click node_infra_external "https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/config/AnthropicConfig.java"

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_auth,node_frontend_api,node_frontend_dashboard,node_frontend_jobs,node_frontend_profile,node_frontend_docs,node_frontend_apply toneBlue
class node_backend_boot,node_backend_config,node_backend_auth,node_backend_controllers,node_backend_services,node_backend_match,node_backend_domain,node_backend_dto toneAmber
class node_infra_db,node_infra_migrations,node_infra_external toneMint
```

## Components

### Frontend

React browser client and routed UI

- [App shell](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/App.jsx): react spa · Routed browser client · `frontend/src/App.jsx`
- [Auth state](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/contexts/AuthContext.jsx): context · Login state and route protection · `frontend/src/contexts/AuthContext.jsx`
- [API client](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/api/axios.js): axios client · JWT-aware backend access · `frontend/src/api/axios.js`
- [Dashboard](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/DashboardPage.jsx): page · Pipeline summary and recent activity · `frontend/src/pages/DashboardPage.jsx`
- [Jobs](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/JobsPage.jsx): page · Search, save, and apply workflow · `frontend/src/pages/JobsPage.jsx`
- [Profile](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/ProfilePage.jsx): page · Identity, preferences, and templates · `frontend/src/pages/ProfilePage.jsx`
- [Docs pages](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/pages/ResumesPage.jsx): pages · Resume and cover-letter views · `frontend/src/pages/ResumesPage.jsx`
- [Apply modal](https://github.com/tamim662/ai-job-tracker/blob/main/frontend/src/components/ApplyModal.jsx): workflow ui · Job action surface · `frontend/src/components/ApplyModal.jsx`

### Backend

Spring Boot API, domain logic, and persistence

- [Spring Boot](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/JobTrackerApplication.java): entrypoint · Application bootstrap · `backend/src/main/java/com/jobtracker/JobTrackerApplication.java`
- [Config](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/config/CorsConfig.java): app config · CORS, REST client, Anthropic, and S3 wiring · `backend/src/main/java/com/jobtracker/config/CorsConfig.java`
- [Auth stack](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/security/JwtAuthFilter.java): jwt security · Login endpoint and JWT filter/util · `backend/src/main/java/com/jobtracker/security/JwtAuthFilter.java`
- [REST API](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/controller/JobController.java): controllers · Endpoints for jobs, documents, profile, search, and AI actions · `backend/src/main/java/com/jobtracker/controller/JobController.java`
- [Services](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/service/JobService.java): service layer · Orchestration, integrations, and document workflows · `backend/src/main/java/com/jobtracker/service/JobService.java`
- [Matching](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/util/KeywordMatcher.java): scoring · Local keyword scoring and ATS analysis · `backend/src/main/java/com/jobtracker/util/KeywordMatcher.java`
- [Domain model](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/entity/Job.java): entities and repos · Jobs, applications, resumes, messages, profiles, and research · `backend/src/main/java/com/jobtracker/entity/Job.java`
- [DTOs](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/dto/JobDto.java): payload model · Request and response shapes · `backend/src/main/java/com/jobtracker/dto/JobDto.java`

### Infrastructure

Database, migrations, and external integrations

- [PostgreSQL](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/resources/db/migration/V1__init_schema.sql): database · Primary persistence store · `backend/src/main/resources/db/migration/V1__init_schema.sql`
- [Flyway](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/resources/db/migration/V2__add_company_research.sql): migrations · Schema evolution for research and profile templates · `backend/src/main/resources/db/migration/V2__add_company_research.sql`
- [External APIs](https://github.com/tamim662/ai-job-tracker/blob/main/backend/src/main/java/com/jobtracker/config/AnthropicConfig.java): providers · Anthropic, Groq, Adzuna, Tavily, and optional S3 · `backend/src/main/java/com/jobtracker/config/AnthropicConfig.java`

## Connections

- App shell → Auth state: uses · UI gates authenticated routes
- App shell → API client: calls · Browser requests go through shared client
- App shell → Dashboard: routes · Main operational surface
- App shell → Jobs: routes · Search and application workflow
- App shell → Profile: routes · Profile and template management
- App shell → Docs pages: routes · Resume and cover-letter pages
- Jobs → Apply modal: opens · Job actions are centered here
- API client → REST API: HTTP · Authenticated API access
- Spring Boot → Config: wires · Bootstraps application configuration
- Spring Boot → Auth stack: wires · Bootstraps security
- Spring Boot → REST API: starts · Exposes REST surface
- REST API → Services: delegates · Controllers hand off orchestration
- REST API → Auth stack: protected by · JWT login and protected API surface
- Services → Domain model: reads/writes · Persists jobs, profiles, documents, and results
- Services → DTOs: maps · Transforms request and response payloads
- Services → Matching: scores · Uses local and AI-backed job matching
- Services → External APIs: calls · Claude, Groq, job search, and web research providers
- Services → PostgreSQL: persists · Stores tracked jobs and generated artifacts
- Domain model → PostgreSQL: maps to · JPA entities map to PostgreSQL
- Flyway → PostgreSQL: evolves · Flyway creates and updates schema