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
@@ -1,93 +1,42 @@
-# Application Architecture Overview
+# Architecture overview

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

-Define the target architecture direction for Jobjakt.
+## Components

-This document does not require an immediate rewrite.
+```mermaid
+flowchart LR
+  Browser --> Nginx[nginx static frontend]
+  Nginx --> API[ASP.NET Core API]
+  API --> DB[(SQLite or MariaDB/MySQL)]
+  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 goal is incremental improvement while keeping the application functional.
+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

-# Product Architecture
+| 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 | SQLite default; Pomelo MySQL/MariaDB provider for server deployments |
+| 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 |

-The application consists of:
+Further detail: [frontend architecture](frontend.md), [backend architecture](backend.md), [data flow](data-flow.md), [integrations](integrations.md), [database schema](../database/schema.md), and [deployment](../infrastructure/deployment.md).

-## Core Platform
+The older [architecture/current.md](current.md) path is retained as a compatibility pointer to this overview.

-Job Tracking
+## Important boundaries

-↓
-
-Applications
-
-↓
-
-Communication
-
-↓
-
-Follow-ups
-
-
---
-
-## Supporting Platform
-
-Career Workspace
-
-↓
-
-Master Career Profile
-
-↓
-
-CV Builder
-
-↓
-
-Documents
-
-
---
-
-## Intelligence Layer
-
-AI Services
-
-↓
-
-Recommendations
-
-↓
-
-Generation
-
---
-
-# Architecture Goals
-
-The system should be:
-
- Maintainable.
- Testable.
- Extensible.
- Secure.
- SaaS-ready.
-
---
-
-# Evolution Strategy
-
-Prefer:
-
- Refactoring.
- Extraction.
- Clear boundaries.
- Incremental migrations.
-
-Avoid:
-
- Large rewrites.
- Replacing working systems unnecessarily.
+- `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.