Backend architecture documentation for a HIPAA-compliant multi-agent system that augments therapy sessions.
Rung is a therapy augmentation platform that uses AI agents to:
- Pre-Session: Convert therapist voice memos into clinical briefs and client preparation guides
- Post-Session: Extract frameworks from session notes and generate development sprint plans
- Couples: Merge partner insights at the framework level (no raw data crossing)
| Component | Technology | Purpose |
|---|---|---|
| LLM | AWS Bedrock (Claude 3.5 Sonnet) | AI inference (HIPAA BAA) |
| Orchestration | Python async pipelines | Workflow execution (src/pipelines/) |
| API | FastAPI + Pydantic | Type-safe endpoints with validation |
| Deployment | ECS Fargate | Docker container on AWS |
| Database | RDS PostgreSQL + Alembic | Structured data with migrations |
| Storage | S3 (SSE-KMS) | Voice memos, transcripts, encrypted |
| Encryption | KMS envelope encryption | Field-level PHI encryption |
| Audit | Centralized service | HIPAA-compliant audit logging |
| Auth | Cognito | Therapist authentication with MFA |
| Research | Perplexity API | Evidence-based framework lookup (anonymized) |
Two isolated agents with strict context separation:
+---------------------------+ +---------------------------+
| RUNG AGENT | | BETH AGENT |
| (Clinical Analysis) | | (Client Communication) |
+---------------------------+ +---------------------------+
| Inputs: | | Inputs: |
| - Raw transcripts | | - Abstracted themes |
| - Session notes | | - Exercise templates |
| - Clinical history | | - Client language level |
+---------------------------+ +---------------------------+
| Outputs: | | Outputs: |
| - Clinical briefs | | - Client guides |
| - Framework analysis | | - Accessible exercises |
| - Risk assessments | | - Psychoeducation |
+---------------------------+ +---------------------------+
Critical: Beth NEVER receives raw clinical data. All content passes through an abstraction layer.
| File | Purpose |
|---|---|
| ARCHITECTURE.md | Complete technical specification |
| BLUEPRINT.md | Implementation phases with checkboxes |
| decisions.log | Architectural decision records |
- System Overview - High-level architecture diagram
- Service Architecture - Bounded contexts and communication patterns
- Data Models - Entity relationships and encryption strategy
- API Specifications - OpenAPI 3.0 spec with all endpoints
- n8n Workflows - Pre-session, post-session, and couples merge
- Security Architecture - Auth, encryption, audit logging
- Infrastructure - AWS components and deployment
- Implementation Phases - 6 phases over 20 weeks
Key compliance measures:
- AWS BAA covers all infrastructure
- Field-level encryption for PHI (AES-256-GCM, KMS)
- Audit logging with 7-year retention
- MFA required for all therapist access
- Perplexity queries anonymized (no BAA available)
- No PHI in Slack notifications
# Prerequisites
- AWS CLI configured
- Docker installed
- Python 3.11+
# Setup
cd ~/projects/Rung
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Run database migrations
make migrate
# Start development server
make dev
# Run tests
make test
# Build Docker image
make build
# Deploy to ECS (requires AWS credentials)
make deploy# Development
make dev # Start FastAPI dev server with auto-reload
make test # Run test suite with coverage
make lint # Run linters (ruff, mypy)
make fmt # Format code (Black, isort)
make migrate # Run database migrations
# Docker & Deployment
make build # Build Docker image locally
make run-local # Run container locally with .env
make push # Build and push to ECR
make deploy # Deploy to ECS Fargate
# Infrastructure
make tf-plan # Terraform plan (dev environment)
make tf-apply # Terraform apply (dev environment)- Architecture Design Complete
- Phase 0: Test Stabilization
- Phase A: Foundation (Encryption, Audit, Migrations)
- Phase B: Pipeline Orchestration (Pre-Session, Post-Session, Couples)
- Phase C: Progress Analytics
- Phase D: Deployment Infrastructure (ECS Fargate)
- Phase E: Documentation
- Phase E2: Reading List Feature (ADR-012)
- Phase F: Production Deployment
- Phase G: Couples Module Field Test
Architecture designed for Ralph-loop automation with clear completion criteria and testable components.
Last Updated: 2026-02-09