Tech workflow, architecture & plan of action

01 · Product shape

Five phases, one growing avatar

Beeing Human is an AI-avatar coaching platform. Each user gets two avatars — Avatar 2 (a likeness of themselves) and Avatar 1, a "brain" that grows and accumulates memory as the user moves through a structured journey of 4 stages · 12 modules · 3 lessons each. The MVP proves the first two phases end-to-end.

02 · Tech workflow

The two MVP flows, step by step

These are the user-facing sequences the MVP must support, annotated with the system responsibilities each step triggers. This is the spine the API contract and screens are built from.

03 · Architecture

Target system architecture

A service-oriented backend on AWS, HIPAA-eligible services throughout, with a media/AI edge for avatar delivery and an AvatarProvider abstraction so the pre-recorded and future real-time engines are interchangeable.

flowchart TB
  subgraph Clients
    M["Flutter Mobile<br/>iOS · Android"]
    W["Flutter Web<br/>user app"]
    A["Next.js<br/>Admin Panel"]
  end
  subgraph Edge["AWS Edge"]
    CF["CloudFront CDN"]
    GW["API Gateway / ALB"]
    COG["Cognito<br/>auth + BAA"]
  end
  subgraph Svc["FastAPI services · ECS Fargate (VPC)"]
    ID["Identity and Billing"]
    ON["Onboarding and Assessments"]
    OR["Orientation and Progress"]
    CH["Chat and Rooms"]
    AV["Avatar / Memory"]
  end
  subgraph AI["AI and Media"]
    BR["Bedrock<br/>Claude — chat/synthesis"]
    AVP["AvatarProvider<br/>pre-rec then real-time"]
    HG["HeyGen / D-ID<br/>video gen"]
    SP["Transcribe / Polly"]
  end
  subgraph Data
    PG[("RDS PostgreSQL<br/>+ pgvector")]
    RD[("ElastiCache Redis")]
    S3[("S3 + KMS<br/>media · PHI")]
    Q["SQS · async jobs"]
  end
  ST["Stripe"]

  M --> CF --> GW
  W --> CF
  A --> GW
  M -.auth.-> COG
  GW --> ID & ON & OR & CH & AV
  ID --> ST
  ON --> S3
  CH --> BR
  AV --> BR
  AVP --> HG
  OR --> AVP
  CH --> SP
  ID & ON & OR & CH & AV --> PG
  CH --> RD
  ON --> Q --> S3
  AV --> PG

Emotion / micro-expression detection runs on-device (Flutter + MediaPipe / ML Kit) — only derived signals, never raw video, reach the backend, minimizing PHI transfer.

Why these edges

• On-device emotion detection keeps biometric video off our servers — smaller compliance surface and lower latency than Rekognition round-trips.
• Bedrock (Claude) for chat, in-video Q&A, and post-module synthesis — HIPAA-eligible under AWS BAA, no data leaves the account boundary.
• AvatarProvider interface — PrerecordedVideoProvider ships now; RealtimeProvider (Unreal/RPM stream) slots in for P3/P4 live phases with no caller changes.
• Async job queue (SQS) handles video/audio transcode, resume parsing, and avatar-video generation off the request path.

04 · Data model

Database schema

PostgreSQL is the system of record. The "growing avatar" is modeled as avatar_memory nodes with pgvector embeddings, so knowledge, questions, and confidence signals accrue over time and are queryable semantically. Entities below the fold are modeled now but built in later phases.

erDiagram
  ORGANIZATION ||--o{ USER : "employs / enrolls"
  USER ||--|| PROFILE : has
  USER ||--o{ CONSENT : grants
  USER ||--o| SUBSCRIPTION : holds
  PLAN ||--o{ SUBSCRIPTION : defines
  USER ||--o{ AVATAR : owns
  USER ||--o{ ASSESSMENT : completes
  ASSESSMENT ||--o{ ASSESSMENT_RESPONSE : contains
  USER ||--o{ GROWTH_PLAN : has
  GROWTH_PLAN ||--o{ GROWTH_PLAN_ITEM : contains
  USER ||--o{ UPLOAD : submits
  AVATAR ||--o{ AVATAR_MEMORY : accrues
  PHASE ||--o{ MODULE : groups
  MODULE ||--o{ LESSON : contains
  USER ||--o{ ENROLLMENT : has
  ENROLLMENT ||--o{ MODULE_PROGRESS : tracks
  USER ||--o{ CHAT_MESSAGE : sends
  CHAT_ROOM ||--o{ CHAT_MESSAGE : holds
  USER ||--o{ FLAG : raises
  USER ||--o{ AUDIT_LOG : generates

  USER {
    uuid id PK
    uuid org_id FK
    string cognito_sub
    string email
    string phone
    string status
  }
  AVATAR {
    uuid id PK
    uuid user_id FK
    enum kind "self | growing"
    jsonb appearance
    int growth_level
  }
  AVATAR_MEMORY {
    uuid id PK
    uuid avatar_id FK
    enum kind "knowledge|gap|question|confidence"
    text content
    vector embedding
    uuid source_module_id
  }
  GROWTH_PLAN_ITEM {
    uuid id PK
    uuid plan_id FK
    enum type "value|strength|short_goal|long_goal"
    text content
  }
  MODULE_PROGRESS {
    uuid id PK
    uuid enrollment_id FK
    uuid module_id FK
    enum state
    jsonb engagement_signals
  }

Entity inventory

05 · Stack

Technology stack

Chosen for a small team moving fast to MVP, with every third-party under an AWS-signable BAA or kept clear of PHI. Shared type discipline via OpenAPI-generated clients into Flutter and the admin panel.

06 · Compliance & risk

Flags to resolve before build

The boards mention "EHR certified", "HIPAA", "relapse process", universities, and webcam emotion reading. Each carries regulatory weight that must be pinned down in this sprint — they change hosting, vendor, and consent decisions.

07 · Plan of action

The requirements sprint — this week

Five days to turn the boards into a build-ready foundation. Each day has a clear output; the week ends with a prioritized, estimated backlog and a green-lit architecture.

Sprint deliverables

Then — Sprint 0 (setup, week 2)

• Monorepo scaffold: /mobile (Flutter) · /admin (Next.js) · /api (FastAPI) · /infra (Terraform).
• AWS landing zone: VPC, KMS, RDS, Cognito, ECS, S3 buckets — encrypted, private-subnet, tagged.
• CI/CD pipelines + preview environments; OpenAPI client codegen into Flutter & admin.
• Auth + billing walking skeleton: sign-up → trial → authenticated "hello avatar" screen.