MOPC-App/docs/codex-architecture-redesign.../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.
Competition/Round architecture: full platform rewrite (Phases 1-9) Replace Pipeline/Stage system with Competition/Round architecture. New schema: Competition, Round (7 types), JuryGroup, AssignmentPolicy, ProjectRoundState, DeliberationSession, ResultLock, SubmissionWindow. New services: round-engine, round-assignment, deliberation, result-lock, submission-manager, competition-context, ai-prompt-guard. Full admin/jury/applicant/mentor UI rewrite. AI prompt hardening with structured prompts, retry logic, and injection detection. All legacy pipeline/stage code removed. 4 new migrations + seed aligned. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-02-15 23:04:15 +01:00			`# 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.`