MOPC-App/Notes.md

Below is a “technical requirements” rendering (not an architecture diagram), structured so you can hand it to a dev team and derive system architecture + backlog from it. Phase 1 is the only critical deliverable; Phase 2+ are explicitly extendable.

---

## 0) Product scope and phasing

### Phase 1 (critical, delivery in ~2 weeks)

**Secure Jury Online Voting Module** to run two selection rounds:

* Round 1: ~130 projects → ~60 semi-finalists (Feb 18–23 voting window)
* Round 2: ~60 projects → 6 finalists (~April 13 week voting window)
* Voting is asynchronous, online, with assigned project access, scoring + feedback capture, and reporting dashboards.

### Phase 2+ (mid-term)

Centralized MOPC platform:

* Applications/projects database
* Document management (MinIO S3)
* Jury spaces (history, comments, scoring)
* Learning hub / resources
* Communication workflows (email + possibly WhatsApp)
* Partner/sponsor visibility modules
* Potential website integration / shared back office

---

## 1) Users, roles, permissions (RBAC)

### Core roles

1. **Platform Super Admin**

   * Full system configuration, security policies, integrations, user/role management, data export, audit access.
2. **Program Admin (MOPC Admin)**

   * Manages cycles/rounds, projects, jury members, assignments, voting windows, criteria forms, dashboards, exports.
3. **Jury Member**

   * Can access only assigned projects for active rounds; submit evaluations; view own submitted evaluations; optionally view aggregated results only if permitted.
4. **Read-only Observer (optional)**

   * Internal meeting viewer: can see dashboards/aggregates but cannot edit votes.

### Permission model requirements

* **Least privilege by default**
* **Round-scoped permissions**: access can be constrained per selection round/cycle.
* **Project-scoped access control**: jury sees only assigned projects (unless admin toggles “all projects visible”).
* **Admin override controls**: reassign projects, revoke access, reopen/lock evaluations, extend voting windows, invalidate votes with reason logging.

---

## 2) Core domain objects (data model concepts)

### Entities

* **Program** (e.g., “MOPC 2026”)
* **Selection Cycle / Round**

  * Attributes: name, start/end of voting window, status (draft/active/closed/archived), required reviews per project (default ≥3), scoring form version, jury cohort.
* **Project**

  * Attributes: title, team name, description, tags, status (submitted/eligible/assigned/semi-finalist/finalist/etc.), submission metadata, external IDs (Typeform/Notion), files (exec summary, PDF deck, intro video).
* **File Asset**

  * Stored in MinIO (S3-compatible): object key, bucket, version/etag, mime type, size, upload timestamp, retention policy, access policy.
* **Jury Member**

  * Profile: name, email, organization (optional), role, expertise tags, status (invited/active/suspended).
* **Expertise Tag**

  * Managed vocabulary or free-form with admin approval.
* **Assignment**

  * Connects Jury Member ↔ Project ↔ Round
  * Attributes: assignment method (manual/auto), created by, created timestamp, required review flag, completion status.
* **Evaluation (Vote)**

  * Per assignment: criterion scores + global score + binary decision + qualitative feedback
  * Metadata: submitted_at, last_edited_at, finalization flag, versioning, IP/user-agent logging (optional), conflict handling.
* **Audit Log**

  * Immutable events: login, permission changes, voting window changes, assignments, overrides, exports, vote invalidations.

---

## 3) Phase 1 functional requirements

### 3.1 Jury authentication & access

* Invite flow:

  * Admin imports jury list (CSV) or adds manually.
  * System sends invitation email with secure link + account activation.
* Authentication options (choose one for Phase 1, keep others pluggable):

  * Email magic link (recommended for speed)
  * Password + MFA optional
* Session requirements:

  * Configurable session duration
  * Forced logout on role revocation
* Access gating:

  * Jury can only view projects for **active** rounds and only those assigned.

### 3.2 Project ingestion & management

Phase 1 can support either:

* **Option A (fastest): Manual import**

  * Admin uploads CSV with project metadata + file links or uploads.
* **Option B (semi-integrated): Sync from Notion/Typeform**

  * Read projects from existing Notion DB and/or Typeform export.

Minimum capabilities:

* Admin CRUD on projects (create/update/archive)
* Project tagging (from “Which issue does your project address?” + additional admin tags)
* Attach required assets:

  * Executive summary (PDF/doc)
  * PDF presentation
  * 30s intro video (mp4)
* File storage via MinIO (see Section 6)

### 3.3 Assignment system (≥3 reviews/project)

Admin can:

* Manually assign projects to jury members (bulk assign supported)
* Auto-assign (optional but strongly recommended):

  * Input: jury expertise tags + project tags + constraints
  * Constraints:

    * Each project assigned to at least N jurors (N configurable; default 3)
    * Load balancing across jurors (minimize variance)
    * Avoid conflicts (optional): disallow assignment if juror marked conflict with project
  * Output: assignment set + summary metrics (coverage, per-juror load, unmatched tags)
* Reassignment rules:

  * Admin can reassign at any time
  * If an evaluation exists, admin can:

    * keep existing evaluation tied to original juror
    * or invalidate/lock it (requires reason + audit event)

### 3.4 Evaluation form & scoring logic

Per project evaluation must capture:

* **Criterion scores** (scale-based, define exact scale as configurable; e.g., 1–5 or 1–10)

  1. Need clarity
  2. Solution relevance
  3. Gap analysis (market/competitors)
  4. Target customers clarity
  5. Ocean impact
* **Global score**: 1–10
* **Binary decision**: “Select as semi-finalist?” (Yes/No)
* **Qualitative feedback**: long text

Form requirements:

* Admin-configurable criteria text, ordering, scales, and whether fields are mandatory
* Autosave drafts
* Final submit locks evaluation by default (admin can allow edits until window closes)
* Support multiple rounds with potentially different forms (versioned forms per round)

### 3.5 Voting windows and enforcement (must-have)

Admins must be able to configure and enforce:

* Voting window start/end **per round** (date-time, timezone-aware)
* States:

  * Draft (admins only)
  * Active (jury can submit)
  * Closed (jury read-only)
  * Archived (admin/export only)
* Enforcement rules:

  * Jury cannot submit outside the active window
  * Admin “grace period” toggle to accept late submissions for specific jurors/projects
  * Admin can extend the window (global or subset) with audit logging
* Dashboard countdown + clear messaging for jurors

### 3.6 Dashboards & outputs

Must produce:

* **Jury member view**

  * Assigned projects list, completion status, quick access to files, evaluation status (not started/draft/submitted)
* **Admin dashboards**

  * Coverage: projects with <N evaluations
  * Progress: submission rates by juror
  * Aggregates per project:

    * Average per criterion
    * Average global score
    * Distribution (min/max, std dev optional)
    * Count of “Yes” votes
    * Qualitative comments list (with juror identity visible only to admins, configurable)
  * Shortlisting tools:

    * Filter/sort by aggregate score, yes-vote ratio, tag, missing reviews
    * Export shortlist (e.g., top 60 / top 6) with manual override controls
* Exports (Phase 1):

  * CSV/Excel export for:

    * Evaluations (row per evaluation)
    * Aggregates (row per project)
    * Assignment matrix
  * PDF export (optional) for meeting packs

---

## 4) Admin console requirements (robust)

### 4.1 Governance & configuration

* Create/manage Programs and Rounds
* Set:

  * Required reviews per project (N)
  * Voting windows (start/end) + grace rules
  * Evaluation form version
  * Visibility rules (whether jurors can see aggregates, whether jurors can see their past submissions after close)
* Manage tags:

  * Tag taxonomy, synonyms/merging, locked tags

### 4.2 User management & security controls

* Bulk invite/import
* Role assignment & revocation
* Force password reset / disable account
* View user activity logs
* Configure:

  * Allowed email domains (optional)
  * MFA requirement (optional)
  * Session lifetime (optional)

### 4.3 Assignment controls

* Manual assignment UI (single + bulk)
* Auto-assignment wizard:

  * select round
  * choose balancing strategy (e.g., “maximize tag match”, “balance load first”)
  * preview results
  * apply
* Conflict of interest handling:

  * Admin can mark conflicts (juror ↔ project)
  * Auto-assign must respect conflicts

### 4.4 Data integrity controls

* Vote invalidation (requires reason)
* Reopen evaluation (admin-only, logged)
* Freeze round (hard lock)
* Immutable audit log export

### 4.5 Integrations management

* Connectors toggles (Typeform/Notion/email provider/WhatsApp) with credentials stored securely
* MinIO bucket configuration + retention policies
* Webhook management (optional)

---

## 5) Non-functional requirements (Phase 1)

### Security

* TLS everywhere
* RBAC + project-level access control
* Secure file access (pre-signed URLs with short TTL; no public buckets)
* Audit logging for admin actions + exports
* Basic anti-abuse:

  * rate limiting login endpoints
  * brute-force protection if password auth used

### Reliability & performance

* Support:

  * Round 1: 15 jurors, 130 projects, min 390 evaluations
  * Round 2: ~30 jurors, 60 projects
* Fast page load for dashboards and project pages
* File streaming for PDFs/videos (avoid timeouts)

### Compliance & privacy (baseline)

* Store only necessary personal data for jurors/candidates
* Retention policies configurable (especially for candidate files)
* Access logs available for security review

---

## 6) File storage requirements (MinIO S3)

### Storage design (requirements-level)

* Use MinIO as S3-compatible object store for:

  * project documents (exec summary, deck)
  * video files
  * optional assets (logos, exports packs)
* Buckets:

  * Separate buckets or prefixes by Program/Round to simplify retention + permissions
* Access pattern:

  * Upload: direct-to-S3 (preferred) or via backend proxy
  * Download/view: **pre-signed URLs** generated by backend per authorized user
* Optional features:

  * Object versioning enabled
  * Antivirus scanning hook (Phase 2)
  * Lifecycle rules (auto-expire after X months)

---

## 7) “Current process” integration mapping (future-proof)

### Existing flow

* Typeform application → confirmation email → Tally upload → Notion tracking → Google Drive manual upload

### Platform integration targets

Phase 1 (minimal):

* Allow admin to ingest projects and upload assets (replace Drive for jury-facing access)

Phase 2 options:

* Typeform: pull submissions via API/webhooks
* Tally: capture uploads directly to MinIO (or via platform upload portal)
* Notion: sync project status + metadata (one-way or two-way)
* Email automation: reminder workflows for incomplete applications

---

## 8) Additional ideas as “technical backlog candidates”

### Automated follow-ups for incomplete applications (Phase 2)

* State machine for applications: registered → awaiting docs → complete → expired
* Scheduler:

  * send reminders at configurable intervals (e.g., +2d, +5d, +7d)
  * stop on completion
* Channels:

  * Email must-have
  * WhatsApp optional (requires compliance + provider; store consent + opt-out)

### Learning hub access (semi-finalists only)

* Resource library stored in MinIO + metadata in DB
* Access controlled by cohort + passwordless login or access tokens
* Expiring invite links

### Website integration

* Shared identity/back office (SSO-ready) OR separate admin domains
* Public-facing site remains content-only; platform is operational hub
* Requirement: clear separation between “public content” and “private jury/applicant data”

---

## 9) Acceptance criteria checklist (Phase 1)

1. Admin can create a round, set voting window (start/end), and activate it.
2. Admin can import projects + upload/attach required files to MinIO.
3. Admin can import jurors, invite them, and jurors can log in securely.
4. Admin can assign projects (manual + bulk). Auto-assign is optional but if included must guarantee ≥3 reviews/project.
5. Juror sees only assigned projects, can view files, and submit evaluation form.
6. System blocks submissions outside the voting window (unless admin-granted exception).
7. Admin dashboard shows progress + aggregates per project; admin can export results.
8. All critical admin actions are audit-logged.
9. File access is protected (no public links; pre-signed URLs with TTL).

---

If you want, I can turn this into:

* a clean PRD-style document (Dev-ready) **plus**
* a ticket breakdown (Epics → user stories → acceptance tests) for Phase 1 delivery.