feat: prepare ARR for controlled public deployment

.project-docs/20-architecture/system-overview.md

@@ -0,0 +1,33 @@
+# System Overview
+
+## Current Architecture
+
+The ARR system accepts an Opera XML upload, stores the private source artifact, invokes an Agent for deterministic processing, validates the returned structured result, and commits accepted Finance facts to PostgreSQL. Downstream analytics and report programs consume those committed facts. The accepted target flow automatically triggers monthly processing after the commit; the current manual monthly UI/API remains a known implementation gap.
+
+## Main Components
+
+| Component | Responsibility | Notes |
+|---|---|---|
+| `arr_web` | XML upload, job status, controlled downloads and business APIs | The existing manual monthly-generation request is not the accepted primary flow. |
+| SuperAgent + deterministic processing skill | Convert XML to the approved structured result | Must not decide user-facing report parameters. |
+| `arr_mcp` / ingestion service | Independently validate/replay and atomically commit accepted structured results | Automatic downstream trigger begins only after commit success. |
+| PostgreSQL Finance facts | Authoritative current and retained daily facts | Source of truth for downstream reports. |
+| `monthly_reports` | Generate monthly XLSX from committed database facts | Internal month/cutoff inputs are allowed; `TOTAL PRICE` must be an XLSX formula. |
+| `channel_analytics` / `company_reports` | Additional read/report consumers | Must not change the monthly-report trigger contract. |
+| Caddy + Compose deployment boundary | Terminate HTTPS, authenticate Web users, keep Web/MCP ports internal and start the explicit processing profile | MCP still performs its own bearer check and DNS-rebinding Host validation. |
+
+## Important Boundaries
+
+- XML processing and Finance fact validation happen before the monthly-report trigger.
+- The user-facing upload workflow does not collect monthly report year, month, or cutoff date.
+- Monthly processing reads validated database facts rather than repeating Agent business logic.
+- Database `total_price` may support validation, but the exported `TOTAL PRICE` cell must remain a formula.
+- Public deployment enables XML processing only through the explicit Compose command and requires `processing_ready=true`; it does not change local/application defaults.
+
+## Related Decisions
+
+- [ADR-001](../10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md)
+
+## Last Updated
+
+2026-07-29