MOPC-App/docs/codex-architecture-redesign-docs/README.md

Monaco OPC Architecture Redesign (Codex Plan)

Purpose

This documentation set is a comprehensive redesign plan to align the current MOPC platform with the exact Monaco Ocean Protection Challenge flow you defined:

• Startups + Concepts in one competition lifecycle
• AI eligibility filtering
• Purpose-bound main juries as explicit entities (custom-labeled per program; often Jury 1 / Jury 2 / Jury 3)
• Round-specific submission bundles
• Special award routing modes
• Mentoring collaboration layer with promotion to official submissions
• Live finals control + final confirmation/lock workflow
• Full admin override and auditability
• End-to-end integration across all platform functions (including member invitation/onboarding/team flows)

The plan is intentionally designed to reduce current ambiguity and complexity while maximizing customizability through typed policies and explicit workflow entities.

Scope Of This Plan

This plan covers:

1. Current-state architecture audit (schema, services, routers, UI surfaces)
2. Target-state architecture mapped 1:1 to Monaco flow
3. Gap analysis and simplification decisions
4. Typed domain model and policy contracts
5. Platform-wide integration matrix (all major functions/pages)
6. Implementation roadmap and migration/cutover strategy
7. QA, observability, release gates
8. Open decisions/questions for flow owners

This plan does not implement code changes. It is an implementation-ready architecture and delivery blueprint.

Guiding Principles

1. Keep the stage engine; remove ambiguity around stage purpose.
2. Move critical competition behavior from loosely-typed configJson into typed models/policies.
3. Preserve admin override authority everywhere, but formalize override intent and audit structure.
4. Make jury/award/mentoring/finals flows first-class entities instead of inferred behavior.
5. Keep UX simple by exposing only context-relevant controls at each stage.
6. Ensure every user-facing workflow is backed by the redesigned architecture contract.

Document Index

• 01-current-platform-architecture-audit.md
• 02-monaco-flow-target-architecture.md
• 03-gap-analysis-and-simplification-decisions.md
• 04-unified-domain-model-and-config-contracts.md
• 05-platform-wide-integration-matrix.md
• 06-implementation-roadmap-and-migration-plan.md
• 07-testing-observability-and-release-gates.md
• 08-open-questions-for-flow-owners.md

Recommended Reading Order

1. Read 02-monaco-flow-target-architecture.md for the desired end state.
2. Read 03-gap-analysis-and-simplification-decisions.md to understand what must change and why.
3. Read 04-unified-domain-model-and-config-contracts.md for schema/API/behavior contracts.
4. Read 05-platform-wide-integration-matrix.md to see exact surface-level impact.
5. Read 06-implementation-roadmap-and-migration-plan.md + 07-testing-observability-and-release-gates.md for execution.
6. Resolve items in 08-open-questions-for-flow-owners.md before Phase 1 starts.

Success Criteria

The redesign is successful when:

• The platform can run your full Monaco flow without workarounds.
• Admins can configure and override all required decisions transparently.
• Judges, mentors, applicants, and audience each see role-appropriate, stage-aware UX.
• Invite/onboarding/team management, assignment, judging, mentoring, and finals workflows all reference the same underlying competition model.
• Audit evidence can reconstruct every advance/reject/override/winner decision.