How cagedbear83/job-tracker works
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: server.py API server · App.jsx React app · api.js API client · tests Backend tests
Components 22
Frontend
React single-page app and client-side session layer
- React app · Client-rendered UI shell and route host
APP/frontend/src/App.jsx - Auth state · Session and JWT state management
APP/frontend/src/context/AuthContext.jsx - Route pages · Login, dashboard, claimant, import, audit, and profile screens
APP/frontend/src/pages - Admin guard · Client-side protection for privileged views
APP/frontend/src/components/AdminRoute.jsx - API client · Frontend requests and token attachment layer
APP/frontend/src/lib/api.js
Backend
FastAPI application core and domain orchestration
- API server · Application entrypoint and request router
APP/backend/server.py - Identity · Login, invites, verification, reset, and role checks
APP/backend/server.py - Work tracker · Claimants, benefit weeks, contacts, and dashboard logic
APP/backend/server.py - Mongo access · Async persistence boundary for application data
APP/backend/server.py - PDF reports · Benefit-week form generation and template output
APP/backend/assets/ADJ034F.pdf - Reminder jobs · In-process scheduled reminders and background tasks
APP/backend/server.py - Inbound webhooks · Mailgun webhook handling and signature verification
APP/backend/server.py - Security controls · Health checks, CORS, HSTS, rate limiting, and protected admin paths
APP/backend/server.py
External services
Third-party and infrastructure dependencies
- MongoDB · Primary application datastore
- Mailgun · Email delivery and inbound event source
- Twilio · SMS reminders and notifications
- Sentry · Error tracking and production diagnostics
Ops & verification
Deployment, testing, and validation artifacts
- Vercel · Frontend hosting and SPA routing
APP/frontend/vercel.json - Render · Backend container deployment target
render.yaml - Backend tests · Unit and integration-style backend checks
APP/backend/tests - Test reports · Stored CI and validation outputs
APP/test_reports
Other components
- Browser · End-user entrypoint for the SPA
Connections 22
- 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