jobtrackingapp/docs/architecture/overview.md

Architecture overview

Last verified: 2026-09-11 against the current repository.

Components

flowchart LR
  Browser --> Nginx[nginx static frontend]
  Nginx --> API[ASP.NET Core API]
  API --> DB[(MariaDB)]
  API --> Data[Data root: uploads, CV artifacts, exports, keys]
  API --> AI[FastAPI AI service]
  AI --> Local[local transformers/Ollama]
  AI --> Cloud[optional Gemini or Groq]
  API --> Mail[Google/Gmail, Microsoft Graph, IMAP, SMTP]
  API --> Jobs[NAV and job-site import clients]

The frontend is a client-rendered React application inside a Next.js static-export shell. nginx serves the export and proxies same-origin /api requests to the API. The API owns HTTP endpoints, business services, EF Core models/migrations, authentication, background services, files, and integrations. The AI service is an internal network dependency; it is not a user-authenticated application.

Technology and ownership

Component	Current implementation
UI	Next.js 16, React 19, TypeScript 5.9, MUI 7, React Router 7
API	ASP.NET Core 9, EF Core 9, ASP.NET Identity, JWT bearer, cookie sessions
Data	MariaDB standard for development/integration/CI/production; Pomelo 9.0.0, EF Core 9.0.14; explicit SQLite transition path retained pending safe retirement
AI	FastAPI, transformers/distilbart summarizer, OCR and document extractors, Ollama/Gemini/Groq CV routes
Runtime	Docker Compose, nginx 1.29-alpine, optional Ollama profile
Delivery	Gitea Actions → SSH deployment → Docker Compose

Further detail: frontend architecture, backend architecture, data flow, integrations, database schema, and deployment.

Database architecture decision updated 23 October 2026: production is owner-verified MariaDB 12.2.2, previously running floating mariadb:latest. The development/integration image is pinned by version and verified registry manifest digest. Standardisation record separates actual runtime evidence, exact-image limits, remaining CI qualifications and staged SQLite retirement.

The older architecture/current.md path is retained as a compatibility pointer to this overview.

CV-UX-01 development architecture, 26 October 2026: the existing MUI CV editor and physical-page renderer remain the owners. Career Profile is canonical; CV overrides and null-as-inherit settings remain document-specific. All letter text/design/history writers stage atomically through ApplicationAssetsService under JobApplication.Version. Contact/design copies are reviewed snapshots; application packages freeze recorded HTML/settings/artifacts. Letter AI records source fingerprints and validates them before Apply. The additive letter-design migration and current acceptance limits are documented in CV-UX-01 acceptance. This is development evidence; live-model checks are owner-blocked, and production/Phase 10 remain NO-GO.

Important boundaries

• Job is the opportunity; JobApplication is the user's pursuit of it. Compatibility columns and dual writes remain until the production cutover gate is completed.
• Every tenant-owned record is filtered by the authenticated owner. A missing owner is denied, not treated as an anonymous tenant.
• AI is best-effort and policy-gated. Manual tracking remains usable when the AI service or a provider is unavailable.
• The current deployment is single-backend-instance. Worker leasing is intentionally not implemented for multi-replica operation.