epic(platform-hardening): reconcile architecture, security, delivery, docs, and operations #679

Context

A repository-wide static audit of AWCMS-Mini at commit 4b6ccfcde3be3f00f7aea6d1dba987d60fda1f34 found cross-cutting risks that should be resolved before further module expansion. The repository currently contains 14 registered modules, 44 migrations, 76 tables, 127 API route files, 168 handlers, 127 OpenAPI paths, 156 test files, and 57 documentation files.

The audit was static because Bun was not available in the audit environment. This epic records evidence and required verification; it does not claim the current CI suite is green.

Objective

Reconcile architecture, security, delivery, documentation, operations, and admin UX through independently reviewable issues, while preserving AWCMS-Mini's offline/LAN-first defaults.

Guardrails

• Keep the runtime a modular monolith with a trusted static module registry.
• Do not add runtime upload/install of arbitrary third-party code or a public module marketplace.
• Preserve local/offline/LAN behavior. Online-provider behavior remains explicit and opt-in.
• Tenant-scoped data requires tenant_id, ABAC, withTenant, RLS, and FORCE RLS.
• External provider calls stay outside database transactions.
• Never commit or expose secrets, raw credentials, access tokens, or unnecessary personal data.
• Use the next available migration number at implementation time.
• Each child issue is atomic and adds focused tests/docs appropriate to its change.

Child issues

P0 — release blockers

• fix(modules): eliminate core module dependency cycles and add DAG validation #680
• refactor(architecture): replace blog-content/news-portal circular imports with capability ports #681
• security(db): replace schema-wide DML grants with per-role least-privilege grants #683
• security(api): enforce global and endpoint-specific request body limits #686
• fix(preflight): make production preflight non-destructive before quality gates #684
• security(deploy): harden Docker Compose, PgBouncer, and production image defaults #682
• ci(contracts): run API spec, route parity, module graph, and i18n parity gates #685

P1 — maintainability and operational readiness

• security(logging): normalize and redact server-side and worker errors #687
• docs(governance): define core, system, official optional module, and derived-app admission policy #696
• docs: reconcile repository status, version, module inventory, and GitHub snapshot #688
• refactor(config): add typed configuration schema and remove dead environment variables #689
• i18n: generate messages.pot and enforce EN/ID/POT key parity #694
• refactor(api): split OpenAPI by module and enforce route-operation-security parity #695
• refactor(jobs): add shared worker runner, locks, batching, and JSON telemetry #697
• security(backup): add encrypted backup, checksum-before-restore, off-site copy, and restore drill #691
• feat(ui): add responsive admin navigation and reusable admin component library #693
• chore(visitor-analytics): add rollup, retention purge, readiness checks, and docs #624 — existing visitor-analytics issue updated and reopened with audit privacy deltas
• feat(news-media): add pending/orphan R2 media lifecycle cleanup and reconciliation #690
• ci(release): automate Changesets release, SBOM, image signing, and provenance #692

P2 — measurable reliability

• feat(observability): add metrics, SLOs, job health, and provider telemetry #698
• test(resilience): add failure-injection and disaster-recovery verification #699
• docs(api): publish generated API and event reference documentation #700

Recommended implementation order

1. Architecture and authority: fix(modules): eliminate core module dependency cycles and add DAG validation #680, refactor(architecture): replace blog-content/news-portal circular imports with capability ports #681, security(db): replace schema-wide DML grants with per-role least-privilege grants #683, security(api): enforce global and endpoint-specific request body limits #686.
2. Safe delivery baseline: fix(preflight): make production preflight non-destructive before quality gates #684, security(deploy): harden Docker Compose, PgBouncer, and production image defaults #682, security(backup): add encrypted backup, checksum-before-restore, off-site copy, and restore drill #691.
3. Sources of truth and gates: refactor(config): add typed configuration schema and remove dead environment variables #689, i18n: generate messages.pot and enforce EN/ID/POT key parity #694, refactor(api): split OpenAPI by module and enforce route-operation-security parity #695, then ci(contracts): run API spec, route parity, module graph, and i18n parity gates #685.
4. Runtime/worker hardening: security(logging): normalize and redact server-side and worker errors #687, refactor(jobs): add shared worker runner, locks, batching, and JSON telemetry #697, chore(visitor-analytics): add rollup, retention purge, readiness checks, and docs #624, feat(news-media): add pending/orphan R2 media lifecycle cleanup and reconciliation #690.
5. Governance, docs, UI, and release: docs(governance): define core, system, official optional module, and derived-app admission policy #696, docs: reconcile repository status, version, module inventory, and GitHub snapshot #688, feat(ui): add responsive admin navigation and reusable admin component library #693, ci(release): automate Changesets release, SBOM, image signing, and provenance #692.
6. Operational proof: feat(observability): add metrics, SLOs, job health, and provider telemetry #698, test(resilience): add failure-injection and disaster-recovery verification #699, docs(api): publish generated API and event reference documentation #700.

Parallel work is safe within a wave when files do not overlap. #685 should consume the checks built by #680/#681/#694/#695. #699 should follow the relevant preflight, backup, and worker-runner work.

Completion criteria

• Every linked child issue is closed or explicitly moved to a follow-up epic with rationale.
• P0 issues are completed before production go-live.
• Relevant unit, integration, E2E, contract, docs, and security-readiness gates pass in CI.
• Offline/LAN defaults remain functional without external providers.
• Architecture, env reference, data dictionary, threat model, deployment runbook, and release docs match the implemented repository.
• A final production preflight is run against a non-production rehearsal environment before go-live.

Related existing work

This epic complements rather than replaces module management #510, public routing #555, online auth #587, visitor analytics #617, news portal #631, master regions #654, and Hermes #668.