docs+src: complete Steps 1-3 outcomes + auth re-sync baseline

This commit captures everything produced during autodev existing-code Steps 1 (Document), 2 (Architecture Baseline Scan), and 3 (Test Spec), together with the targeted auth + CORS re-sync triggered on 2026-05-14 when codebase drift was detected at Step 4 entry. None of this work was previously committed. Step 1 (Document) — 50+ _docs/02_document/ files: problem, solution, architecture, system flows, glossary, module-layout, per-component specs (01..06), modules, deployment, diagrams, data model, FINAL report, verification log, discovery. Step 2 (Architecture Baseline) — architecture_compliance_baseline.md. Verdict PASS_WITH_WARNINGS (0 Critical, 0 High, 1 Medium, 2 Low). No High/Critical findings; auto-chained to Step 3 per existing-code flow. Step 3 (Test Spec) — _docs/02_document/tests/* (67 scenarios across blackbox, security, resilience, resource-limit, performance), plus e2e/docker-compose.test.yml, e2e/seed/run.sh, scripts/run-tests.sh, scripts/run-performance-tests.sh. Coverage 88% over the active scope (40 of 45 items covered, 6 RB-deferred, 5 documented-as-uncovered). Targeted auth + CORS re-sync — replaces the deleted in-house token issuer with a JWKS-verifier model. AuthController and TokenService removed; JwtExtensions switched from HS256 symmetric to ES256 over admin's JWKS. ConfigurationResolver and CorsConfigurationValidator added under src/Infrastructure/. ADR-002 and ADR-006 retired; SEC-01, SEC-02, SEC-03 marked Closed. One new testability risk recorded in architecture.md Open Risks Section 6 (JWKS HTTPS gating). Source changes: - src/Auth/JwtExtensions.cs (modified) — ES256, JWKS, alg pinning - src/Program.cs (modified) — DI wiring for ConfigurationResolver and CorsConfigurationValidator - src/Controllers/AuthController.cs (deleted) — no in-service issuance - src/Services/TokenService.cs (deleted) — same - src/Infrastructure/ConfigurationResolver.cs (new) - src/Infrastructure/CorsConfigurationValidator.cs (new) - .env.example (new) — required env var documentation - .gitignore (updated) Cross-repo coordination: _docs/cross-repo/flights_h1_h2_h3_change_spec captures the change-spec for downstream services that consumed the now deleted /auth endpoints. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-21 12:21:06 +00:00 · 2026-05-14 20:19:05 +03:00
parent 08eadc1158
commit 03f879206e
66 changed files with 6006 additions and 133 deletions
@@ -0,0 +1,45 @@
+# Annotations (REST & files)
+
+## 1. High-Level Overview
+
+**Purpose:** HTTP API for annotation CRUD, status, listing, and serving **annotation image / thumbnail** bytes — the surface described in `suite/_docs/01_annotations.md` §1–6 (excluding the SSE stream).
+
+**Architectural pattern:** Layered API — controller → application service → database + filesystem.
+
+**Upstream dependencies:** Platform (DB, auth, paths), Media (annotation create may reference existing `MediaId`).
+
+**Downstream consumers:** Annotator UI, Detections pipeline (HTTP POST annotations), Dataset (read-only overlap on entities).
+
+## 2. Internal interfaces
+
+Primary application API: `AnnotationService` — create/update/status/delete/query/get-by-id; uses `PathResolver`, `AppDataConnection`, hashing, label files, thumbnails, and triggers **real-time publish** (calls into `AnnotationEventService`) and **queue enqueue** (via failsafe path — see component 02).
+
+Controller: `AnnotationsController` — **REST and file routes**; the `GET …/events` SSE action is **specified and operated** from the **Annotations realtime & sync** component (same source file, split responsibility for docs).
+
+### Representative HTTP
+
+| Area | Routes (policy `ANN`) |
+|------|------------------------|
+| CRUD | `POST/PUT/PATCH/DELETE/GET` under `/annotations` |
+| Files | `GET /annotations/{id}/thumbnail`, `GET /annotations/{id}/image` |
+
+## 3. External API specification
+
+See `01_annotations.md` §1–6; confirm drift notes in `00_discovery.md` (JWT user id, `FlightId` vs suite `missionId`).
+
+## 4. Data access patterns
+
+Heavy use of `annotations`, `detection`, `media` joins for list filters; writes cascade detections on update.
+
+## 5. Implementation notes
+
+- Annotation id from image hash when bytes provided; else copy from existing media path.
+- `TimeSpan` persisted as ticks on `Annotation`.
+
+## 6. Dependency graph (relative to other components)
+
+**Imports from:** Platform, Media (logical). **Consumed by:** Dataset (read), UI, external Detections service.
+
+## 7. Modules included
+
+`annotations-service` (module doc); **shared file** `AnnotationsController.cs` with component 02 for SSE action only.
@@ -0,0 +1,40 @@
+# Annotations (realtime & stream sync)
+
+## 1. High-Level Overview
+
+**Purpose:** **SSE** push for annotation changes and **RabbitMQ Stream** failsafe export — `01_annotations.md` sections *SSE Communication* and *Annotation Sync* / *Failsafe* / *RabbitMQ Stream*.
+
+**Architectural pattern:** Event channel + background outbox producer.
+
+**Upstream dependencies:** Platform (DB, config, paths), Annotations REST (domain mutations enqueue/publish).
+
+**Downstream consumers:** Browser UI (SSE); Admin sync worker; AI Training consumer (external).
+
+## 2. Internal interfaces
+
+- `AnnotationEventService` — in-process `Channel<AnnotationEventDto>`; `PublishAsync` / `Reader`.
+- `FailsafeProducer` + `RabbitMqConfig` — stream client, MessagePack payloads, drains `annotations_queue_records`.
+- **HTTP:** `AnnotationsController.Events` — `text/event-stream` subscription (same controller file as REST component; **doc ownership** here for SSE).
+
+## 3. External API / integration
+
+| Surface | Notes |
+|---------|--------|
+| `GET /annotations/events` | SSE; see suite SSE section |
+| RabbitMQ stream `azaion-annotations` | Env `RABBITMQ_*` from `Program` |
+
+## 4. Data access patterns
+
+Queue table buffering; stream send on connectivity; image bytes in create messages per suite.
+
+## 5. Caveats
+
+MessagePack key stability; stream consumer offsets independent per consumer type.
+
+## 6. Dependency graph
+
+**Imports from:** Platform, annotations domain (via service calls / shared types). **Consumed by:** External infrastructure.
+
+## 7. Modules included
+
+`sse-realtime`, `rabbitmq-stream-sync`.
@@ -0,0 +1,29 @@
+# Media
+
+## 1. High-Level Overview
+
+**Purpose:** Upload, batch-upload, list, delete, and download **media** files for missions/waypoints — `01_annotations.md` §7–10 and *Media Browsing*.
+
+**Architectural pattern:** Service + controller; filesystem + DB.
+
+**Upstream dependencies:** Platform (auth, DB, paths for storage roots).
+
+**Downstream consumers:** Annotator UI; Annotations REST (references `MediaId`).
+
+## 2. Internal interfaces
+
+`MediaService`, `MediaController` — JSON create, **multipart** batch with `waypointId`, paged list, file download, delete.
+
+## 3. External API
+
+| Policy | Base |
+|--------|------|
+| `ANN` | `/media` |
+
+## 4. Data access
+
+`media` table; files on disk under configured video/image roots.
+
+## 5. Modules included
+
+`media-service`.
@@ -0,0 +1,25 @@
+# Dataset Explorer (API)
+
+## 1. High-Level Overview
+
+**Purpose:** Backend for **Dataset Explorer** — grid, detail, status PATCH, bulk status — `DATASET` policy; cross-ref `suite/_docs/09_dataset_explorer.md`.
+
+**Architectural pattern:** Read-heavy + controlled writes on annotation status.
+
+**Upstream dependencies:** Platform, shared annotation entities/status with Annotations REST.
+
+**Downstream consumers:** Dataset Explorer UI.
+
+## 2. Internal interfaces
+
+`DatasetService`, `DatasetController` — `/dataset` routes.
+
+## 3. External API
+
+| Policy | Base |
+|--------|------|
+| `DATASET` | `/dataset` |
+
+## 4. Modules included
+
+`dataset-service`.
@@ -0,0 +1,23 @@
+# Settings & metadata
+
+## 1. High-Level Overview
+
+**Purpose:** System, directory, camera, and per-user UI settings; **detection class catalog** for labels/colors — `01_annotations.md` §11–12 (camera) plus settings/directory narratives; `GET /classes` for annotator.
+
+**Architectural pattern:** CRUD settings services + thin metadata read controller.
+
+**Upstream dependencies:** Platform (DB, auth — `ADM` on mutating settings).
+
+**Downstream consumers:** All UIs; `PathResolver` after directory updates (reset).
+
+## 2. Internal interfaces
+
+`SettingsService`, `SettingsController`, `ClassesController`.
+
+## 3. External API
+
+Mixed `[Authorize]` and policy `ADM` for writes under `/settings`; `GET /classes` authenticated read.
+
+## 4. Modules included
+
+`settings-metadata-service`.
@@ -0,0 +1,27 @@
+# Platform foundation
+
+## 1. High-Level Overview
+
+**Purpose:** **Wire enums**, **PostgreSQL schema/mapping**, **cross-cutting HTTP error handling**, **path resolution**, **JWT policies + token refresh**, and **application bootstrap** — no standalone product feature; enables all other components.
+
+**Architectural pattern:** Shared kernel / infrastructure.
+
+**Upstream dependencies:** None (root).
+
+**Downstream consumers:** All feature components.
+
+## 2. Internal interfaces
+
+- `src/Enums/*`
+- `src/Database/*` (`AppDataConnection`, `DatabaseMigrator`, entities)
+- `ErrorHandlingMiddleware`, `PathResolver`, `PaginatedResponse`, `ErrorResponse`, `GlobalUsings.cs`
+- `JwtExtensions` (JWKS verifier), `ConfigurationResolver`, `CorsConfigurationValidator`
+- `Program.cs`
+
+## 3. External API
+
+`/health` (AllowAnonymous); Swagger in development configuration. Token refresh is no longer hosted here — callers refresh against admin's `POST /token/refresh`.
+
+## 4. Modules included
+
+`wire-enums`, `database-layer`, `common-infrastructure`, `auth-identity`, `composition-program`.