🛡️ ConvoGuard AI

January 6, 2026 · View on GitHub

🛑 ARCHITECTURAL ANCHOR

This project is part of the Berlin AI Automation Studio. It is governed by the global rules in berlin-ai-infra.

Setup for new laptops:

Clone this repo.
Run ./bootstrap-infra.sh to link to the global Master Brain.

Real-time API middleware that validates mental health chatbot conversations for EU AI Act/DiGA/GDPR compliance.

Built for CIC Berlin / Soonami Accelerator demo.

🚀 Quick Start

npm install
npm run dev

Open http://localhost:3000 - Landing page with API demo Open http://localhost:3000/dashboard - Compliance dashboard

📡 API Usage

Validate a Conversation

curl -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{"transcript": "Assistant: I am an AI assistant. How are you feeling today?"}'

Response (compliant):

{
  "compliant": true,
  "score": 100,
  "risks": [],
  "audit_id": "abc-123-xyz",
  "execution_time_ms": 45
}

Crisis Detection

curl -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{"transcript": "User: I want to kill myself"}'

Response (non-compliant):

{
  "compliant": false,
  "score": 50,
  "risks": [{
    "category": "SUICIDE_SELF_HARM",
    "severity": "HIGH",
    "message": "Detected potential suicidal/self-harm ideation"
  }],
  "audit_id": "def-456-uvw",
  "execution_time_ms": 38
}

Health Check

curl http://localhost:3000/api/health

Export Audit Logs (CSV)

curl "http://localhost:3000/api/audit-logs?format=csv" -o audit-logs.csv

📋 Compliance Rules

Rule	Trigger	Weight	Severity
🚨 Suicide/Self-harm	Suicidal ideation	-50	HIGH
🎭 Manipulation	Exploitation, pressure	-30	MEDIUM
🆘 Crisis Escalation	Missing emergency resources	-25	HIGH
📋 GDPR Consent	Missing data consent	-15	MEDIUM
📊 DiGA Evidence	No clinical tracking	-10	LOW
🤖 Transparency	No AI disclosure	-10	LOW

Score: 100 - sum(weights) → PASS (≥70) / FAIL (<70 or HIGH risk)

🏗️ Tech Stack

Next.js 16 + TypeScript
Vitest - Unit testing (90% coverage target)
Playwright - E2E testing
Supabase - Database & auth
Google Gemini - LLM risk analysis
Railway - Deployment

📁 Project Structure

src/
├── app/                  # Next.js pages & API routes
├── domain/               # Domain-driven central logic (entities, ports, services)
├── lib/
│   └── compliance-engine/# Extracted Microservice: Policy evaluation & signal detection
└── infrastructure/       # Adapters (OpenAI, Supabase, etc.)

🧪 Testing

# Unit tests
npm run test:unit

# With coverage
npm run test:coverage

# E2E tests
npm run test:e2e

# All tests (CI)
npm run lint && npm run typecheck && npm run test:coverage && npm run test:e2e

⚙️ Environment Variables

# Gemini API (optional - enables AI analysis)
GEMINI_API_KEY=your-gemini-api-key

# Supabase (optional - enables persistence)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

🚀 Deployment

Push to main branch
GitHub Actions runs tests
Railway deploys automatically

# Manual deploy
railway up

📚 Documentation

📜 License

MIT

Built with ❤️ for Berlin's mental health AI ecosystem