mirror of https://github.com/azaion/admin.git synced 2026-06-21 22:31:09 +00:00

Files

T

Oleksandr Bezdieniezhnykh a77b3f8a59 [AZ-529] [AZ-530] Cycle-2 documentation refresh

Refreshes _docs/02_document/ to reflect the cycle-2 auth-modernization
+ CMMC hardening landings (AZ-531..AZ-538). Authoritative source for
the ripple set is ripple_log_cycle2.md.

Covered:
- architecture.md (section 1 rewritten, ADRs 6-9 added)
- data_model.md (sessions, audit_events, user columns, migrations)
- system-flows.md (F1 rewritten; F11-F17 added; F2/F7/F9 minor)
- module-layout.md (cycle-2 sub-component table)
- diagrams/flows/flow_login.md (dual-token + MFA)
- components/{01_data_layer,03_auth_and_security,05_admin_api}
- modules/ (12 new, 8 modified — full Argon2id/ES256/MFA/refresh
  /mission/session/audit/jwks rollup)
- tests/{blackbox,security,traceability-matrix}

Step 13 (Update Docs) output for cycle 2.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-14 09:22:53 +03:00

7.2 KiB

Raw Blame History

Module Layout

Language: csharp Layout Convention: solution-flat (legacy — pre-src/ convention) Root: ./ (csproj folders sit at workspace root) Last Updated: 2026-05-14 (refreshed for cycle 2 Auth Modernization — AZ-531..AZ-538)

Layout Rules

This admin/ workspace is one deployable (the Azaion.AdminApi HTTP service) split across three production csproj projects + one e2e test csproj: Azaion.AdminApi, Azaion.Services, Azaion.Common, e2e/Azaion.E2E. (The Azaion.Test unit-test project was removed in cycle 2 once its only test class — SecurityTest.cs — was deleted along with the encrypted-download stack; no in-process unit tests remain.)
Existing task specs (_docs/02_tasks/*/AZ-*.md) all use Component: Admin API as a single coarse identifier covering this entire workspace. The Per-Component Mapping below honors that convention rather than rewriting every task spec.
The conceptual sub-components documented in _docs/02_document/components/01_data_layer..05_admin_api/ are read-time documentation aids, not write-time ownership boundaries. They are listed under "Conceptual Sub-Components" below for reference only.
Public API surface = the namespaces / interfaces exposed across csproj boundaries (I*Service interfaces in Azaion.Services, request DTOs in Azaion.Common/Requests/, entities in Azaion.Common/Entities/).
Tests live in e2e/Azaion.E2E/ (HTTP black-box). Production code never imports from there.

Per-Component Mapping

Component: Admin API

Epic: AZ-181 (and any other admin-API epic, e.g. AZ-509 for the Detection Classes feature)
Directory: workspace root (multi-csproj, see below)
Owns (exclusive write during implementation):
- Azaion.AdminApi/**
- Azaion.Services/**
- Azaion.Common/**
- e2e/Azaion.E2E/** (xUnit/HttpClient-based black-box tests)
- e2e/db-init/** (test-DB seed/init scripts consumed by the e2e harness)
- docker-compose.test.yml
Public API (visible to other csprojs within the workspace):
- Azaion.Services/I*Service.cs interfaces (UserService, AuthService, ResourcesService, …)
- Azaion.Services/Security.cs, Azaion.Services/Cache.cs (used by Azaion.AdminApi/Program.cs)
- Azaion.Common/Requests/* request DTOs
- Azaion.Common/Entities/* linq2db entities
- Azaion.Common/Database/* IDbFactory + connection helpers
- Azaion.Common/Configs/* strongly-typed config records
- Azaion.Common/Extensions/* extension methods
- Azaion.Common/BusinessException.cs
- Azaion.AdminApi/Program.cs (composition root + minimal-API endpoints)
- Azaion.AdminApi/BusinessExceptionHandler.cs
Internal (do NOT import across csproj boundaries):
- private/internal members within each csproj (default C# visibility rules apply)
- Azaion.AdminApi/appsettings*.json (loaded by the host, not imported)
- e2e/Azaion.E2E/Helpers/* (test-only helpers, never imported by production)
Imports from: (none — this is the only deployable in the workspace; the Loader is architecturally retired per suite/_docs/_repo-config.yaml unresolved:loader-retirement-arch-doc)
Consumed by: HTTP clients (UI workspace, edge services on secured Jetson, SaaS browser sessions) — out of process

Conceptual Sub-Components (documentation only — NOT ownership boundaries)

These come from _docs/02_document/components/ and exist for reading the codebase, not for assigning task ownership. A single task may legitimately touch multiple sub-components within the Admin API umbrella.

#	Sub-component	Primary file locations
1	Data Layer	`Azaion.Common/Database/`, `Azaion.Common/Configs/` (incl. cycle-2 `AuthConfig.cs` + `JwtConfig.cs` rebuilt for ES256 + new `SessionConfig`), `Azaion.Common/Entities/` (incl. cycle-1 `DetectionClass.cs`; cycle-2 `Session.cs` + `AuditEvent.cs`; `User.cs` extended with lockout + MFA columns; `RoleEnum.cs` + `Service = 60`)
2	User Management	`Azaion.Services/UserService.cs` (cycle-2 — Argon2id verify/hash + lazy migration + lockout + per-account rate-limit checks; new dependencies on `IAuditLog`, `IOptions<AuthConfig>`), `Azaion.Common/Requests/Register{User,DeviceResponse}.cs`, `LoginRequest.cs`, `LoginResponse.cs` (new — AZ-531), `MfaRequests.cs` (new — AZ-534), `MissionSessionRequest.cs` (new — AZ-533), `SetUserQueueOffsetsRequest.cs`
3	Auth & Security	`Azaion.Services/AuthService.cs` (cycle-2 — ES256 + `AccessToken` record + sid/jti/amr claims), `Azaion.Services/Security.cs` (cycle-2 — Argon2id `HashPassword`/`VerifyPassword`; `ToHash` deleted), `Azaion.Services/RefreshTokenService.cs` (new — AZ-531), `Azaion.Services/SessionService.cs` (new — AZ-535), `Azaion.Services/MfaService.cs` (new — AZ-534), `Azaion.Services/MissionTokenService.cs` (new — AZ-533), `Azaion.Services/JwtSigningKeyProvider.cs` (new — AZ-532), `Azaion.Services/AuditLog.cs` (new — AZ-537), `Azaion.Services/Cache.cs`
4	Resource Management	`Azaion.Services/ResourcesService.cs` (`GetResourceRequest.cs` removed in cycle 2 with `POST /resources/get`; `SetHWRequest.cs` removed by AZ-197; `ResourceUpdateService.cs` + `GetUpdateRequest.cs` + `PublishResourceRequest.cs` removed when AZ-183 was reverted)
4b	Detection Classes	`Azaion.Services/DetectionClassService.cs` + `Azaion.Common/Requests/{Create,Update}DetectionClassRequest.cs` (added cycle 1 / AZ-513)
5	Admin API (HTTP)	`Azaion.AdminApi/Program.cs` (cycle-2 — significantly expanded: HSTS / HTTPS redirect, RateLimiter, DataProtection, eight new endpoints, `IssueDualTokens` + `ParseSidClaim`/`ParseUserIdClaim` helpers), `Azaion.AdminApi/BusinessExceptionHandler.cs` (cycle-2 — per-enum status mapping + `Retry-After` header), `Azaion.AdminApi/appsettings*.json`

Allowed Dependencies (csproj layering)

Layer	csproj	May reference
4. Entry / Host	`Azaion.AdminApi`	`Azaion.Services`, `Azaion.Common`
3. Application	`Azaion.Services`	`Azaion.Common`
2. Foundation	`Azaion.Common`	(none)
—. Tests (out-of-process e2e)	`e2e/Azaion.E2E`	(none from production csprojs — HTTP only)

A reference from a lower production layer to a higher production layer is an Architecture finding (High severity) in /code-review Phase 7. Test projects may reference any production csproj; production csprojs may NOT reference test projects.

Layout Conventions (reference)

Language	Root	Per-component path	Public API file	Test path
C# (.NET)	`./` (this workspace, legacy flat layout)	`./<Csproj>/`	namespace-root types in each csproj	`e2e/Azaion.E2E/`

Notes

This file was authored 2026-05-13 by /autodev Step 10 to satisfy /implement Step 4. The _docs/ artifact set predates the Step 1.5 module-layout addition, so this is a backfill rather than a fresh decompose Step 1.5 run.
If the project later splits into multiple deployables (e.g. carving out Azaion.AnnotationsApi), re-run /decompose Step 1.5 to produce a finer-grained mapping.

7.2 KiB Raw Blame History