Current Dependencies & Governance Blockers
The project is following a requirements-first methodology to prevent costly rework. Several features are intentionally paused pending clinical and administrative approvals. These are not delays — they are evidence of disciplined governance.
- Case Report Forms (CRFs) pending finalisation by Prof. Obed Brew before REDCap API credentials are issued by KCIRD
- User stories and wireframes documentation pending release by the project coordinators before frontend development proceeds
- Live REDCap data unavailable until participant recruitment begins; synthetic data environment in active use
- Production TLS certificate pending institutional procurement from KNUST IT
Context About the NEPS Study
What is NEPS Digital?
NEPS (Navigating Educational Pressures and Stressors) is a clinical-grade digital health surveillance platform monitoring the mental health and psychological resilience of youth aged 10–24 across three African countries over a 24-month longitudinal study.
The platform integrates REDCap for structured psychosocial data collection, an AI/ML distress engine for real-time risk scoring (PHQ-9, GAD-7, suicidality screening), and role-based clinical dashboards for Investigators, Country Leads, Enumerators, and System Administrators.
Infrastructure is planned to be hosted on-premises at KNUST/CAIH, Ghana, with VPN-secured access for field teams in Sierra Leone and Tanzania once the system is production-ready. Currently, this multi-country deployment is not yet in place.
Planned Production Deployment
-
🇬🇭
Ghana (Primary Host - Planned)KNUST, CAIH · VPN-secured server host
-
🇸🇱
Sierra Leone (Planned)VPN-connected field teams
-
🇹🇿
Tanzania (Planned)VPN-connected field teams
Architecture System Overview
Data & Service Flow
source of truth
PostgreSQL sync
Business logic
NLP sentiment
Role dashboards
Enumerators
All services run inside Docker Compose on-premises at KNUST. Prometheus + Grafana provide observability. Alertmanager dispatches safeguarding crisis notifications. Ofelia schedules nightly backups and REDCap ETL sync.
Repositories Per-Repo Status Breakdown
DevOps orchestration hub. Manages the full Docker Compose stack, network segmentation, secrets management, monitoring telemetry, nightly backups, and CI/CD pipelines.
- ✅ Full Docker Compose stack (17 services — Nginx, Prometheus, Grafana, Loki, Alertmanager, MinIO, Ofelia)
- ✅ 4-tier network segmentation (public / internal / database / monitoring)
- ✅ Docker Secrets for all credentials — no plain-text env vars
- ✅ WAL archiving + PITR scripts (Ofelia cron nightly at 02:00)
- ✅ CI/CD pipeline across all 6 repos
- ✅ Grafana auto-provisioned dashboards + Loki log aggregation
- ⚠️ Production TLS certificate pending (self-signed for dev only)
- ✅ Discord Alertmanager webhook configured and active, receiving alerts
- ○ PITR restore drill not yet formally documented
FastAPI-based REST API. Serves the portal and data platform. Handles REDCap data proxy, participant records, distress screenings, referrals, and WP6 interventions.
- ✅ FastAPI app with full router structure (portal, redcap, sync, analytics, health)
- ✅ SQLAlchemy ORM models: Participant, ConsentRecord, SurveyResponse, DistressScreening, WP6Session, Referral, LongitudinalRecord
- ✅ Alembic migrations (initial schema + foreign key constraints)
- ✅ REDCap mock client (REDCAP_MOCK_ENABLED toggle)
- ✅ APScheduler for hourly REDCap sync jobs
- ✅ Prometheus instrumentation (/metrics) + health check (/health)
- ⚠️ JWT helper scaffolding exists in security.py (token creation + decode functions); no /api/auth/login endpoint; no User model; zero routes protected with auth guards
- ○ Safeguarding escalation endpoint (internal routing) not yet built
- ○ Risk model router file exists but is empty (risk_models.py is 0 bytes)
ETL warehouse pipeline. Extracts from REDCap (live or mock), transforms raw survey records, and upserts into PostgreSQL. Supports multi-instrument sync with schema migrations.
- ✅ Full ETL pipeline: extract → transform → load with CLI entrypoint
- ✅ Upsert logic (ON CONFLICT) for idempotent REDCap data loads
- ✅ Alembic database migrations (001_initial schema)
- ✅ Sync orchestrator with --full, --metadata-only, --dry-run flags
- ✅ Ofelia cron nightly sync (01:00 daily)
- ✅ Distress trends analytics module (distress_trends.py)
- ⚠️ Error notification on sync failure not yet wired
- ○ Integration test suite needs expansion
Next.js 16 / React 19 clinical web portal. Role-based dashboards, live API data fetching, chart visualisations, authentication, and Prometheus metrics.
- ✅ Landing page with animated typewriter + dark/light theme toggle
- ✅ NextAuth v5 with role-based routing middleware
- ✅ Admin dashboard with 3 components live-bound to backend API (StatCard stats, StressScoreTrend, AlertCard alerts) with graceful fallback to dummy data
- ⚠️ 6 remaining admin dashboard components (ParticipantTrendChart, DataCollectionStatus, WorkPackageOverview, UpcomingSchedule, RecentActivity, Demographics) still use hardcoded/static values
- ✅ Full set of dashboard card components built and styled
- ✅ Prometheus /api/metrics endpoint
- ✅ Fully typed API client against backend response models
- ⚠️ PI, Country Lead, Enumerator dashboards scaffolded — "coming soon" stubs
- ○ Participants module route not yet built
- ○ Safeguarding alert detail page not yet built
- ○ 2FA enforcement not yet configured in NextAuth
AI/ML analytics engine. Trained NLP classification models for emotion detection and sentiment scoring. REST API for predictions is in progress.
- ✅ FastAPI app with /health + /metrics endpoints
- ✅ Emotion detection model trained (TF-IDF + Logistic Regression, 6 classes)
- ✅ Sentiment classification pipeline trained and serialised (PKL)
- ✅ NLP preprocessing module for text cleaning and vectorisation
- ✅ PKL model/vectorizer/pipeline artefacts stored in models/
- ⚠️ Models not yet loaded into API — endpoints return placeholder only
- ○ PHQ-9 / GAD-7 structured risk scoring not yet built
- ○ Prediction endpoints not yet wired to backend risk_models router
Technical documentation and deployment guides covering data security, multi-country hosting, clinical data flows, dashboard UX, AI risk detection, REDCap forms, and backup procedures.
- ✅ Documentation plan and structure in place (7 document areas defined)
- ✅ Source teams and information requirements mapped per document
- ⚠️ Actual document drafts not yet written (plan only)
- ○ Data Security policy document pending
- ○ Three-Country Hosting architecture guide pending
- ○ REDCap integration and form management guide pending
- ○ Backup & Disaster Recovery runbook pending
- ○ AI/ML risk detection explanation for clinicians pending
External Development Utilities
mock-redcap-service Live on Render
A standalone hosted mock REDCap API mirroring exact REDCap POST endpoint payload formats. Serves realistic longitudinal youth mental health data across all three study countries. All teams (backend, data-platform, portal) point to this service for development and integration testing while the live REDCap instance is being provisioned.
Includes a 2,000-record mock NLP dataset validated against the NEPS instrument schema. Exposes REDCap-style record export, metadata, and event-arm endpoints. Drop-in replaceable by switching a single REDCAP_API_URL environment variable.
Summary What's Working vs. What's Pending
What is Operational
- Full infrastructure stack running in Docker (17 containers)
- PostgreSQL with WAL archiving and nightly PITR base backups via Ofelia cron (02:00)
- Prometheus scraping all 4 application services
- Grafana dashboard auto-provisioned with live metric graphs (1 overview dashboard)
- Loki + Promtail collecting logs from all containers
- REDCap mock API live on Render — all teams using it for dev
- Data platform ETL nightly sync configured via Ofelia docker-exec (01:00 daily, full refresh); container sleeps after migrate, sync triggered externally
- Backend Alembic DB schema deployed and queryable
- Admin dashboard: 3 components (StatCard stats, StressScoreTrend, AlertCard) fetching live backend data with fallback; 6+ components still hardcoded
- CI/CD across all 6 repos: automated test → build → image push (deploy job activates once DEPLOY_HOST GitHub var is set)
- Alertmanager configured with real Discord webhook alongside webhook-logger test sink; safeguarding alerts deliver to Discord channel
Critical Pending Items
- Backend: no /api/auth/login endpoint, no User DB model, zero routes protected with JWT auth guards (helpers scaffolded only; entire API publicly accessible)
- ML/AI models not yet exposed through API endpoints (only / and /health exist; trained PKL models not loaded)
- Safeguarding escalation route and case management workflow not yet implemented (no acknowledge/assign/resolve endpoints or UI)
- PI, Country Lead, and Enumerator dashboards are "coming soon" stubs (Admin dashboard partially live-bound)
- Production TLS certificate pending institutional procurement (self-signed certs exist for local dev)
- Data-platform: incremental sync feature branch not yet merged (current nightly is full refresh only; relies on external Ofelia docker-exec)
- PITR restore drill not formally documented or tested end-to-end
- 2FA enforcement in NextAuth not yet configured
- Actual documentation drafts not yet written (neps-docs: plan + confidentiality register only)
Roadmap Next Priorities
| Phase | Task | Priority | Owner |
|---|---|---|---|
| Phase 1 — Integration | Load ML/AI trained models into FastAPI endpoints and wire to backend risk_models router | 🔴 Critical | ML/AI Team |
| Phase 1 — Integration | Build safeguarding escalation endpoint in backend API | 🔴 Critical | Samuel |
| Phase 1 — Integration | Build PI, Country Lead, and Enumerator role dashboards in the portal | 🟠 High | Portal Team |
| Phase 2 — Safeguarding | Build /dashboard/safeguarding page with live high-distress alert queue | 🟠 High | Portal Team |
| Phase 2 — Safeguarding | End-to-end safeguarding drill: mock distress submission → verify alert fires | 🟠 High | All Teams |
| Phase 3 — Rollout | Install production TLS certificate on KNUST server | 🔵 Medium | Damien |
| Phase 3 — Rollout | Configure 2FA in NextAuth and RBAC audit across all 4 roles | 🔵 Medium | Portal + Backend |
| Phase 3 — Rollout | Conduct formal PITR restore drill and document RTO/RPO achieved | 🔵 Medium | Damien |
| Phase 3 — Rollout | Write all 7 neps-docs documents (security, hosting, flows, AI, forms, backups) | 🔵 Medium | Salamatu |
Table Repository Summary
| Repository | Purpose | Lead | Last Activity | Status |
|---|---|---|---|---|
| neps-infrastructure | Docker Compose, CI/CD, monitoring, PITR backups | Damien | Aug 2026 | Active Dev |
| neps-backend | FastAPI REST API, DB models, REDCap proxy, sync | Samuel | Aug 2026 | Active Dev |
| neps-data-platform | ETL pipelines, warehouse loaders, REDCap sync | Frank / Isaac | Aug 2026 | Active Dev |
| neps-portal | Next.js web client, role dashboards, auth | Eric / Ama / Ghazi | Aug 2026 | Partial Dev |
| neps-ml-ai | ML distress models, NLP emotion/sentiment API | Yasmine | Aug 2026 | Partial Dev |
| neps-docs | Technical documentation, deployment runbooks | Salamatu | Jul 2026 | Drafting |
| mock-redcap-service | Hosted REDCap API sandbox (external dev utility) | All Teams | Aug 2026 | Live |