Skip to content

Architecture Overview

Metricis is built as a modern, cloud-native platform with a monorepo structure containing four main applications.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Frontend Layer                        │
├──────────────┬──────────────────┬─────────────────────────────┤
│    Client    │      Portal      │     Patient Portal         │
│  (jsPsych)   │  (Researcher)    │  (Participant/Caregiver)   │
│   Port 5173  │    Port 3000     │       Port 3001            │
└──────────────┴──────────────────┴─────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                       Backend Layer                          │
├─────────────────────────────────────────────────────────────┤
│               FastAPI Server (Port 8000)                     │
│  ┌────────────┬──────────────┬────────────┬──────────────┐ │
│  │   Auth     │   Studies    │  Forms     │   Sessions   │ │
│  │  Routers   │   Routers    │  Routers   │   Routers    │ │
│  └────────────┴──────────────┴────────────┴──────────────┘ │
│  ┌────────────┬──────────────┬────────────┬──────────────┐ │
│  │ Validation │    Query     │    SDV     │   Workflow   │ │
│  │  Service   │   Service    │  Service   │   Service    │ │
│  └────────────┴──────────────┴────────────┴──────────────┘ │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                     Persistence Layer                        │
├──────────────┬─────────────┬───────────────┬──────────────┤
│  PostgreSQL  │    Redis    │    Celery     │   File Store │
│  (Database)  │  (Cache)    │  (Workers)    │   (Local)    │
└──────────────┴─────────────┴───────────────┴──────────────┘

Component Overview

Client (jsPsych Assessment Frontend)

  • Technology: jsPsych 8.x, TypeScript, Vite, Capacitor
  • Purpose: Run cognitive assessments (Tier 1 screening + Tier 2 deep phenotyping)
  • Features:
  • Offline-first with Dexie.js
  • Mobile deployment via Capacitor (iOS/Android)
  • Task orchestration and adaptive testing (CAT)
  • i18n support (English/French)

Portal (Researcher Interface)

  • Technology: React 18, React Query, Tailwind CSS, Recharts
  • Purpose: Study management, participant tracking, data review
  • Features:
  • Study configuration and templates
  • Participant enrollment and management
  • Data entry grid with quality badges
  • Validation rules and query management
  • REDCap integration
  • Export (CSV, Excel, ODM XML)
  • Reports and analytics

Patient Portal (Participant Interface)

  • Technology: React 18, Capacitor, i18next, Tailwind CSS
  • Purpose: Mobile-first participant access to assessments
  • Features:
  • Magic link authentication
  • eConsent signing
  • Assessment completion
  • Schedule viewing
  • Offline support
  • Push notifications

Server (FastAPI Backend)

  • Technology: FastAPI, Python 3.11+, SQLAlchemy 2.x, Alembic
  • Purpose: REST API, business logic, data persistence
  • Features:
  • Async/await for high performance
  • JWT authentication
  • Rate limiting
  • Structured logging with correlation IDs
  • Validation and query services
  • REDCap sync
  • PDF report generation
  • Webhook support

Database (PostgreSQL)

  • Technology: PostgreSQL 15+, Alembic migrations
  • Purpose: Persistent data storage
  • Schema: Multi-tenant with study isolation
  • Key Tables:
  • Studies, Participants, Users
  • Forms, FormResponses, FormVersions
  • Batteries, Modules, ItemBanks
  • Queries, ValidationResults, SourceVerifications
  • ScheduledVisits, Sessions

Background Workers (Celery)

  • Technology: Celery, Redis
  • Purpose: Asynchronous task processing
  • Tasks:
  • Visit reminder notifications
  • REDCap sync jobs
  • Report generation
  • Bulk imports

Data Flow

Assessment Completion Flow

  1. Session Start: Client calls /api/session/start → receives session ID
  2. Task Execution: jsPsych runs tasks, collecting trial data locally
  3. Data Submission: On completion, client submits via /api/submit with task summaries + raw trials
  4. Server Processing:
  5. Store data in PostgreSQL
  6. Run validation (SurveyJS schema + custom rules)
  7. Update quality flags
  8. Sync to REDCap if configured
  9. Quality Review:
  10. Researchers review validation findings
  11. Create and resolve queries
  12. Perform source data verification (SDV)
  13. Sign and lock forms

Form Workflow Progression

Not Started → In Progress → Complete → Signed → Locked
                                ↓         ↓       ↓
                          Quality Flags Applied:
                          • Errors, Warnings
                          • Queries, Review, SDV

Integration Points

REDCap Integration

  • Bidirectional Sync: Participants, form data, events
  • Webhook Support: Real-time updates from REDCap
  • Event Mapping: REDCap events ↔ Metricis batteries
  • Field Mapping: REDCap instruments ↔ Metricis forms

Mobile Deployment

  • Capacitor: Native iOS/Android apps
  • Offline Storage: Dexie.js (IndexedDB)
  • Push Notifications: Firebase Cloud Messaging (FCM)
  • Background Sync: Service Workers

Authentication

  • Portal: JWT with refresh tokens
  • Patient Portal: Magic link (passwordless)
  • Session Management: Redis-backed or in-memory
  • Multi-device: Session tracking per device

Security Architecture

Authentication & Authorization

  • JWT Tokens: Access (short-lived) + Refresh (long-lived)
  • Password Hashing: bcrypt
  • Rate Limiting: slowapi (per endpoint)
  • CORS: Configurable origins

Data Protection

  • Encryption at Rest: PostgreSQL encryption
  • Encryption in Transit: HTTPS/TLS
  • API Keys: Environment variables
  • Session Security: HttpOnly cookies, CSRF protection

Audit Trail

  • Structured Logging: JSON logs with correlation IDs
  • User Actions: Tracked in database
  • Data Changes: Timestamp + user tracking
  • Query History: Full comment threads

Scalability Considerations

Horizontal Scaling

  • Stateless API: Scale FastAPI instances
  • Session Storage: Redis for shared state
  • Background Workers: Scale Celery workers
  • Database: PostgreSQL read replicas

Performance Optimization

  • Caching: Redis for session and query results
  • Database Indexing: Strategic indexes on key fields
  • Async I/O: FastAPI async/await
  • Connection Pooling: SQLAlchemy async pool

Monitoring & Observability

  • Structured Logging: JSON logs with correlation IDs
  • Health Checks: /api/health endpoint
  • Metrics: Response times, error rates
  • Alerts: (To be configured)

Deployment Architecture

Development

  • Local development with hot reload
  • Docker Compose for local stack
  • Separate ports for each service
  • Frontend: Static hosting (Vercel, Netlify, Cloudflare Pages)
  • Backend: Container deployment (AWS ECS, Google Cloud Run, Fly.io)
  • Database: Managed PostgreSQL (AWS RDS, Google Cloud SQL)
  • Cache: Managed Redis (AWS ElastiCache, Upstash)
  • CDN: CloudFront or Cloudflare for static assets

Technology Decisions

Why FastAPI?

  • Modern async Python framework
  • Automatic OpenAPI docs
  • Type safety with Pydantic
  • High performance (on par with Node.js)

Why React Query?

  • Declarative data fetching
  • Automatic caching and background updates
  • Optimistic updates
  • Built-in loading and error states

Why PostgreSQL?

  • ACID compliance for clinical data
  • JSONB for flexible schema
  • Full-text search
  • Mature ecosystem

Why Capacitor?

  • Cross-platform (iOS/Android/Web)
  • Native plugin access
  • Web-first development
  • Active community

Next Steps