docs: consolidate repository guides and preserve audit history

2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
@@ -0,0 +1,10 @@
+# Backend
+
+The ASP.NET Core API is the system boundary for persistence, authentication, business rules, files, integrations, and background work.
+
+- [API reference](api.md)
+- [Background jobs](background-jobs.md)
+- [Error handling](error-handling.md)
+- [Backend architecture](../architecture/backend.md)
+
+Run and test it through [local development](../development/getting-started.md). Do not point local acceptance tests at production data.
@@ -0,0 +1,18 @@
+# API reference
+
+All application routes are under `/api`. OpenAPI is mapped in Development only. The authoritative contracts are the controller request/response types and tests in `JobTrackerApi.Tests/`.
+
+| Area | Main routes |
+|---|---|
+| Authentication | `/auth/config`, `/auth/login`, `/auth/register`, `/auth/me`, password/email verification and reset |
+| Jobs/applications | `/jobapplications` CRUD, board, pipeline, reminders, history, timeline, stats, follow-ups, soft-delete/restore, AI workspace |
+| Companies | `/companies` CRUD and recruiter/pipeline context |
+| Correspondence | `/correspondence` per-application messages and inbox views |
+| Gmail/Graph/IMAP | `/gmail`, `/microsoft-graph`, `/imap` connect, sync, review, and relink flows |
+| Attachments | `/attachments` validated upload, list, download, metadata rename, delete |
+| Career/CV | `/profile-cv` extraction, structure, rewriting, tailoring, templates, export |
+| Rules/exports/backups | `/rules`, `/export`, `/backup` |
+| Admin | `/users`, `/admin/audit`, `/admin/system` |
+| Billing | `/billing` hosted checkout, portal, and webhook when configured |
+
+Mutating requests using a session cookie require the CSRF double-submit header. Authorization and owner filtering are enforced in the API; a UI route is not a security boundary. See [authentication](../security/authentication.md) and [authorization](../security/authorization.md).
@@ -0,0 +1,5 @@
+# Background jobs
+
+Hosted services currently cover rules/ghosting, follow-up reminders, saved-search alerts, daily exports, job enrichment, AI operations, CV processing, and database backups. The exact enablement switches and defaults are in `JobTrackerApi/appsettings.json` and [environment variables](../configuration/environment-variables.md).
+
+The deployment is intentionally single-backend-instance. CV and AI work persist enough state to recover queued/running work after restart, but there is no database lease for multiple API replicas. Add leasing before scaling horizontally. Worker failures must not make manual tracking unusable; readiness and logs are the operational signals.
@@ -0,0 +1,5 @@
+# Error handling
+
+Unhandled API errors use RFC 7807-style Problem Details with a trace identifier. Client errors are logged best-effort through `/client-errors`; the client must not treat that endpoint as a required dependency for saving data.
+
+External failures are surfaced as bounded, actionable errors. AI, mail, translation, import, and PDF paths have timeouts or admission limits where implemented. Do not retry ambiguous writes automatically; preserve reviewed drafts and uncertain send state. Health (`/health`) is liveness-only, while `/ready` checks database readiness.