Project Plan Overview¶

AI-Native, Standards-First EDC Platform for Modern Clinical Trials

An ODM-aligned, assessment-centric clinical trial system with governed AI co-pilots and specialized support for rare disease and pediatric studies.

Document Status: Active Last Updated: 2026-01-22

Recent Update: AI Agent Phase 2 (Protocol Ingestion) complete. Adds PDF document processing service, protocol ingestion system prompt and task executor, ChangeSet creation from extracted study structure (events, forms), and StudyAssistant portal page with document upload, task execution, and ChangeSet review workflow.

1. Purpose and Vision¶

Metricis is a next-generation Electronic Data Capture (EDC) platform designed to support regulated clinical trials, with particular strength in rare disease and pediatric research.

The platform is built to:

Meet ICH-GCP, Health Canada, FDA, and EMA expectations
Support complex, longitudinal, small-N studies
Reduce operational burden through AI-assisted workflows
Maintain inspection-grade auditability and governance
Separate professional (site) and participant/caregiver experiences while sharing a common backend

The system treats metadata governance, consent, assessments, and amendments as first-class citizens rather than edge cases.

2. Implementation Status¶

2.1 Completed Capabilities (✅)¶

The following major subsystems are fully implemented and operational:

Subsystem	Status	Details
Study Runtime	✅ Complete	Enrollment, visit scheduling, form data entry, session management
Metadata Versioning	✅ Complete	Draft → Review → Approved → Published lifecycle with PI signatures
jsPsych Assessments	✅ Complete	Battery versioning, queue management, reconciliation on amendment
eConsent	✅ Complete	Versioned consent, signature capture, consent gating, re-consent triggers
RBAC & Audit	✅ Complete	Role-based access, immutable audit trail, 21 CFR Part 11 signatures
SDTM/ODM Export	✅ Complete	SDTM domain export (DM, AE, SV, etc.), ODM-XML, Define-XML
Validation Services	✅ Complete	SDTM validation (Pinnacle 21-style), regulatory compliance checks
Portal UI	✅ Complete	38+ pages including Dashboard, Participants, Forms, Reports, Export, Registries
Patient/Caregiver Portal	✅ Complete	Magic link auth, task queue, consent signing, mobile-first UI
Rare Disease Phase 1-2	✅ Complete	Rare pediatric mode, actor badges, assessment burden minimization, partial completions
Rare Disease Phase 3	✅ Complete	Phenotype tracking, amendment narratives, impact analysis
Rare Disease Phase 4	✅ Complete	Narrative exports, audit viewer, phenotype SDTM mappings, patient summary
AI Agent Phase 1	✅ Complete	Foundation infrastructure - database models, LLM service, ChangeSet workflow, REST API
AI Agent Phase 2	✅ Complete	Protocol Ingestion - PDF processing, study structure extraction, StudyAssistant page
Patient Registry Phase 1-4	✅ Complete	Registry foundation, trial linkage, AI summaries, natural history modeling, follow-up cohorts, cohort management UI

For detailed implementation documentation, see EDC Implementation Plan.

2.2 In Progress (🔄)¶

Capability	Phase	Status	Specification
AI Agent Facilitation	Phase 3: Battery Configuration	Planned	ai-agent-implementation-plan.md

2.3 Planned Capabilities (🔜)¶

The following capabilities are designed but not yet implemented:

Capability	Description	Specification
AI Agent Phase 3	Battery & Assessment Configuration Assistance	ai-agent-implementation-plan.md
AI Agent Phase 4	Amendment Impact Analysis & Cutover Planning	ai-agent-implementation-plan.md

3. High-Level Architecture¶

3.1 Core Architectural Principles¶

Single authoritative backend with versioned metadata and audit trail
Multiple frontends tailored to distinct actors:
Site-facing EDC Portal (CRC, PI, DM, Monitor, Safety)
Patient/Caregiver Portal (web + mobile)
Strict role-based access control (RBAC) and scope-limited APIs
ODM-informed data model with explicit version binding
AI agent facilitation embedded in governance, not automation without oversight — planned
jsPsych integration and modules for cognitive eCOAs and ePROs

3.2 System Decomposition¶

┌─────────────────────────────────────────────────────────────────┐
│                     Metricis Platform                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Portal    │  │   Client    │  │   Patient/Caregiver     │  │
│  │   (React)   │  │  (jsPsych)  │  │   Portal (React)        │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
│  ───────┴────────────────┴──────────────────────┴───────────────│
│                          FastAPI Backend                         │
│  ┌──────────┬──────────┬──────────┬──────────┬───────────────┐  │
│  │  Study   │ Metadata │ Consent  │ Assess-  │ RBAC/Audit    │  │
│  │ Runtime  │ Version  │ Service  │ ments    │ Service       │  │
│  └──────────┴──────────┴──────────┴──────────┴───────────────┘  │
│  ┌──────────┬──────────┬──────────┬──────────────────────────┐  │
│  │  Query   │  Safety  │  Export  │  AI Assistant (planned)  │  │
│  │ Service  │ Service  │ Services │                          │  │
│  └──────────┴──────────┴──────────┴──────────────────────────┘  │
│         │                                                        │
│  ───────┴───────────────────────────────────────────────────────│
│                     PostgreSQL + Redis                           │
└─────────────────────────────────────────────────────────────────┘

4. Functional Domains¶

4.1 Study Runtime (EDC – Site-Facing) ✅¶

Supports day-to-day trial execution:

Study dashboards (status, quality, safety signals)
Participant enrollment and lifecycle management
Visit scheduling and window management
Role-centric data entry (CRFs, ClinRO, ObsRO)
Query and discrepancy management
Safety reporting (AE/SAE)
Data review, coding (MedDRA / WHO-DD), freeze, lock
Regulatory-ready reports and exports (ODM, SDTM, ADaM)
Global, immutable audit trail access

Implementation: See server/app/routers/ and portal/src/pages/

4.2 Metadata Governance & Configuration ✅¶

Supports controlled study design and change management:

Versioned Study Design (visits, forms, rules)
Metadata lifecycle (draft → approve → publish)
Explicit diffing and impact analysis
Standards & terminology management
Rules and derivations (edit checks, calculations)
Mappings to downstream standards
Protocol amendment workflows as a routine operation

Implementation: See server/app/services/metadata_service.py

4.3 Assessments (jsPsych / eCOA) ✅¶

First-class support for participant-completed assessments:

Module library and battery builder
Battery versioning and event binding
Adaptive and partial completion support
Assessment delivery via web/mobile (Capacitor)
Raw signal capture and analysis-ready outputs
Full provenance (battery version, metadata version, consent version)
Compliance and quality monitoring in the EDC

Implementation: See server/app/services/assessment_queue_service.py

4.4 eConsent ✅¶

Comprehensive, versioned consent management:

Consent document authoring and versioning
Language variants and signature workflows
Pediatric consent and assent transitions
Event-based consent gating
Re-consent triggered by protocol amendments or age milestones
Non-repudiable signatures and auditability

Implementation: See server/app/services/consent_service.py and server/app/services/reconsent_service.py

4.5 Patient & Caregiver Portal ✅¶

A dedicated, task-focused experience for families:

Magic link (passwordless) authentication
Caregiver- and participant-linked identities with delegation support
Unified task queue aggregating consent and assessment tasks
Mobile-first, accessible UI with i18n (English/French)
Partial and interrupted task handling
Explicit attribution of caregiver vs participant actions
Study contact information access

The portal executes consent and assessments; the EDC monitors and governs them.

Implementation: - Backend: server/app/routers/portal.py, server/app/services/portal_auth_service.py - Frontend: patient-portal/src/

Specification: patient-caregiver-portal.md

4.6 Rare Disease & Pediatric Adaptations (Phases 1-3 ✅, Phase 4 🔄)¶

Specialized support for rare pediatric trials:

Phase 1 (Complete): - Rare pediatric mode feature flag per study - Actor badge showing caregiver/participant identity - Enhanced caregiver model with actor display names

Phase 2 (Complete): - Assessment burden minimization with step-based progress - Partial completion capture with structured exit reasons - Assessment feasibility records

Phase 3 (Complete): - Longitudinal phenotype state tracking - Phenotype state transitions with clinical significance flags - Amendment impact analysis with per-participant narratives - Impact preview before applying amendments - Non-alarmist amendment banners for participants

Phase 4 (Next): - Narrative export service for regulatory packages - Phenotype data in SDTM exports - Actor attribution reports - Participant-centric audit viewer

Implementation: - Backend: server/app/services/phenotype_service.py, server/app/services/amendment_impact_service.py - Portal: portal/src/components/participant/ - Patient Portal: patient-portal/src/components/AmendmentBanner.tsx

Specification: rare-disease-integration.md

5. Planned Capabilities¶

5.1 AI Agent Facilitation 🔄¶

AI agents are embedded as governed co-pilots, not autonomous actors.

Implementation Status:

Phase	Description	Status
Phase 1	Foundation - Database models, LLM service, ChangeSet infrastructure	✅ Complete
Phase 2	Protocol Ingestion & Study Structure Generation	🔜 Next
Phase 3	Battery & Assessment Configuration Assistance	🔜 Planned
Phase 4	Amendment Impact Analysis & Cutover Planning	🔜 Planned

Phase 1 Deliverables (Complete): - Database models: AgentDocument, AgentRun, ChangeSet, ChangeSetItem - LLMService with Anthropic Claude integration (optional dependency) - AgentService for task orchestration - ChangeSetValidator for pre-apply validation - Full REST API at /api/studies/{study_id}/ai/* - Comprehensive audit logging for all AI operations

Key constraints: - AI outputs are always drafts - Human review and approval required - No autonomous publishing, consent activation, or data lock - All AI activity is auditable and distinguishable from human actions

Full specification: ai-assistant.md Implementation plan: ai-agent-implementation-plan.md

5.2 AI Agent Phase 2: Protocol Ingestion 🔜¶

The next phase of AI Agent implementation adds the first visible capability:

Protocol PDF parsing and text extraction
Schedule of Activities (SoA) interpretation
StudyEventDef proposal generation with timing windows
FormDef stub creation
Source reference tracking (section, page)

Full specification: ai-agent-implementation-plan.md

5.3 Patient Registry Capability ✅¶

Patient registries are first-class peers to studies, supporting:

Observational registries: Natural history, longitudinal tracking
Trial-adjacent registries: Pre-trial, post-trial follow-up
Platform registries: Disease-wide, multi-study reference
Patient-initiated registries: Direct enrollment via portal

Implementation Phases:

Phase	Description	Status
Phase 1	Registry Foundation - Entity, participants, consent, phenotypes	✅ Complete
Phase 2	Registry-Trial Linkage - Consent-gated study links	✅ Complete
Phase 3	Advanced Analytics - AI summaries, natural history, follow-up cohorts	✅ Complete
Phase 4	UI Completion - Cohort modal, phenotype updates, contact tracking, dashboard counts	✅ Complete

Key Features:

Feature	Description
Phenotype-centric data model	Longitudinal phenotype tracking (vs. visit-centric EDC)
Consent-gated linkage	Granular consent purposes (feasibility, recruitment, data_sharing, ai_analytics)
Registry participants	Master identity owning phenotypes, linkable to studies
State transitions	Phenotype progression/regression tracking with clinical significance
AI phenotype summaries	LLM-generated disease trajectory narratives (requires ai_analytics consent)
Natural history modeling	Markov transition matrices, cohort queries, progression statistics
Follow-up cohorts	Post-trial, natural history, and phenotype-subset cohort management

Implementation:

Backend Services:
server/app/services/registry_service.py - Core registry operations
server/app/services/registry_analytics_service.py - AI summaries, transition matrices
server/app/services/registry_followup_service.py - Cohort management
API Routers:
server/app/routers/registries.py - Core registry API
server/app/routers/registry_analytics.py - Analytics API
server/app/routers/registry_followup.py - Follow-up cohorts API
Database Models: Registry, RegistryParticipant, RegistryConsent, RegistryPhenotype, RegistryPhenotypeSummary, RegistryNaturalHistoryStats, RegistryFollowUpCohort, RegistryFollowUpCohortMember
Portal Components:
portal/src/components/registry/PhenotypeSummaryCard.tsx - AI summary display
portal/src/components/registry/TransitionMatrixChart.tsx - Heatmap visualization

Portal Routes:

Route	Page	Purpose
`/registries`	Registries	List all registries with filtering
`/registries/:id`	RegistryOverview	Registry dashboard with stats
`/registries/:id/participants`	RegistryParticipants	Participant list and enrollment
`/registries/:id/participants/:pid`	RegistryParticipantDetail	Participant detail with phenotypes and consent
`/registries/:id/analytics`	RegistryAnalytics	AI summaries, natural history, follow-up cohorts
`/registries/:id/cohorts/:cid`	CohortDetail	Cohort management with members, contacts, auto-population

Specification: participant-registry.md

6. Security, Compliance, and Audit ✅¶

Fine-grained RBAC enforced at UI, API, and service layers
Separate API scopes for EDC and Portal
Immutable, append-only audit event store
Comprehensive audit taxonomy covering:
Metadata, consent, assessments, AI activity, overrides
Regulator-facing audit trail narratives and reports
Health Canada–aligned inspection readiness

7. Expected Outcomes and Differentiation¶

This platform enables:

Faster and safer study initiation
Reduced site and family burden
Better handling of evolving rare disease protocols
Clear regulatory defensibility
Scalable reuse across studies without bespoke builds

The result is an EDC ecosystem that treats complexity, ethics, and longitudinal care as core design drivers rather than exceptions.

8. Documentation Structure¶

8.1 Active Documentation¶

Document	Purpose
This file (`project-plan.md`)	High-level vision and status
ai-assistant.md	AI Agent Facilitation specification
patient-caregiver-portal.md	Patient/Caregiver Portal specification (implemented)
rare-disease-integration.md	Rare disease and pediatric adaptations
EDC Implementation Plan	Detailed technical implementation (complete)
UI README	Portal UI design system
Patient Portal	Patient/Caregiver Portal implementation

8.2 Reference Assets¶

Asset	Purpose
`ui-mockup.pptx`	UI mockup presentation
`sidbar-menu-top-menu.png`	Menu mockup image

8.3 Archived Documentation¶

Completed specifications that informed the current implementation have been moved to docs/archive/completed-plans/:

sidebar-menu.md - Sidebar menu specifications (implemented)
amendment-sop.md - Amendment SOP (implemented)
role-based-visibility.md - RBAC visibility matrix (implemented)
edc-prototype-implementation-plan.md - Original EDC prototype plan
edc-implementation-odm-mapping.md - ODM mapping specifications
edc-stress-test-scenarios.md - Amendment stress test scenarios
jsPysch-integration-plan.md - jsPsych integration (implemented)
surveyJS-integration-plan.md - SurveyJS integration (implemented)
redcap-gap-analysis.md - REDCap gap analysis
rbac/ - RBAC role mapping documents

9. Implementation Priorities¶

9.1 Current: AI Agent Phase 2 (Protocol Ingestion)¶

Rationale: First visible AI capability - accelerates study setup from protocols.

Key milestones: 1. Document processing (PDF text extraction) 2. Protocol ingestion task implementation 3. System prompt templates 4. Basic Portal UI (StudyAssistant page) 5. End-to-end testing

9.2 Next Phase: AI Agent Phase 3 (Battery Configuration)¶

Rationale: Extends AI assistance to jsPsych assessment setup.

Key milestones: 1. Battery configuration task 2. Event linking proposals 3. Inline assists in BatteryBuilder 4. Validation pipeline for battery proposals