admin/_docs/02_document/components/01_data_layer/description.md

Data Layer

1. High-Level Overview

Purpose: Provides database access, ORM mapping, entity definitions, configuration binding, and in-memory caching for the entire application.

Architectural Pattern: Repository/Factory — DbFactory creates short-lived AzaionDb connections with a read/write separation pattern.

Upstream dependencies: None (leaf component).

Downstream consumers: User Management, Authentication & Security, Resource Management.

2. Internal Interfaces

Interface: IDbFactory

Method	Input	Output	Async	Error Types
Run<T>	Func<AzaionDb, Task<T>>	T	Yes	ArgumentException (empty conn string)
Run	Func<AzaionDb, Task>	void	Yes	ArgumentException
RunAdmin	Func<AzaionDb, Task>	void	Yes	ArgumentException

Interface: ICache

Method	Input	Output	Async	Error Types
GetFromCacheAsync<T>	string key, Func<Task<T>>, TimeSpan?	T	Yes	None
Invalidate	string key	void	No	None

Entities

Cycle 1 (2026-05-13) note — DetectionClass (AZ-513) added; Resource (AZ-183) added then reverted same cycle. User.Hardware left as a tombstone (AZ-197). UNIQUE INDEX users_email_uidx added on users.email (security audit F-3, env/db/06_users_email_unique.sql).

Cycle 2 — early (2026-05-14) — ResourcesConfig.SuiteInstallerFolder / SuiteStageInstallerFolder removed with the installer endpoints; ResourcesConfig is now ResourcesFolder-only.

Cycle 2 — Auth Modernization (2026-05-14) — significant data-layer changes:

• User gained FailedLoginCount, LockoutUntil (AZ-537) and MfaEnabled, MfaSecret (DataProtection-encrypted), MfaRecoveryCodes (jsonb of Argon2id-hashed codes), MfaEnrolledAt, MfaLastUsedWindow (AZ-534). PasswordHash column unchanged in shape but now contains Argon2id PHC strings; legacy SHA-384 base64 values are accepted by Security.VerifyPassword and lazily upgraded on next login (AZ-536).
• New table public.sessions (AZ-531 / AZ-535) — refresh-token rotation + revocation, mapped via Common/Entities/Session.
• New table public.audit_events (AZ-537 + AZ-534) — append-only login + MFA event log, mapped via Common/Entities/AuditEvent.
• New RoleEnum.Service = 60 (AZ-535) — verifier-fleet identity used by the revocationReaderPolicy.
• New configs: AuthConfig (rate limit + lockout + Argon2id parameters), SessionConfig (refresh sliding + absolute lifetimes). JwtConfig rebuilt around ES256 (KeysFolder, ActiveKid, AccessTokenLifetimeMinutes, MfaStepTokenLifetimeMinutes); the legacy Secret and TokenLifetimeHours fields are no longer read.
• Migrations added: 07_auth_lockout_and_audit.sql, 08_sessions.sql, 09_sessions_logout_and_mission.sql, 10_users_mfa.sql.

User:
  Id: Guid (PK)
  Email: string (required)
  PasswordHash: string (required, Argon2id PHC; legacy SHA-384 base64 accepted on read, rehashed on next login — AZ-536)
  Hardware: string? (TOMBSTONED — AZ-197)
  Role: RoleEnum (required)
  CreatedAt: DateTime
  LastLogin: DateTime?
  UserConfig: UserConfig?
  IsEnabled: bool
  FailedLoginCount: int (AZ-537 — reset on successful login)
  LockoutUntil: DateTime? (AZ-537 — UTC; "now < LockoutUntil" → AccountLocked)
  MfaEnabled: bool (AZ-534)
  MfaSecret: string? (AZ-534 — IDataProtector-encrypted base32 TOTP secret)
  MfaRecoveryCodes: List<string>? (AZ-534 — jsonb of Argon2id-hashed single-use codes)
  MfaEnrolledAt: DateTime?
  MfaLastUsedWindow: long? (AZ-534 — anti-replay; last consumed TOTP step)

Session (AZ-531 / AZ-535):
  Id: Guid (PK — used as the JWT `sid` claim)
  UserId: Guid (FK to users)
  Class: string ("interactive" | "mission")
  RefreshTokenHash: byte[]? (SHA-256 of opaque refresh; null for mission sessions)
  RotatedFromTokenId: Guid? (chain pointer for reuse detection)
  IssuedAt: DateTime
  ExpiresAt: DateTime (sliding for interactive, absolute for mission)
  RevokedAt: DateTime?
  RevokedReason: string? (one of SessionRevokedReasons)
  RevokedByUserId: Guid?
  Ip: string?
  UserAgent: string?
  MfaAuthenticated: bool (AZ-534 — pinned at issue, inherited by rotations)
  AircraftId: Guid? (mission-only)
  MissionId: string? (mission-only)

AuditEvent (AZ-537 + AZ-534):
  Id: long (PK identity)
  EventType: string (one of AuditEventTypes — login_failed/success/lockout, mfa_*)
  Email: string (lowercase normalised)
  Ip: string?
  OccurredAt: DateTime (UTC)

DetectionClass (AZ-513): unchanged

RoleEnum: None=0, Operator=10, Validator=20, CompanionPC=30, Admin=40, ResourceUploader=50, Service=60 (AZ-535), ApiAdmin=1000
// ResourceUploader is data-only since AZ-183 revert.
// Service is the verifier-fleet identity used by revocationReaderPolicy.

Configuration POCOs

ConnectionStrings:
  AzaionDb: string — read-only connection string
  AzaionDbAdmin: string — admin (read/write) connection string

JwtConfig (AZ-532):
  Issuer: string
  Audience: string
  KeysFolder: string                — directory containing one PEM per kid
  ActiveKid: string                 — selects the signing key
  AccessTokenLifetimeMinutes: int   — default 15
  MfaStepTokenLifetimeMinutes: int  — default 5 (AZ-534)
  # Secret + TokenLifetimeHours: no longer read; kept only for back-compat deserialisation

SessionConfig (AZ-531):
  RefreshSlidingHours: int      — sliding window per rotate
  RefreshAbsoluteHours: int     — hard cap (no rotation past this)
  RevokedSnapshotMinutes: int   — verifier-poll grace window for /sessions/revoked

AuthConfig (AZ-536 + AZ-537):
  PasswordHashing: { TimeCost, MemoryCostKiB, Parallelism } — Argon2id parameters
  RateLimit:
    PerIpPermitLimit: int
    PerIpWindowSeconds: int
    PerAccountWindowSeconds: int
    PerAccountFailedThreshold: int
  Lockout:
    ConsecutiveFailureThreshold: int
    LockoutSeconds: int

ResourcesConfig:
  ResourcesFolder: string

3. External API Specification

N/A — internal component.

4. Data Access Patterns

Queries

Query	Frequency	Hot Path	Index Needed
SELECT * FROM users WHERE email = ?	High	Yes	Yes — UNIQUE INDEX users_email_uidx on email
SELECT * FROM users with optional filters	Medium	No	No
UPDATE users SET ... WHERE email = ?	Medium	No	No
INSERT INTO users	Low	No	UNIQUE INDEX above
DELETE FROM users WHERE email = ?	Low	No	No
SELECT * FROM sessions WHERE refresh_token_hash = ? (AZ-531)	High	Yes	Yes — UNIQUE INDEX on refresh_token_hash (08_sessions.sql)
UPDATE sessions SET revoked_at..., revoked_reason... WHERE id = ? (AZ-535)	Medium	No	PK
UPDATE sessions SET revoked_... WHERE user_id = ? AND revoked_at IS NULL (AZ-535 logout/all)	Low	No	INDEX on (user_id, revoked_at)
UPDATE sessions SET revoked_... WHERE aircraft_id = ? AND class='mission' AND revoked_at IS NULL (AZ-533)	Low	No	INDEX on (aircraft_id, class, revoked_at)
SELECT ... FROM sessions WHERE revoked_at >= ? AND expires_at > now() (AZ-535 verifier poll)	High	Yes	INDEX on revoked_at
SELECT count(*) FROM audit_events WHERE event_type='login_failed' AND email=? AND occurred_at >= ? (AZ-537)	High	Yes	INDEX on (email, event_type, occurred_at)
INSERT INTO audit_events (...) (AZ-537 / AZ-534)	High	Yes	n/a

Caching Strategy

Data	Cache Type	TTL	Invalidation
User by email	In-memory (LazyCache)	4 hours	On UpdateQueueOffsets, on lazy-rehash (AZ-536), on MFA enroll/confirm/disable (AZ-534), on user enable/disable, on lockout state changes (AZ-537)

Refresh tokens, sessions, and audit events are NOT cached — they are read directly from Postgres on every request. The verifier-poll snapshot (/sessions/revoked) is the only "edge" cache and lives in the verifier process, not in this component.

Storage Estimates

Table	Est. Row Count (1yr)	Row Size	Total Size	Growth Rate
users	100–1000 web users + 2000–10000 CompanionPC device users	~700 bytes (post-MFA columns)	~7 MB	Medium
sessions (AZ-531)	30 d retention (RefreshAbsoluteHours) × N active sessions per user × pruning job	~400 bytes	~50 MB ceiling	High during active fleet ops; bounded by retention
audit_events (AZ-537)	~50 events/user/day × ~5000 users × 365 d	~150 bytes	~14 GB/yr	High — partition or archive after 90 d (operational follow-up)
detection_classes (AZ-513)	10–200	~250 bytes	~50 KB	Low

Data Management

Seed data: Default admin user (admin@azaion.com, ApiAdmin role) and uploader user (uploader@azaion.com, ResourceUploader role) — see env/db/02_structure.sql.

Rollback: Standard PostgreSQL transactions; linq2db creates a new connection per Run/RunAdmin call.

5. Implementation Details

State Management: Stateless factory pattern. DbFactory is a singleton holding pre-built DataOptions. Cache state is in-memory per process.

Key Dependencies:

Library	Version	Purpose
linq2db	5.4.1	ORM for PostgreSQL access
Npgsql	10.0.1	PostgreSQL ADO.NET provider
LazyCache	2.4.0	In-memory cache with async support
Newtonsoft.Json	13.0.4	JSON serialization for UserConfig (bumped from 13.0.1 by security audit D-1, GHSA-5crp-9r3c-p9vr)

Error Handling Strategy:

• DbFactory.LoadOptions throws ArgumentException on empty connection strings (fail-fast at startup).
• Database exceptions from linq2db/Npgsql propagate unhandled to callers.

6. Extensions and Helpers

Helper	Purpose	Used By
StringExtensions.ToSnakeCase	PascalCase → snake_case column mapping	AzaionDbSchemaHolder
EnumExtensions.GetDescriptions	Enum → description dictionary	BusinessException
QueryableExtensions.WhereIf	Conditional LINQ filters	UserService

7. Caveats & Edge Cases

Known limitations:

• No connection pooling configuration exposed; relies on Npgsql defaults.
• AzaionDbSchemaHolder mapping schema is static — adding new entities requires code changes.
• Cache TTL (4 hours) is hardcoded, not configurable.

Potential race conditions:

• Cache invalidation after write: there's a small window where stale data could be served between the DB write and cache invalidation.

Performance bottlenecks:

• DbFactory creates a new connection per operation. For high-throughput scenarios, connection reuse or batching would be needed.

8. Dependency Graph

Must be implemented after: None (leaf component).

Can be implemented in parallel with: Security & Cryptography (no dependency).

Blocks: User Management, Authentication, Resource Management, Admin API.

9. Logging Strategy

Log Level	When	Example
INFO	SQL trace	SELECT * FROM users WHERE email = @p1 (via linq2db TraceLevel.Info)

Log format: Plaintext SQL output to console.

Log storage: Console (via Console.WriteLine in DbFactory.LoadOptions trace callback).

Modules Covered

• Common/Configs/ConnectionStrings
• Common/Configs/JwtConfig (AZ-532 — ES256 + session config)
• Common/Configs/AuthConfig (new in cycle 2 — AZ-536 + AZ-537)
• Common/Configs/ResourcesConfig
• Common/Entities/User (extended in cycle 2 — AZ-537 + AZ-534)
• Common/Entities/RoleEnum (extended in cycle 2 — AZ-535 added Service)
• Common/Entities/Session (new in cycle 2 — AZ-531 + AZ-535)
• Common/Entities/AuditEvent (new in cycle 2 — AZ-537)
• Common/Entities/DetectionClass (added cycle 1, AZ-513)
• Common/Database/AzaionDb (Sessions and AuditEvents ITables added in cycle 2)
• Common/Database/AzaionDbSchemaHolder (Session + AuditEvent mappings, jsonb for MfaRecoveryCodes)
• Common/Database/DbFactory
• Services/Cache