curriculum-project-hub/.scratch/saas-production-readiness/map.md

Initial Production SaaS Readiness

Label: wayfinder:map

Destination

The repository can be deployed from a clean checkout as the initial production multi-tenant Curriculum Project Hub: platform staff manage Organizations; every Organization authenticates through and operates its own customer-owned Feishu app/bot, and selects either an Organization-managed BYOK provider connection or a distinct platform-managed provider connection; Organization owners/admins manage their own members, projects and settings. The ADR-0018/0020/0021 single-host Linux topology is operated with repeatable release evidence, rollback and recovery, and no known critical security or data-integrity gaps.

Notes

• spec/ remains the semantic source of truth; implementation drift must be surfaced rather than silently resolved.
• The initial product boundary follows the accepted ADRs: Organization is the tenant root and customer onboarding may be manual. Full billing, tenant suspension, and self-service platform administration remain deferred; ADR-0022's safety limits and workload brakes are required for production.
• Manual guided setup may provision each Organization's customer-owned Feishu app during the pilot; one process-global Feishu/OAuth credential shared by unrelated Organizations is not an acceptable destination state.
• Use the diagnosing-bugs loop for every reproduced defect. Prefer explicit failures and observable critical paths over fallback behavior.
• Work directly on main per developer authorization; make small conventional commits after verified, independently reversible milestones. Do not push without explicit authorization.
• Local lake build currently requires a configured elan toolchain; CI remains the authoritative configured Lean build environment until that local toolchain is available.

Decisions so far

• Audit the clean-host deployment and rollback contract — keep the accepted single-host topology, but replace the incomplete in-place updater with a provisioned, immutable, readiness-gated and rollbackable release contract.
• Audit tenant, authentication, and request security boundaries — retain the working org-admin/application authorization core, but production is blocked on agent/MCP isolation, execution-time object binding, org-scoped encrypted credentials, tenant status, browser sessions, and clean dependency audits.
• Audit run lifecycle and data integrity under failure — retain the database-enforced project-lock uniqueness and normal happy path, but replace receipt-before-success, process-local queues, independent run/session/lock effects, silent delivery/audit loss, and partial startup reset with durable, recoverable state machines; explicitly decide failed-run workspace semantics.
• Define production observability and incident recovery — keep the existing Fastify/Prisma/systemd signal fragments, but production requires dependency-aware readiness, typed and correlated errors, durable-work telemetry, an explicit SLO/retention/alerting control plane, and recovery runbooks proven by fault drills.
• Define initial abuse and capacity controls — require layered fail-closed limits, durable Organization-fair admission, explicit backpressure, bounded files/storage/runs, soft usage alerts, and audited emergency workload brakes; calibrate numerical ceilings under production-like load.
• Audit backup, migration, and disaster recovery safety — separate persistent state from releases, define a database/workspace checkpoint and recovery objectives, make migrations compatibility-gated, and prove complete off-host backup sets through isolated restore and cutover drills.
• Audit the accepted product surface for production completeness — retain the guarded Organization APIs and single-app Feishu vertical slice, but require explicit Organization-scoped Feishu/provider connections and external-identity namespaces, private platform and Organization admin control planes, and the full ADR-0022 capacity surface before release.
• Decide the platform-administrator identity and audit boundary — use a dedicated platform Feishu issuer, one peer administrator role, guarded bootstrap and identity-bound invitations, revocable server-side sessions, atomic append-only Platform Audit, and dual-factor offline recovery without a standing break-glass account.
• Restore the checker formatting gate — pin local and CI Rust/rustfmt/clippy to 1.92.0, apply the canonical workspace format, and keep the full fmt + clippy + 53-test checker gate green.

Fog

• The production topology after the initial single-host pilot (HA, horizontal workers, multi-region, or managed container orchestration) depends on measured demand and failure experience.
• Commercial self-service concerns such as billing plans and automated tenant provisioning remain beyond the accepted ADR boundary; revisit after the initial safety and operability route is clear.
• Regulatory retention, residency, and customer-specific compliance controls require product/legal inputs that the repository does not currently contain.