tamim662/ai-job-tracker

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.