System Architecture
MindBridge MVP — Technical Documentation
1. System Overview
┌─────────────────────────────────────────────────────────────────┐
│ CLIENT (Browser) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Landing │ │ Survey │ │ Chat │ │ Doctors │ Settings │
│ │ Page │ │ PHQ/GAD │ │ UI │ │ Connect │ Page │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └─────────────┴────────────┴─────────────┘ │
│ │ React / Next.js │
│ │ TLS 1.3 Encrypted │
└──────────────────────────┼──────────────────────────────────────┘
│ REST API + WebSocket
┌──────────────────────────┼──────────────────────────────────────┐
│ API GATEWAY (nginx) │
│ Rate Limiting · CORS · Auth │
└──────────────────────────┼──────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────────────────┐
│ APPLICATION SERVER │
│ Node.js / FastAPI + Guardrails │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Assessment │ │ Chat Engine │ │ Escalation │ │
│ │ Service │ │ + LLM API │ │ Service │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ Booking │ │ Privacy │ │ Notification │ │
│ │ Service │ │ Service │ │ Service │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────┼──────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────────────────┐
│ DATA LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Object Store│ │
│ │ (Primary DB) │ │ (Sessions) │ │ (Exports) │ │
│ │ AES-256 Enc │ │ Ephemeral │ │ Encrypted │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
2. Database Schema
-- Users table
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
anonymous_id VARCHAR(64) UNIQUE NOT NULL,
email VARCHAR(255) ENCRYPTED, -- optional
created_at TIMESTAMPTZ DEFAULT NOW(),
last_active TIMESTAMPTZ,
preferences JSONB DEFAULT '{}',
data_consent BOOLEAN DEFAULT false,
is_deleted BOOLEAN DEFAULT false -- soft delete
);
-- Assessments
CREATE TABLE assessments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
type VARCHAR(20) NOT NULL, -- 'PHQ9' | 'GAD7'
answers JSONB NOT NULL ENCRYPTED,
total_score INTEGER NOT NULL,
risk_level VARCHAR(20) NOT NULL, -- minimal|mild|moderate|mod_severe|severe
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Chat Sessions
CREATE TABLE chat_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
started_at TIMESTAMPTZ DEFAULT NOW(),
ended_at TIMESTAMPTZ,
crisis_flagged BOOLEAN DEFAULT false,
summary TEXT ENCRYPTED
);
-- Messages
CREATE TABLE messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES chat_sessions(id) ON DELETE CASCADE,
role VARCHAR(10) NOT NULL, -- 'user' | 'assistant'
content TEXT NOT NULL ENCRYPTED,
created_at TIMESTAMPTZ DEFAULT NOW(),
flagged BOOLEAN DEFAULT false -- crisis keyword detected
);
-- Professionals
CREATE TABLE professionals (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
title VARCHAR(255),
specialties TEXT[],
rating DECIMAL(2,1),
review_count INTEGER DEFAULT 0,
available BOOLEAN DEFAULT true,
bio TEXT,
avatar_url VARCHAR(512)
);
-- Consultations
CREATE TABLE consultations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
professional_id UUID REFERENCES professionals(id),
preferred_date DATE,
preferred_time TIME,
reason VARCHAR(255),
consent_shared BOOLEAN DEFAULT false,
status VARCHAR(20) DEFAULT 'pending', -- pending|confirmed|completed|cancelled
assessment_snapshot JSONB ENCRYPTED,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Crisis Events (audit log)
CREATE TABLE crisis_events (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id) ON DELETE SET NULL,
session_id UUID REFERENCES chat_sessions(id),
trigger_content TEXT ENCRYPTED,
action_taken VARCHAR(50), -- 'banner_shown'|'chat_disabled'|'hotline_displayed'
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Indexes
CREATE INDEX idx_assessments_user ON assessments(user_id, created_at DESC);
CREATE INDEX idx_messages_session ON messages(session_id, created_at);
CREATE INDEX idx_consultations_user ON consultations(user_id, status);
CREATE INDEX idx_crisis_events_user ON crisis_events(user_id, created_at DESC);
3. API Design
| Method | Endpoint | Description |
| POST | /api/auth/anonymous | Create anonymous session |
| POST | /api/assessments | Submit assessment (PHQ-9 / GAD-7) |
| GET | /api/assessments/:id | Get assessment results |
| GET | /api/assessments/latest | Get user's most recent assessment |
| POST | /api/chat/sessions | Start new chat session |
| POST | /api/chat/sessions/:id/messages | Send message (returns AI response) |
| GET | /api/chat/sessions/:id/messages | Get session message history |
| POST | /api/crisis/report | Log crisis event |
| GET | /api/professionals | List available professionals |
| GET | /api/professionals/:id | Get professional detail |
| POST | /api/consultations | Request consultation booking |
| GET | /api/consultations | List user's consultations |
| GET | /api/user/data-export | Download all user data (GDPR) |
| DELETE | /api/user/data | Delete all user data (right to erasure) |
| PUT | /api/user/preferences | Update user preferences |
4. Tech Stack
Next.js 14
React 18
TypeScript
TailwindCSS
Node.js / Express
FastAPI (Python)
Prisma ORM
PostgreSQL 16
Redis
S3-compatible storage
OpenAI GPT-4 / Claude
Custom guardrails middleware
Docker + Kubernetes
GitHub Actions CI/CD
5. AI Safety Guardrails
AI Safety Middleware Pipeline:
1. INPUT FILTER
├─ Crisis keyword detection (regex + NLP classifier)
├─ PII detection and redaction
└─ Content length / rate limiting
2. SYSTEM PROMPT ENFORCEMENT
├─ "You are NOT a doctor or therapist"
├─ "Never diagnose conditions"
├─ "Never prescribe medication or treatment"
├─ "Always encourage professional help for serious concerns"
└─ "If crisis detected, respond with safety resources ONLY"
3. OUTPUT FILTER
├─ Scan for accidental diagnostic language
├─ Ensure disclaimer presence in first message
├─ Block medical advice patterns
└─ Inject crisis resources when flagged
4. ESCALATION TRIGGER
├─ Keywords: suicide, self-harm, end my life, kill myself, etc.
├─ Action: Log crisis_event → Show banner → Disable AI chat
└─ Notify on-call staff (if available)
6. MVP Implementation Plan
Phase 1 — Foundation (Weeks 1-2)
- Project scaffolding: Next.js + FastAPI + PostgreSQL + Docker Compose
- Database schema migration with Prisma / Alembic
- Anonymous authentication flow
- PHQ-9 and GAD-7 assessment forms with scoring engine
- Basic UI shell with navigation and responsive layout
Phase 2 — AI Chat (Weeks 3-4)
- LLM integration with system prompt guardrails
- Chat session management (create, store, retrieve)
- Crisis keyword detection pipeline
- Crisis mode UI (banner, chat disable, hotline display)
- Pre-built coping tools: breathing exercise, grounding technique
Phase 3 — Professional Connect (Weeks 5-6)
- Professional directory with search and filtering
- Consultation request flow with consent-based data sharing
- Assessment summary generation for professionals
- Email notification system for booking confirmations
Phase 4 — Privacy & Launch (Weeks 7-8)
- GDPR data export and deletion endpoints
- AES-256 encryption for sensitive database fields
- Security audit and penetration testing
- Accessibility audit (WCAG 2.1 AA)
- Load testing and performance optimization
- Deployment to production (AWS / GCP with Kubernetes)