docs(): added RUNBOOK, compliance matrix, ADR, refactored C4 and

repository map

zavoz

assets/plantuml/raw/c4-component-critical-path.puml

@@ -7,20 +7,21 @@ title LOTTY Backend - C4 Component
 
 Container_Boundary(api, "Backend Container (Django + Django Ninja)") {
   Component(decision_endpoint, "Decision Endpoint", "api/v1/decision/endpoints.py", "POST /api/v1/decide")
-  Component(decision_service, "Decision Service", "apps/decision/services.py", "Flag lookup, targeting DSL, participation limits, hash-based variant assignment")
+  Component(decision_service, "Decision Service", "apps/decision/services.py", "Flag lookup, targeting DSL, limits/conflicts, hash-based assignment, decide-result cache, sync/async decision persistence")
 
   Component(events_endpoint, "Events Endpoint", "api/v1/events/endpoints.py", "POST /api/v1/events")
   Component(events_service, "Events Service", "apps/events/services.py", "Validation, dedup, exposure/conversion attribution, pending promotion")
+  Component(events_tasks, "Events Tasks", "apps/events/tasks.py", "persist_decision, cleanup pending")
 
   Component(reports_endpoint, "Reports Endpoint", "api/v1/reports/endpoints.py", "GET /reports/{experiment_id}")
-  Component(reports_service, "Reports Service", "apps/reports/services.py", "Per-variant metric calculation (ratio, count, average, percentile)")
+  Component(reports_service, "Reports Service", "apps/reports/services.py", "Per-variant metrics (ratio/count/average/percentile)")
 
   Component(guardrails_service, "Guardrails Service", "apps/guardrails/services.py", "Threshold checks, auto pause/rollback")
 }
 
 ContainerDb(db, "Relational DB", "PostgreSQL / SQLite", "Flags, experiments, variants, decisions, events, exposures")
-Container(cache, "Cache", "Valkey / LocMem", "Flag and active experiment cache")
-Container(worker, "Celery Beat", "Celery", "Periodic guardrail checks (60s)")
+Container(cache, "Cache + Broker", "Valkey / Redis / LocMem", "Flag/active experiment/decide-result cache, Celery broker")
+Container(worker, "Celery Worker / Beat", "Celery", "Periodic guardrails/notifications/cleanup + async decision persistence")
 
 Rel(decision_endpoint, decision_service, "Delegates")
 Rel(decision_service, cache, "Reads cached flag / active experiment")
@@ -28,6 +29,7 @@ Rel(decision_service, db, "Reads variants, writes Decision")
 
 Rel(events_endpoint, events_service, "Delegates batch")
 Rel(events_service, db, "Writes Event / Exposure / PendingEvent")
+Rel(events_tasks, db, "Writes Decision async")
 
 Rel(reports_endpoint, reports_service, "Builds report")
 Rel(reports_service, db, "Reads attributed events / exposures")

assets/plantuml/raw/c4-container.puml

@@ -11,8 +11,8 @@ Person(ops_user, "Experimenter/Approver/Admin/Viewer")
 System_Boundary(lotty_boundary, "LOTTY Backend") {
   Container(api, "Backend API", "Django + Ninja", "REST endpoints: flags, experiments, decide, events, reports, guardrails, notifications, conflicts, metrics, learnings, reviews, users, auth")
   ContainerDb(db, "PostgreSQL / SQLite", "Relational DB", "Experiments, variants, decisions, events, exposures, outcomes, guardrails, notifications, conflicts, logs")
-  Container(cache, "Valkey / LocMem Cache", "Cache + Celery broker", "Flag/experiment cache, Celery task broker")
-  Container(worker, "Celery Worker / Beat", "Background worker", "Periodic: guardrails check, notifications flush, pending events cleanup")
+  Container(cache, "Valkey / Redis / LocMem Cache", "Cache + Celery broker", "Flag/experiment/decide-result cache, Celery task broker")
+  Container(worker, "Celery Worker / Beat", "Background worker", "Periodic jobs + async decision persistence")
 }
 
 System_Ext(notifications, "Notification Channels", "Telegram / SMTP")
@@ -20,9 +20,9 @@ System_Ext(notifications, "Notification Channels", "Telegram / SMTP")
 Rel(product_client, api, "Gets flag decisions, sends events", "HTTP/JSON")
 Rel(ops_user, api, "Admin/experiment/review calls", "HTTP/JSON")
 Rel(api, db, "Read/write application state", "SQL")
-Rel(api, cache, "Read/write cache", "Redis protocol")
+Rel(api, cache, "Read/write cache, enqueue async tasks", "Redis protocol")
 Rel(worker, db, "Read/write application state", "SQL")
-Rel(worker, cache, "Receives tasks, reads cached state", "Redis protocol")
+Rel(worker, cache, "Consumes tasks, reads cached state", "Redis protocol")
 Rel(worker, notifications, "Delivers queued notifications", "HTTP / SMTP")
 
 @enduml