NEPSDigitalSystem  ·  Public Report

NEPS Digital System

Public status and technical progress report for the Navigating Educational Pressures and Stressors (NEPS) digital platform — an adolescent and youth mental health research initiative.

Multi-Site Research (GH · SL · TZ) Track A Baseline Delivered REDCap Master CRF V3.2 (227 Fields) Track B Longitudinal in Design
Organisation: NEPSDigitalSystem  ·  Public Read-Only Status Report Report date: November 2026 · Post-Handover Baseline V3.1 & REDCap V3.2 Integration
6 Core Repositories (+1 Mock Utility)
3 Study Countries (GH · SL · TZ)
227 CRF Variables (73 Core Clinical)
150 Scored Cohort (Golden Parity)
Track A Status: Baseline Live · Track B Blocked
🔒 Privacy & Security Note: Core repository source code, database migration schemas, participant clinical entries, and infrastructure secrets are maintained inside a private GitHub organisation in accordance with GDPR and national data protection regulations across Ghana, Sierra Leone, and Tanzania. This page provides a transparent, read-only status mirror for institutional partners, funders, and research ethics committees.

📋 Governance Milestones & Dependency Evolution (Aug → Nov 2026)

Track A Verified · Track B Pending

The 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.md delivered with explicit qualitative acceptance criteria, role matrix, and integration boundaries.
  • Hardened JWT Authentication & RBAC: Dedicated /api/auth/login endpoint 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.

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:

K6 / MHDI (Mental Health Distress) BRS (Brief Resilience) MSPSS (Social Support) GSE (Self-Efficacy) EPI (Educational Pressure) ESI (Economic Stress) SBI (Stigma Burden) PFI (Protective Factors) NSES Composite Score

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)
*Note: Target baseline verification cohort is 150 participants across all 3 countries, successfully modeled and scored in PostgreSQL.

System Overview & Data Pipeline

End-to-End Clinical Data Pipeline

📋 REDCap / Mock CRF V3.2 (227 vars)
Consent & DOB Gated
→
🔄 Data Platform ETL Ingest & Scoring
PostgreSQL Warehouse
→
⚙️ Backend API FastAPI · JWT RBAC
Country-Scoped Routing
→
🤖 ML / AI Engine 240-Feature Models
NLP Clinical Triage
→
🖥️ Portal Dashboards Next.js 16 · NextAuth
Admin, PI, Leads, Enums
→
👥 Clinical Researchers Triage · Analytics
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).

Per-Repo Status Breakdown

neps-infrastructure Live / Active Ops

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
neps-backend Live (Baseline) / Active Dev

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/baseline returns 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
neps-data-platform Live

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-v31 CLI 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-run modes
  • ✅ Distress trends analytics and quality metrics validation modules
  • ○ Track B 24-month longitudinal table migrations pending monthly CRF release
neps-portal Active Dev

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/metrics instrumentation and Next.js dark/light theme toggle
  • ⚠️ 14-parameter monthly monitoring cards prototype wired to trend API; pending Track B CRFs
neps-ml-ai Active Dev

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
neps-docs Active Dev

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

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.

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/baseline returns 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

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

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