📋 Governance Milestones & Dependency Evolution (Aug → Nov 2026)
Track A Verified · Track B PendingThe NEPS Digital platform operates under a strict clinical requirements-first governance model. Following early technical blockers in August, the project received the official NDS_Team Handover Baseline V3.1 package from the NEPS Board in October, followed by the REDCap Data Dictionary Version 3.2 in November. Here is the operational reality of what has been delivered versus what is pending external clinical sign-off:
✅ Unblocked & Implemented (Track A Scope)
- Master CRF V3.1 Handover Delivered: Board provided the official 223-row CRF dictionary, 73 core clinical items, and verified scoring contracts (K6, BRS, MSPSS, GSE, EPI, ESI, SBI, PFI, NSES).
-
REDCap Data Dictionary V3.2 Integrated: Bernard Arhin (KATH) issued V3.2 expanding to 227 fields; automated DOB-to-age calculation, explicit consent gating (
survey_consent), and age-eligibility validation (12–24 years) are live across all tiers. -
Unified User Stories Published:
USER_STORIES_V31.mddelivered with explicit qualitative acceptance criteria, role matrix, and integration boundaries. -
Hardened JWT Authentication & RBAC: Dedicated
/api/auth/loginendpoint deployed with country-level scoping (Ghana, Sierra Leone, Tanzania) and role enforcement across portal dashboards. -
PITR Runbook Formally Documented: Automated WAL archiving and complete recovery procedures verified in
neps-infrastructure/docs/pitr-runbook.md.
⏳ Active Blockers (Track B & External Governance)
-
Track B Longitudinal CRFs Pending: Clinical team (Prof. Brew / KATH) has not yet finalized Case Report Forms for 24-month monthly self-reports (M1–M24, 14 parameters) and wave reviews (M06, M12, M18, M24). These remain classified as
UNVERIFIED. -
Live REDCap Production Credentials: KATH/KCHR (
https://kchr.org) API token issuance is deferred by the field committee until field participant recruitment begins. Development proceeds against the V3.2 mock server. -
Clinical Safeguarding Escalation Protocols: Exact referral pathways, emergency contacts, and clinician assignment workflows for severe distress (
K6 ≥ 13) and suicidality require final ethics committee sign-off. - Production TLS Certificate: On-premises host deployment at KNUST IT awaits institutional SSL certificate procurement.
Context About the NEPS Study
Clinical Scope & Target Population
NEPS (Navigating Educational Pressures and Stressors) is a clinical-grade digital mental health surveillance platform designed to evaluate and strengthen psychological resilience among adolescents and youth aged 12–24 years across West and East Africa over a 24-month longitudinal cohort study.
Under the Master CRF V3.1/V3.2 standard, the platform computes 9 authoritative psychometric indices to stratify risk and resilience:
The platform combines REDCap survey capture with a high-throughput ETL scoring warehouse, a secure FastAPI backend, machine learning risk engines, and role-scoped Next.js clinical dashboards.
Multi-Site Study Deployment
-
🇬🇭
Ghana (Primary Host & Lead Site)KNUST, CAIH · Kumasi & Accra study sites (60 target cohort)
-
🇸🇱
Sierra LeoneFreetown urban & peri-urban study sites (45 target cohort)
-
🇹🇿
TanzaniaDar es Salaam study sites (45 target cohort)
Architecture System Overview & Data Pipeline
End-to-End Clinical Data Pipeline
Consent & DOB Gated
PostgreSQL Warehouse
Country-Scoped Routing
NLP Clinical Triage
Admin, PI, Leads, Enums
Interventions (WP6)
All services run inside segmented Docker networks on-premises at KNUST. Prometheus, Grafana, and Loki provide full-stack telemetry. Alertmanager dispatches safeguarding notifications to Discord. Automated WAL archiving ensures point-in-time recovery (PITR).
Repositories Per-Repo Status Breakdown
DevOps and orchestration engine. Manages the 17-container Docker Compose stack, network isolation, credential vaulting, telemetry, continuous integration, and disaster recovery.
- ✅ 17 container services running in Docker Compose with 4-tier network isolation
- ✅ Docker Secrets for all credentials — zero plain-text passwords or tokens
- ✅ WAL archiving and nightly PITR backup script via Ofelia cron (02:00)
- ✅ Formal PITR operational runbook published (
docs/pitr-runbook.md) - ✅ Active CI/CD pipelines across all repositories (main & staging)
- ✅ Prometheus, Grafana dashboards, and Loki log pipelines operational
- ✅ Discord Alertmanager webhook active and routing safeguarding alerts
- ⚠️ Production TLS certificate pending institutional IT procurement from KNUST
FastAPI clinical REST service. Implements fail-closed JWT authentication, country data scoping, official V3.1/V3.2 baseline endpoints, scoring queries, and REDCap synchronization.
- ✅ Hardened JWT authentication (
POST /api/auth/login) with role-based and country scoping - ✅ Live V3.1/V3.2 baseline endpoints (
/api/v31/baseline,/participants,/stats,/export) - ✅ Dynamic dictionary API (
/api/v31/dictionary) serving 227 V3.2 fields with V3.1 fallback - ✅ Distress trend and trajectory endpoints (
/api/portal/distress/trends) - ✅ 119/119 unit and integration tests passing in CI (100% green)
- ✅
POST /api/v31/baselinereturns HTTP 501 by design until direct REDCap enumerator sync (Track B) is finalized - ○ Track B monthly self-report endpoints (M1–M24) pending clinical CRF handover
ETL data platform and clinical scoring warehouse. Ingests raw REDCap survey records, validates schemas, executes psychometric scoring algorithms, and persists verified data in PostgreSQL.
- ✅ Additive Alembic migration chain through
004_storage_integrity - ✅ Core 73 clinical psychometric scoring engine with 100% mathematical parity against
SCORING_GOLDEN.json - ✅
ingest-v31CLI ingests and scores all 150 baseline records into PostgreSQL (nds_v31_source,nds_v31_derived) - ✅ JSON payload warehouse schema seamlessly accommodates V3.2 consent and DOB fields
- ✅ Orchestration CLI with
--full,--metadata-only, and--dry-runmodes - ✅ Distress trends analytics and quality metrics validation modules
- ○ Track B 24-month longitudinal table migrations pending monthly CRF release
Next.js 16 / React 19 clinical portal. Delivers role-based dashboards, country data filtering, longitudinal trend visualizations, OpenAPI mock backend, and clinical intake forms.
- ✅ V3.1/V3.2 consumption layer merged (PR #92, #104/#105) with fail-closed security
- ✅ Built-in mock API server (
npm run mock) with OpenAPI 3.1 schema (openapi.json) simulating 150 participants - ✅ Role-based and country-scoped dashboards for Admin, PI, Country Lead, and Enumerator
- ✅ Baseline entry form (
US-FE-BL-001) updated for V3.2 (explicit consent, DOB age calculation, 12–24 alert) - ✅ Dynamic participant directory with country filtering (Ghana, Sierra Leone, Tanzania)
- ✅ Prometheus
/api/metricsinstrumentation and Next.js dark/light theme toggle - ⚠️ 14-parameter monthly monitoring cards prototype wired to trend API; pending Track B CRFs
Predictive analytics and clinical NLP engine. Houses machine learning pipelines for adolescent distress risk detection, sentiment evaluation, and clinical text classification.
- ✅ PostgreSQL warehouse reader (
app/data/v31_repository.py) reading directly from live database tables - ✅ Published verified offline 240-column baseline dataset (
v31_baseline_dataset.csv) matching V3.2 - ✅ Multimodal NLP clinical dataset with 2,000 records across 6 narrative modalities and 21 emotion labels
- ✅ Serialized emotion classification and sentiment models in
models/ - ✅ Fast-API microservice container with health check and Prometheus metrics
- ⚠️ Baseline scoring models currently train on verified V3.1 snapshot; live inference routing in review
- ○ Longitudinal trajectory risk forecaster dormant awaiting Track B monthly data
Technical governance, deployment runbooks, and clinical operations documentation hub. Establishes data ethics, disaster recovery runbooks, and schema audit logs.
- ✅ Comprehensive operational runbooks (
08-operational-runbook.md) - ✅ Data Ethics and Management Plan (
07-ethics-data-management-plan.md) - ✅ Pipeline testing and verification guide (
pipeline-testing-guide.md) - ✅ Formally signed-off Confidentiality and Trade Secret Register
- ✅ PostgreSQL database architecture review and dependency audit documents
- ⚠️ Multi-country deployment VPN guide to be finalized upon physical hardware install
External Utility Sandboxed REDCap API Service
mock-redcap-service Live on Render · V3.2 Standard
A high-fidelity standalone mock REDCap service hosted on Render that replicates exact REDCap API endpoints, authentication headers, and multi-country response payloads. Updated to the Version 3.2 data dictionary, it generates realistic synthetic participant profiles with automated DOB-to-age calculation, explicit consent gating, and stamps survey completion dates.
Exposes the full 150 participant baseline dataset across Ghana, Sierra Leone, and Tanzania, the 227-field data dictionary API, and the 2,000-record multimodal NLP dataset. All services point to this instance for end-to-end integration testing, providing a zero-friction drop-in replacement when the live KCHR REDCap production server (https://kchr.org) is connected.
Summary Current Operational State vs. Pending Work
What is Fully Operational
- Full 17-container infrastructure stack with Docker network segmentation and secrets vaulting
- Automated PostgreSQL WAL archiving and verified PITR disaster recovery runbook (
docs/pitr-runbook.md) - Master CRF V3.1 Handover fully implemented with 100% mathematical scoring parity against Golden Fixtures
- REDCap Data Dictionary V3.2 integrated across all layers (227 fields, consent gating, DOB age calculation)
- Backend JWT authentication with role-based access control and country-level scoping (Ghana, Sierra Leone, Tanzania)
- Data platform ETL pipeline (
ingest-v31) scoring all 150 participants into PostgreSQL tables - Portal Next.js web client with authenticated role dashboards, OpenAPI mock backend, and 150 simulated records
- ML/AI service connected directly to PostgreSQL data warehouse with published 240-feature offline dataset
- Automated CI/CD workflows across main and staging branches across all repositories with 100% passing tests
- Discord Alertmanager integration actively monitoring infrastructure health and safeguarding queues
What is Pending / Awaiting External Approval
- Track B Longitudinal CRFs: Clinical team (Prof. Brew / KATH) has not yet released the 24-month monthly self-report CRFs (14 parameters) and wave schedules; forms remain UNVERIFIED
- Live REDCap API Credentials: Issuance of production KCHR API tokens awaits final field deployment readiness and ethical clearance
- Safeguarding Escalation Triage: Formal approval of clinical referral thresholds (
K6 ≥ 13, severe distress, suicidality) needed before automated alert dispatch is authorized - Manual Entry Live Submission:
POST /api/v31/baselinereturns HTTP 501 by design until enumerator REDCap submission integration is finalized - Production TLS Certificate: Institutional procurement from KNUST IT for the physical server environment remains pending
- Multi-Country VPN Setup: Physical site-to-site VPN connection between KNUST host and Sierra Leone/Tanzania field offices to be established upon field launch
Roadmap Technical Milestones & Phasing
| Phase | Milestone / Task | Priority | Owner |
|---|---|---|---|
| Phase 1 — Track A (Baseline) | Implement Master CRF V3.1 (223 vars) and V3.2 (227 vars) across all 6 core repositories | ✅ Delivered | All Teams |
| Phase 1 — Track A (Baseline) | Deliver PostgreSQL ingestion pipeline and verify golden scoring parity across 150 baseline records | ✅ Delivered | Data Platform |
| Phase 1 — Track A (Baseline) | Harden JWT authentication, RBAC role dashboards, and country-level data scoping | ✅ Delivered | Backend + Portal |
| Phase 1 — Track A (Baseline) | Connect ML/AI feature extraction directly to PostgreSQL data warehouse | ✅ Delivered | ML/AI Team |
| Phase 2 — Track B (Longitudinal) | Receive and review official REDCap Monthly Follow-up CRFs (M1–M24, 14 parameters) from clinical team | 🔴 Critical (Blocked) | Clinical / PI Team |
| Phase 2 — Track B (Longitudinal) | Migrate database schema for monthly reports and comprehensive waves (M06, M12, M18, M24) | 🟠 High (Pending CRF) | Data Platform |
| Phase 2 — Safeguarding | Formalize clinical safeguarding referral triage rules and automated clinician alert dispatch | 🟠 High | Clinical + Backend |
| Phase 3 — Production Rollout | Obtain and install official institutional TLS certificate from KNUST IT | 🔵 Medium | Damien (DevOps) |
| Phase 3 — Production Rollout | Switch data platform ingestion from Render mock server to live KCHR REDCap production API | 🟠 High | DevOps + Backend |
| Phase 3 — Production Rollout | Establish multi-country secure VPN connectivity between KNUST, Sierra Leone, and Tanzania field hubs | 🔵 Medium | DevOps + IT |
Table Repository Summary & Ownership
| Repository | Core Architecture & Purpose | Lead | Last Activity | Status |
|---|---|---|---|---|
| neps-infrastructure | Docker Compose (17 services), CI/CD, PITR backup automation, network security | Damien | Nov 2026 | Live / Active Ops |
| neps-backend | FastAPI REST API, JWT auth, RBAC, V3.1/V3.2 baseline endpoints, scoring queries | Samuel | Nov 2026 | Live (Baseline) / Active Dev |
| neps-data-platform | ETL scoring warehouse, Alembic 004 integrity, PostgreSQL ingestion (150 cohort) | Frank / Isaac | Nov 2026 | Live |
| neps-portal | Next.js 16 client, authenticated role dashboards, mock API server, V3.2 intake form | Eric / Ama / Ghazi | Nov 2026 | Active Dev |
| neps-ml-ai | Direct PostgreSQL warehouse reader, 240-feature tabular models, 2,000-record NLP dataset | Yasmine | Nov 2026 | Active Dev |
| neps-docs | Operational runbooks, data ethics policies, pipeline testing guides, audit registers | Salamatu | Nov 2026 | Active Dev |
| mock-redcap-service | Hosted simulated REDCap API sandbox on Render, V3.2 generator, 150 participants | All Teams | Nov 2026 | Live on Render |