# cagedbear83/job-tracker architecture

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

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

## Overview

1. **System shape**
   - This repository is a full-stack unemployment insurance work-tracker with two primary runtime surfaces: a FastAPI backend in `APP/backend` and a React/Tailwind frontend in `APP/frontend`.
   - Persistence is in MongoDB, accessed asynchronously from the backend.

2. **Backend as the application core**
   - The backend entrypoint is `APP/backend/server.py`.
   - It owns API routing, authentication, authorization, validation, persistence, scheduling, and external integrations.
   - The backend is also where health checks, admin protections, and production security controls live.

3. **Frontend as a single-page application**
   - The frontend is a client-rendered React app built with Tailwind and a component library set under `src/components/ui`.
   - It uses route-level pages such as login, dashboard, claimants, benefit weeks, import, audit, profile, password reset, and legal pages.
   - `src/context/AuthContext.jsx` and `src/lib/tokenStorage.js` indicate the frontend manages session state locally and sends JWT-backed requests to the backend.

4. **Authentication and access boundaries**
   - User authentication is JWT-based, with role-aware protection for admin routes.
   - The backend enforces privileged access on admin functionality; the frontend mirrors this with `AdminRoute.jsx`.
   - The repo includes invite signup, email verification, password reset, and demo/admin seed paths, so identity lifecycle is a first-class subsystem rather than a thin login form.

5. **Domain data model**
   - The main business entities implied by the README and page names are users, claimant profiles, benefit weeks, work-search contacts, invites, and audit logs.
   - MongoDB collections appear to align to those entities, with the backend acting as the sole data access boundary.
   - The frontend’s dashboard, calendar, week detail, and claimant screens are all different views over this same underlying claim/activity model.

6. **Work-search and benefit-week workflows**
   - The core user flow is: select or manage a claimant, record benefit weeks, then add work-search contacts or import them in bulk.
   - This is the central data path of the application and drives dashboard summaries, week detail views, and likely reporting/export behavior.
   - CSV import/export and screenshot-based extraction expand the data-entry path beyond manual form entry.

7. **Reporting and document generation**
   - The backend includes PDF report generation for benefit-week forms, which means it acts as a document-producing service as well as an API.
   - The `assets/ADJ034F.pdf` file suggests a static form/template asset used in that report workflow.
   - This output boundary matters for the diagram: the backend is not just CRUD; it also transforms application data into printable/compliance artifacts.

8. **Notifications and integrations**
   - Mailgun and Twilio are explicit integration points for email and SMS reminders.
   - The scheduler is APScheduler-driven and runs in-process inside the backend, which is important operationally because it affects deployment worker count.
   - There is also webhook handling for Mailgun with signature verification, so inbound external events influence internal reminder state.

9. **Operational and security controls**
   - The backend exposes `/health/live` and `/health/ready`, with readiness including MongoDB connectivity checks.
   - Security-related settings include HSTS, CORS origin control, rate limiting, Sentry error tracking, and JWT secret management.
   - `security-review-findings.md` and the presence of test/report artifacts suggest the project has undergone focused hardening and verification.

10. **Deployment topology**
    - The repo supports local Docker Compose for backend plus MongoDB, while the frontend is intended to run separately or be hosted on Vercel.
    - `render.yaml` indicates backend deployment on Render as a Docker-based service.
    - Vercel configuration handles SPA routing and caching headers for the frontend, while the backend is expected to be reachable via a configured API base URL.

11. **Testing and validation**
    - Backend tests live under `APP/backend/tests` and include both unit-style and integration-style rounds.
    - Test artifacts in `APP/test_reports` show iterative validation and CI reporting.
    - The presence of scripts such as login verification, JWT inspection, and user management helpers suggests some backend behaviors were exercised outside the main app flow for debugging and verification.

12. **Helpful diagram boundaries**
    - The cleanest architecture diagram should show:
      - Browser client → React SPA
      - React SPA → FastAPI API over HTTP with JWT auth
      - FastAPI → MongoDB
      - FastAPI → Mailgun/Twilio/Sentry as external services
      - FastAPI internal scheduler → reminder jobs
    - The backend should be drawn as the central orchestration layer because it owns all business rules, notifications, reporting, and persistence access.

Main entry points: [`APP/backend/server.py`](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py) (API server), [`APP/frontend/src/App.jsx`](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/App.jsx) (React app), [`APP/frontend/src/lib/api.js`](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/lib/api.js) (API client), [`APP/backend/tests`](https://github.com/cagedbear83/job-tracker/tree/main/APP/backend/tests) (Backend tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["React app<br/>spa<br/>[App.jsx]"]
  node_authctx["Auth state<br/>context<br/>[AuthContext.jsx]"]
  node_pages["Route pages<br/>views"]
  node_adminroute["Admin guard<br/>route-guard<br/>[AdminRoute.jsx]"]
  node_api["API client<br/>http-client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_server["API server<br/>fastapi<br/>[server.py]"]
  node_auth["Identity<br/>jwt-auth<br/>[server.py]"]
  node_domain["Work tracker<br/>domain-services<br/>[server.py]"]
  node_persistence[("Mongo access<br/>data-access<br/>[server.py]")]
  node_reports["PDF reports<br/>document-service<br/>[ADJ034F.pdf]"]
  node_scheduler["Reminder jobs<br/>apscheduler<br/>[server.py]"]
  node_webhooks["Inbound webhooks<br/>integration<br/>[server.py]"]
  node_security["Security controls<br/>policy<br/>[server.py]"]
end

subgraph group_external["External services"]
  node_mongo[("MongoDB<br/>database")]
  node_mailgun["Mailgun<br/>email service"]
  node_twilio["Twilio<br/>sms service"]
  node_sentry["Sentry<br/>observability"]
end

subgraph group_ops["Ops & verification"]
  node_vercel["Vercel<br/>hosting<br/>[vercel.json]"]
  node_render["Render<br/>deploy<br/>[render.yaml]"]
  node_tests["Backend tests<br/>verification"]
  node_reportsdir["Test reports<br/>artifacts"]
end

node_browser(("Browser<br/>client"))

node_browser -->|"loads UI"| node_spa
node_spa -->|"reads session"| node_authctx
node_spa -->|"renders routes"| node_pages
node_spa -->|"guards admin views"| node_adminroute
node_spa -->|"calls API"| node_api
node_api -->|"HTTP/JWT"| node_server
node_server -->|"authenticates"| node_auth
node_server -->|"orchestrates"| node_domain
node_domain -->|"stores data"| node_persistence
node_persistence -->|"async reads/writes"| node_mongo
node_server -->|"generates PDFs"| node_reports
node_server -->|"runs jobs"| node_scheduler
node_scheduler -->|"sends SMS"| node_twilio
node_scheduler -->|"sends email"| node_mailgun
node_webhooks -->|"receives events"| node_mailgun
node_server -->|"handles webhook"| node_webhooks
node_server -->|"enforces"| node_security
node_server -->|"reports errors"| node_sentry
node_vercel -->|"hosts frontend"| node_spa
node_render -->|"hosts backend"| node_server
node_tests -->|"validates"| node_server
node_reportsdir -->|"stores results"| node_tests

click node_spa "https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/App.jsx"
click node_authctx "https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/context/AuthContext.jsx"
click node_pages "https://github.com/cagedbear83/job-tracker/tree/main/APP/frontend/src/pages"
click node_adminroute "https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/components/AdminRoute.jsx"
click node_api "https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/lib/api.js"
click node_server "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_auth "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_domain "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_persistence "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_reports "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/assets/ADJ034F.pdf"
click node_scheduler "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_webhooks "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_security "https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py"
click node_vercel "https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/vercel.json"
click node_render "https://github.com/cagedbear83/job-tracker/blob/main/render.yaml"
click node_tests "https://github.com/cagedbear83/job-tracker/tree/main/APP/backend/tests"
click node_reportsdir "https://github.com/cagedbear83/job-tracker/tree/main/APP/test_reports"

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_spa,node_authctx,node_pages,node_adminroute,node_api toneBlue
class node_server,node_auth,node_domain,node_persistence,node_reports,node_scheduler,node_webhooks,node_security toneAmber
class node_mongo,node_mailgun,node_twilio,node_sentry toneMint
class node_vercel,node_render,node_tests,node_reportsdir toneRose
class node_browser toneNeutral
```

## Components

### Frontend

React single-page app and client-side session layer

- [React app](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/App.jsx): spa · Client-rendered UI shell and route host · `APP/frontend/src/App.jsx`
- [Auth state](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/context/AuthContext.jsx): context · Session and JWT state management · `APP/frontend/src/context/AuthContext.jsx`
- [Route pages](https://github.com/cagedbear83/job-tracker/tree/main/APP/frontend/src/pages): views · Login, dashboard, claimant, import, audit, and profile screens · `APP/frontend/src/pages`
- [Admin guard](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/components/AdminRoute.jsx): route-guard · Client-side protection for privileged views · `APP/frontend/src/components/AdminRoute.jsx`
- [API client](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/src/lib/api.js): http-client · Frontend requests and token attachment layer · `APP/frontend/src/lib/api.js`

### Backend

FastAPI application core and domain orchestration

- [API server](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): fastapi · Application entrypoint and request router · `APP/backend/server.py`
- [Identity](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): jwt-auth · Login, invites, verification, reset, and role checks · `APP/backend/server.py`
- [Work tracker](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): domain-services · Claimants, benefit weeks, contacts, and dashboard logic · `APP/backend/server.py`
- [Mongo access](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): data-access · Async persistence boundary for application data · `APP/backend/server.py`
- [PDF reports](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/assets/ADJ034F.pdf): document-service · Benefit-week form generation and template output · `APP/backend/assets/ADJ034F.pdf`
- [Reminder jobs](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): apscheduler · In-process scheduled reminders and background tasks · `APP/backend/server.py`
- [Inbound webhooks](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): integration · Mailgun webhook handling and signature verification · `APP/backend/server.py`
- [Security controls](https://github.com/cagedbear83/job-tracker/blob/main/APP/backend/server.py): policy · Health checks, CORS, HSTS, rate limiting, and protected admin paths · `APP/backend/server.py`

### External services

Third-party and infrastructure dependencies

- **MongoDB**: database · Primary application datastore
- **Mailgun**: email service · Email delivery and inbound event source
- **Twilio**: sms service · SMS reminders and notifications
- **Sentry**: observability · Error tracking and production diagnostics

### Ops & verification

Deployment, testing, and validation artifacts

- [Vercel](https://github.com/cagedbear83/job-tracker/blob/main/APP/frontend/vercel.json): hosting · Frontend hosting and SPA routing · `APP/frontend/vercel.json`
- [Render](https://github.com/cagedbear83/job-tracker/blob/main/render.yaml): deploy · Backend container deployment target · `render.yaml`
- [Backend tests](https://github.com/cagedbear83/job-tracker/tree/main/APP/backend/tests): verification · Unit and integration-style backend checks · `APP/backend/tests`
- [Test reports](https://github.com/cagedbear83/job-tracker/tree/main/APP/test_reports): artifacts · Stored CI and validation outputs · `APP/test_reports`

### Other components

- **Browser**: client · End-user entrypoint for the SPA

## Connections

- Browser → React app: loads UI · User opens the client application
- React app → Auth state: reads session · App consumes client auth state
- React app → Route pages: renders routes · Route-level pages make up the user experience
- React app → Admin guard: guards admin views · Client-side role checks for privileged pages
- React app → API client: calls API · SPA sends JWT-backed HTTP requests
- API client → API server: HTTP/JWT · Frontend talks to backend API
- API server → Identity: authenticates · Login, invite, reset, verify, and admin checks
- API server → Work tracker: orchestrates · Business workflows for claimants and benefit weeks
- Work tracker → Mongo access: stores data · Application state flows through the data boundary
- Mongo access → MongoDB: async reads/writes · MongoDB is the primary datastore
- API server → PDF reports: generates PDFs · Transforms work-tracker data into printable forms
- API server → Reminder jobs: runs jobs · In-process scheduler executes reminders
- Reminder jobs → Twilio: sends SMS · Reminder jobs can notify users by text
- Reminder jobs → Mailgun: sends email · Reminder jobs can notify users by email
- Inbound webhooks → Mailgun: receives events · Inbound mail events update reminder state
- API server → Inbound webhooks: handles webhook · Backend exposes Mailgun webhook endpoints
- API server → Security controls: enforces · Production protections and health endpoints live here
- API server → Sentry: reports errors · Runtime errors and diagnostics flow to Sentry
- Vercel → React app: hosts frontend · Frontend deployment and SPA routing
- Render → API server: hosts backend · Containerized API deployment
- Backend tests → API server: validates · Backend tests exercise API behavior
- Test reports → Backend tests: stores results · Captured validation outputs and CI artifacts