Data Flows

This document describes how data moves through the humuus platform, from user authentication to real-time workshop interactions.

Authentication Flow

Authentication Methods

Device Authentication (Anonymous)

1. Client generates unique device ID on first launch
2. Nakama creates account with device ID as identifier
3. JWT token issued with 30-day expiration (configurable)
4. Token stored in browser's localStorage
5. Automatic reauthentication on subsequent visits

Use Case: Quick access for workshop participants without registration barriers

Email Authentication (Persistent)

1. User provides email/password via registration form
2. Nakama validates email format and password strength
3. Account created with email as primary identifier
4. Verification email sent (optional, configurable)
5. Session token issued after successful login

Use Case: Facilitators and users who want persistent accounts across devices

Token Management

• Token Structure: JWT with user ID, device ID, expiration timestamp
• Refresh Logic: Client automatically refreshes tokens 24 hours before expiration
• Invalidation: Tokens invalidated on logout or password change
• Security: Tokens stored with httpOnly flag when possible, cleared on logout

Session Persistence

Workshop Lifecycle

Workshop States

State	Description	Actions Available
Created	Match initialized, waiting for facilitator
Lobby	Participants can join, workshop not started	Kick participants, start workshop
Active	Workshop in progress, on current node	Progress to next node, pause
Ended	Manually terminated by facilitator	View partial results

Real-Time Interaction Flow

Node State Management

Transition Types:

• Manual: Facilitator clicks "Next" button
• Automatic: Timer expires or all participants complete the node

Data Persistence Flow

Data Models

Workshop Session

CREATE TABLE workshop_sessions (
    id UUID PRIMARY KEY,
    workshop_id VARCHAR(255) NOT NULL,
    match_id VARCHAR(255) UNIQUE NOT NULL,
    facilitator_id VARCHAR(255) NOT NULL,
    status VARCHAR(50) NOT NULL,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

Participant Actions

CREATE TABLE participant_actions (
    id BIGSERIAL PRIMARY KEY,
    session_id UUID REFERENCES workshop_sessions(id),
    user_id VARCHAR(255) NOT NULL,
    node_id VARCHAR(255) NOT NULL,
    action_type VARCHAR(100) NOT NULL,
    action_data JSONB,
    timestamp TIMESTAMP DEFAULT NOW(),
    INDEX idx_session_node (session_id, node_id)
);

File Upload Flow

File Handling

• Max File Size: 50MB per file (configurable)
• Allowed Types: Images (jpg, png, gif), PDFs, audio (mp3, wav), video (mp4)
• Virus Scanning: Optional ClamAV integration for uploaded files
• Retention: Files kept for 90 days after workshop completion
• CDN: Files served via CDN with appropriate cache headers

Error Handling & Recovery

Connection Loss

State Reconciliation

When a client reconnects after disconnection:

1. Send last known state version to server
2. Server calculates delta (changes since last known state)
3. Server sends minimal update to bring client up to date
4. Client merges changes with local state
5. UI updates to reflect current workshop state

Conflict Resolution

In rare cases where conflicting actions occur simultaneously:

• Server state is authoritative: Server's view always wins
• Timestamp-based ordering: Earlier actions take precedence
• Last-write-wins: For simple conflicts, most recent update is kept
• Manual resolution: For critical conflicts, facilitator is notified