Feature Overview & Architecture

Virtual Spaces is a new DuckBuddy feature that gives users a visual, room-based chat experience. Instead of a plain text chat, users enter a styled virtual room where each participant is represented by an avatar seated at a desk. This creates a sense of presence — you can instantly see who’s online and ready to chat, and who’s stepped away.

Key Capabilities

Architecture

Roles & Legend

The swim lane diagram uses the following color coding for each role:

Timeline (X-Axis) — 7 Phases

Swim Lane Diagram — Virtual Spaces

Involvement Timeline Summary

Appendix: PostgreSQL Schema for Virtual Spaces

-- Virtual Spaces PostgreSQL Schema

CREATE TABLE rooms (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name          VARCHAR(100) NOT NULL,
    style_id      INTEGER REFERENCES room_styles(id),
    creator_id    UUID REFERENCES users(id),
    max_occupancy INTEGER DEFAULT 50,
    created_at    TIMESTAMPTZ DEFAULT NOW(),
    updated_at    TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE room_styles (
    id              SERIAL PRIMARY KEY,
    style_key       VARCHAR(50) UNIQUE NOT NULL,  -- 'cozy_loft', 'tech_startup', etc.
    display_name    VARCHAR(100) NOT NULL,
    bg_color        VARCHAR(20),
    desk_shape      VARCHAR(20),     -- 'rounded', 'square', 'organic'
    desk_color      VARCHAR(20),
    font_family     VARCHAR(100),
    preview_image   VARCHAR(255),
    sort_order      INTEGER DEFAULT 0
);

CREATE TABLE desks (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    room_id     UUID REFERENCES rooms(id) ON DELETE CASCADE,
    slot_number INTEGER NOT NULL,  -- position in grid (1..50)
    UNIQUE(room_id, slot_number)
);

CREATE TABLE desk_assignments (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    desk_id     UUID REFERENCES desks(id) ON DELETE CASCADE,
    user_id     UUID REFERENCES users(id),
    is_online   BOOLEAN DEFAULT TRUE,
    assigned_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE messages (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    room_id     UUID REFERENCES rooms(id) ON DELETE CASCADE,
    user_id     UUID REFERENCES users(id),
    body        TEXT NOT NULL,
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE presence_log (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    room_id     UUID REFERENCES rooms(id) ON DELETE CASCADE,
    user_id     UUID REFERENCES users(id),
    event       VARCHAR(20),  -- 'join', 'leave', 'disconnect'
    timestamp   TIMESTAMPTZ DEFAULT NOW()
);

Appendix: New API Endpoints for Virtual Spaces