# kie0611/huddle architecture

> Architecture diagram of the GitHub repository kie0611/huddle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kie0611/huddle
- Repository: https://github.com/kie0611/huddle

## Overview

Huddle is a temporary shared canvas for group brainstorming: people create or join a room, then work with drawings and sticky notes; room data is retained and rooms expire after inactivity. The sampled code shows room and note/stroke API handlers, database query modules, and Liveblocks event broadcasting. Chat is described as ephemeral in the room UI and represented in the event types, but no chat dispatch or persistence path is shown. Some room-page behavior and query implementations were not sampled, so uncertain links are omitted.

Main entry points: [`db/queries/rooms.ts`](https://github.com/kie0611/huddle/blob/main/db/queries/rooms.ts) (Room queries), [`app/room/[code]/page.tsx`](https://github.com/kie0611/huddle/blob/main/app/room/%5Bcode%5D/page.tsx) (Room canvas UI), [`app/api/rooms/[code]/notes/route.ts`](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/notes/route.ts) (Notes API), [`app/api/rooms/[code]/strokes/route.ts`](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/strokes/route.ts) (Strokes API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Room entry"]
  node_home["Home and entry<br/>[page.tsx]"]
end

subgraph group_canvas["Shared canvas"]
  node_roomui["Room canvas UI<br/>[page.tsx]"]
  node_livebroadcast["Event broadcaster<br/>[liveblocks.ts]"]
end

subgraph group_api["Room APIs"]
  node_roomapi["Room lookup API<br/>[route.ts]"]
  node_createapi["Room creation API<br/>[route.ts]"]
  node_notesapi["Notes API<br/>[route.ts]"]
  node_noteitemapi["Note edit API<br/>[route.ts]"]
  node_strokesapi["Strokes API<br/>[route.ts]"]
  node_cleanup["Room cleanup<br/>[route.ts]"]
end

subgraph group_storage["Persistence"]
  node_roomqueries["Room queries<br/>[rooms.ts]"]
  node_notequeries["Note queries<br/>[notes.ts]"]
  node_strokequeries["Stroke queries<br/>[strokes.ts]"]
  node_dbclient["Database client<br/>[index.ts]"]
  node_schema["Data schema<br/>[schema.ts]"]
end

node_participant(("Participant"))
node_liveblocks["Liveblocks"]
node_scheduler(("Cron scheduler"))

node_participant -->|"opens"| node_home
node_home -->|"creates room"| node_createapi
node_home -->|"checks code"| node_roomapi
node_home -->|"opens room"| node_roomui
node_participant -->|"collaborates"| node_roomui
node_roomui -->|"loads room"| node_roomapi
node_roomapi -->|"looks up"| node_roomqueries
node_roomapi -->|"touches activity"| node_roomqueries
node_createapi -->|"creates room"| node_roomqueries
node_roomui -->|"loads notes"| node_notesapi
node_roomui -->|"edits notes"| node_noteitemapi
node_notesapi -->|"resolves room"| node_roomqueries
node_notesapi -->|"reads or creates"| node_notequeries
node_notesapi -->|"touches activity"| node_roomqueries
node_notesapi -->|"broadcasts note"| node_livebroadcast
node_noteitemapi -->|"resolves room"| node_roomqueries
node_noteitemapi -->|"updates or deletes"| node_notequeries
node_noteitemapi -->|"broadcasts change"| node_livebroadcast
node_roomui -->|"stroke operations"| node_strokesapi
node_strokesapi -->|"resolves room"| node_roomqueries
node_strokesapi -->|"touches activity"| node_roomqueries
node_strokesapi -->|"reads or creates"| node_strokequeries
node_strokesapi -->|"broadcasts stroke"| node_livebroadcast
node_livebroadcast -->|"dispatches event"| node_liveblocks
node_scheduler -->|"triggers"| node_cleanup
node_cleanup -->|"deletes expired rooms"| node_dbclient
node_roomqueries -->|"queries"| node_dbclient
node_notequeries -->|"queries"| node_dbclient
node_strokequeries -->|"queries"| node_dbclient
node_dbclient -->|"uses"| node_schema

click node_home "https://github.com/kie0611/huddle/blob/main/app/page.tsx"
click node_roomui "https://github.com/kie0611/huddle/blob/main/app/room/%5Bcode%5D/page.tsx"
click node_roomapi "https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/route.ts"
click node_createapi "https://github.com/kie0611/huddle/blob/main/app/api/rooms/route.ts"
click node_notesapi "https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/notes/route.ts"
click node_noteitemapi "https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/notes/%5Bid%5D/route.ts"
click node_strokesapi "https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/strokes/route.ts"
click node_cleanup "https://github.com/kie0611/huddle/blob/main/app/api/cron/cleanup-rooms/route.ts"
click node_roomqueries "https://github.com/kie0611/huddle/blob/main/db/queries/rooms.ts"
click node_notequeries "https://github.com/kie0611/huddle/blob/main/db/queries/notes.ts"
click node_strokequeries "https://github.com/kie0611/huddle/blob/main/db/queries/strokes.ts"
click node_dbclient "https://github.com/kie0611/huddle/blob/main/db/index.ts"
click node_schema "https://github.com/kie0611/huddle/blob/main/db/schema.ts"
click node_livebroadcast "https://github.com/kie0611/huddle/blob/main/lib/liveblocks.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home toneBlue
class node_roomui,node_livebroadcast toneAmber
class node_roomapi,node_createapi,node_notesapi,node_noteitemapi,node_strokesapi,node_cleanup toneMint
class node_roomqueries,node_notequeries,node_strokequeries,node_dbclient,node_schema,node_scheduler toneRose
class node_participant,node_liveblocks toneIndigo
```

## Components

### Room entry

- [Home and entry](https://github.com/kie0611/huddle/blob/main/app/page.tsx): `app/page.tsx`

### Shared canvas

- [Room canvas UI](https://github.com/kie0611/huddle/blob/main/app/room/%5Bcode%5D/page.tsx): `app/room/[code]/page.tsx`
- [Event broadcaster](https://github.com/kie0611/huddle/blob/main/lib/liveblocks.ts): `lib/liveblocks.ts`

### Room APIs

- [Room lookup API](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/route.ts): `app/api/rooms/[code]/route.ts`
- [Room creation API](https://github.com/kie0611/huddle/blob/main/app/api/rooms/route.ts): `app/api/rooms/route.ts`
- [Notes API](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/notes/route.ts): `app/api/rooms/[code]/notes/route.ts`
- [Note edit API](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/notes/%5Bid%5D/route.ts): `app/api/rooms/[code]/notes/[id]/route.ts`
- [Strokes API](https://github.com/kie0611/huddle/blob/main/app/api/rooms/%5Bcode%5D/strokes/route.ts): `app/api/rooms/[code]/strokes/route.ts`
- [Room cleanup](https://github.com/kie0611/huddle/blob/main/app/api/cron/cleanup-rooms/route.ts): `app/api/cron/cleanup-rooms/route.ts`

### Persistence

- [Room queries](https://github.com/kie0611/huddle/blob/main/db/queries/rooms.ts): `db/queries/rooms.ts`
- [Note queries](https://github.com/kie0611/huddle/blob/main/db/queries/notes.ts): `db/queries/notes.ts`
- [Stroke queries](https://github.com/kie0611/huddle/blob/main/db/queries/strokes.ts): `db/queries/strokes.ts`
- [Database client](https://github.com/kie0611/huddle/blob/main/db/index.ts): `db/index.ts`
- [Data schema](https://github.com/kie0611/huddle/blob/main/db/schema.ts): `db/schema.ts`

### Other components

- **Participant**
- **Liveblocks**
- **Cron scheduler**

## Connections

- Participant → Home and entry: opens
- Home and entry → Room creation API: creates room
- Home and entry → Room lookup API: checks code
- Home and entry → Room canvas UI: opens room
- Participant → Room canvas UI: collaborates
- Room canvas UI → Room lookup API: loads room
- Room lookup API → Room queries: looks up
- Room lookup API → Room queries: touches activity
- Room creation API → Room queries: creates room
- Room canvas UI → Notes API: loads notes
- Room canvas UI → Note edit API: edits notes
- Notes API → Room queries: resolves room
- Notes API → Note queries: reads or creates
- Notes API → Room queries: touches activity
- Notes API → Event broadcaster: broadcasts note
- Note edit API → Room queries: resolves room
- Note edit API → Note queries: updates or deletes
- Note edit API → Event broadcaster: broadcasts change
- Room canvas UI → Strokes API: stroke operations
- Strokes API → Room queries: resolves room
- Strokes API → Room queries: touches activity
- Strokes API → Stroke queries: reads or creates
- Strokes API → Event broadcaster: broadcasts stroke
- Event broadcaster → Liveblocks: dispatches event
- Cron scheduler → Room cleanup: triggers
- Room cleanup → Database client: deletes expired rooms
- Room queries → Database client: queries
- Note queries → Database client: queries
- Stroke queries → Database client: queries
- Database client → Data schema: uses