System Architecture

Metricis is a modular monorepo with several user-facing surfaces sharing one governed service and data layer. Boundaries are organized around research contexts and responsibilities rather than around a single assessment type.

Runtime surfaces

Surface	Technology	Responsibility
Researcher portal	React 18, Vite, React Query	Study, registry, participant, form, consent, quality, monitoring, integration, and export operations
Participant portal	React 18, Vite	Passwordless participant/caregiver experience, context-aware work, consent, diaries, questionnaires, and schedules
Assessment client	TypeScript, Vite, jsPsych 8, Capacitor 8	Focused cognitive-task execution on web, iOS, and Android
API server	FastAPI, SQLAlchemy	Authentication, domain rules, data access, audit provenance, API contracts, and workflow enforcement
Background workers	Celery, Redis	Notifications, reconciliation, scheduled work, and configured integration jobs
Public edge workers	Cloudflare Workers	Published study/registry information and participant interest or join pathways

Domain boundaries

The server groups behavior into related but separable domains:

• Studies and registries: distinct context models, membership, sites, cohorts, arms, schedules, and lifecycle state.
• Identity and access: researcher roles, scoped API tokens, participant accounts, magic links, caregiver attribution, and context membership.
• Forms and governance: FormSpec definitions and versions, release pinning, responses, validation, change classification, signatures, and locks.
• Assessment delivery: task modules, battery versions, sessions, scoring provenance, and device-capable execution.
• Consent and participant rights: versioned consent, assent, re-consent, purpose authorization, withdrawal, and enforcement at service boundaries.
• Quality and analysis: missing-data review, queries, source data verification, audit reconstruction, export policy, snapshots, and manifests.
• Integrations: REDCap, notifications, device ingestion, public sites, and external analysis/API consumers.

Core data flow

1. A researcher authors or imports configuration as a draft.
2. Metricis validates the draft and records proposed changes.
3. An authorized person reviews and releases a version.
4. A study or registry pins that version to a schedule or participant workflow.
5. The participant or researcher completes work against the pinned version.
6. Service-layer rules enforce identity, context, consent purpose, and workflow state.
7. Responses retain actor, timestamps, version identifiers, and relevant provenance.
8. Quality review and governed exports operate on those records without rewriting their history.

Security and governance boundaries

• The browser and mobile clients are untrusted callers; authority is enforced by the API.
• Study and registry context is explicit and must not be inferred from a UI route alone.
• Consent checks are tied to an operation and purpose, not only to whether a consent screen was displayed.
• Released definitions and collected records are not silently mutated; corrections create auditable transitions.
• Integration credentials remain server-side and are configured per deployment.
• Export authorization, de-identification, and provenance are evaluated when the data product is created.

These controls support validated research operations, but deployment compliance still depends on sponsor validation, procedures, training, infrastructure, and intended use. See Trust and governance.

Repository map

metricis/
├── client/          # jsPsych assessment runtime and mobile shell
├── portal/          # researcher portal
├── patient-portal/  # participant and caregiver portal
├── server/          # API, models, services, and worker tasks
├── packages/        # shared form, offline, and UI packages
├── workers/         # edge-delivered public research surfaces
├── landing/         # metricis.app
└── docs/            # docs.metricis.app source

For component-level details, continue to the client, portal, participant portal, server, and database pages.