Architecture

Counslr SOS is an emergency PSAP routing platform that enables telehealth counselors to dispatch 911 to a patient’s location during a crisis. The system prioritizes low-latency response, HIPAA compliance through minimal data persistence, and multi-tenant isolation.

System Overview

                                         ┌────────────────────────────┐
                                         │         AWS VPC            │
┌─────────────┐     ┌──────────────┐     │  ┌──────────────────────┐  │
│ Patient SDK │────▶│              │     │  │  Lambda (Go)         │  │
│  (Browser)  │◀────│  API Gateway │────▶│  │  - Session mgmt      │  │
└─────────────┘     │  (REST +     │     │  │  - SOS handling      │  │
                    │   WebSocket) │     │  │  - PSAP lookup       │  │
┌─────────────┐     │              │     │  └───────────┬──────────┘  │
│  Counselor  │────▶│              │     │              │             │
│    SDK      │◀────└──────────────┘     │  ┌───────────▼──────────┐  │
│  (Browser)  │                          │  │  Aurora Serverless   │  │
└─────────────┘                          │  │  v2 + PostGIS        │  │
                                         │  └───────────┬──────────┘  │
                                         └──────────────┼─────────────┘
                                                        │
                                         ┌──────────────▼─────────────┐
                                         │  TrueVault (HIPAA)         │
                                         │  Crisis event logs         │
                                         └────────────────────────────┘

Clean Architecture

The codebase follows Clean Architecture with four layers. Dependencies point inward — the domain layer has zero external imports.

┌─────────────────────────────────────────────────┐
│  cmd/api, cmd/ws, cmd/migrate, cmd/import       │  Entrypoints
├─────────────────────────────────────────────────┤
│  internal/api        (HTTP handlers)            │  Adapters (outer)
│  internal/storage    (Postgres, DynamoDB,       │
│                       API Gateway, TrueVault)   │
├─────────────────────────────────────────────────┤
│  internal/service    (Use cases, interfaces)    │  Application
├─────────────────────────────────────────────────┤
│  internal/domain     (Entities, value objects)  │  Domain (inner)
└─────────────────────────────────────────────────┘

Repository interfaces are defined in internal/service/ (consumer side) and implemented in internal/storage/ (provider side).

SOS Data Flow

1. Counselor triggers SOS → POST /v1/platforms/{platformId}/sessions/{sessionId}/sos (counselor JWT required)
2. Session transitions to sos state → Aurora (session state update)
3. SOS event created → TrueVault (HIPAA-compliant)
4. Audit entry recorded → Aurora (tamper-evident hash chain)
5. Location request pushed → WebSocket location_request to patient
6. Patient submits location → POST /v1/platforms/{platformId}/sessions/{sessionId}/sos/location (patient JWT required)
7. PSAP lookup → PostGIS nearest-neighbor query (location in-memory only)
8. PSAP contacts returned → REST response + WebSocket push to counselor
9. Location discarded → Never written to any database

Key Components

HIPAA Compliance

Patient location is the most sensitive data in the system. The on-demand capture model ensures location is never at rest:

1. Patient grants geolocation permission at session start
2. SDK holds permission but does not transmit until SOS
3. During SOS, coordinates are held in Lambda process memory only
4. After PSAP lookup, location goes out of scope
5. Crisis logs record the event (who, when, which PSAP) but never the coordinates

See Security & HIPAA for the complete data classification and compliance model.