# gmaxdev/gamitask architecture

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

- Interactive diagram: https://gitdiagram.com/gmaxdev/gamitask
- Repository: https://github.com/gmaxdev/gamitask

## Overview

gamiTask is a social 3D café for working on tasks, with focus timers, character customization, room furniture, and shared progression. The main workflow is to enter a café or private room, manage and score tasks, and receive server-calculated rewards that appear in player state and room activity. The client also supports Google identity, Twitch linking, and a moderator object workshop; a separate landing page includes an offline preview and Pro waitlist. The map follows README-described features and sampled entry points; some subsystem wiring is documented but its implementation was not sampled.

Main entry points: [`app/src/main.ts`](https://github.com/gmaxdev/gamitask/blob/main/app/src/main.ts) (App coordinator), [`server/src/index.ts`](https://github.com/gmaxdev/gamitask/blob/main/server/src/index.ts) (HTTP and sockets), [`app/src/tasks-ui.ts`](https://github.com/gmaxdev/gamitask/blob/main/app/src/tasks-ui.ts) (Task interface), [`app/src/net.ts`](https://github.com/gmaxdev/gamitask/blob/main/app/src/net.ts) (Socket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Café client"]
  node_main["App coordinator<br/>[main.ts]"]
  node_net["Socket client<br/>[net.ts]"]
  node_rooms["Room selection<br/>[rooms.ts]"]
  node_scene["3D café scene<br/>[scene.ts]"]
  node_chat["Room chat<br/>[chat.ts]"]
end

subgraph group_game["Tasks and progression"]
  node_tasksui["Task interface<br/>[tasks-ui.ts]"]
  node_tasks["Task state<br/>[tasks.ts]"]
  node_scoring["Scoring rules<br/>[scoring.ts]"]
  node_pomo["Focus timer<br/>[pomo.ts]"]
  node_pomoui["Timer interface<br/>[pomodoro-ui.ts]"]
  node_progress["Player progress<br/>[progress.ts]"]
  node_journal["Daily journal<br/>[journal.ts]"]
end

subgraph group_server["Realtime service"]
  node_serverindex["HTTP and sockets<br/>[index.ts]"]
  node_database[("SQLite state<br/>[index.ts]")]
end

subgraph group_custom["Identity and objects"]
  node_auth["Auth and roles<br/>[auth.ts]"]
  node_look["Character looks<br/>[look.ts]"]
  node_editor["Character editor<br/>[editor.ts]"]
  node_workshop["Object workshop<br/>[workshop.ts]"]
  node_catalog["Catalog service<br/>[catalog.ts]"]
end

subgraph group_landing["Landing and integrations"]
  node_landing["Landing experience<br/>[landing.ts]"]
  node_waitlist["Pro waitlist<br/>[waitlist.ts]"]
  node_twitch["Twitch integration<br/>[twitch.ts]"]
end

node_player(("Player"))
node_google{{"Google identity"}}
node_twitchservice{{"Twitch service"}}

node_player -->|"uses"| node_main
node_main -->|"connects through"| node_net
node_main -->|"selects room"| node_rooms
node_rooms -->|"mounts room"| node_scene
node_main -->|"coordinates"| node_scene
node_main -->|"opens editor"| node_editor
node_editor -->|"edits look"| node_look
node_main -->|"opens workshop"| node_workshop
node_workshop -->|"sends catalog edits"| node_net
node_player -->|"manages tasks"| node_tasksui
node_tasksui -->|"updates state"| node_tasks
node_tasksui -->|"reads rules"| node_scoring
node_tasksui -->|"emits task actions"| node_net
node_player -->|"starts focus"| node_pomoui
node_pomoui -->|"controls timer"| node_pomo
node_main -->|"records events"| node_journal
node_net -->|"exchanges socket events"| node_serverindex
node_serverindex -->|"reads and writes"| node_database
node_serverindex -->|"applies task rules"| node_scoring
node_serverindex -->|"verifies permissions"| node_auth
node_serverindex -->|"handles catalog edits"| node_catalog
node_serverindex -->|"handles Twitch requests"| node_twitch
node_serverindex -->|"sends look state"| node_look
node_serverindex -->|"sends player state"| node_progress
node_google -->|"provides sign-in"| node_main
node_main -->|"requests authentication"| node_serverindex
node_twitchservice -.->|"provides channel data"| node_twitch
node_player -->|"visits"| node_landing
node_landing -->|"submits interest"| node_waitlist
node_waitlist -->|"stores entries"| node_database

click node_main "https://github.com/gmaxdev/gamitask/blob/main/app/src/main.ts"
click node_net "https://github.com/gmaxdev/gamitask/blob/main/app/src/net.ts"
click node_rooms "https://github.com/gmaxdev/gamitask/blob/main/app/src/rooms.ts"
click node_scene "https://github.com/gmaxdev/gamitask/blob/main/app/src/scene.ts"
click node_chat "https://github.com/gmaxdev/gamitask/blob/main/app/src/chat.ts"
click node_tasksui "https://github.com/gmaxdev/gamitask/blob/main/app/src/tasks-ui.ts"
click node_tasks "https://github.com/gmaxdev/gamitask/blob/main/app/src/tasks.ts"
click node_scoring "https://github.com/gmaxdev/gamitask/blob/main/server/src/scoring.ts"
click node_pomo "https://github.com/gmaxdev/gamitask/blob/main/app/src/pomo.ts"
click node_pomoui "https://github.com/gmaxdev/gamitask/blob/main/app/src/pomodoro-ui.ts"
click node_progress "https://github.com/gmaxdev/gamitask/blob/main/app/src/progress.ts"
click node_journal "https://github.com/gmaxdev/gamitask/blob/main/app/src/journal.ts"
click node_serverindex "https://github.com/gmaxdev/gamitask/blob/main/server/src/index.ts"
click node_database "https://github.com/gmaxdev/gamitask/blob/main/server/src/index.ts"
click node_auth "https://github.com/gmaxdev/gamitask/blob/main/server/src/auth.ts"
click node_look "https://github.com/gmaxdev/gamitask/blob/main/app/src/look.ts"
click node_editor "https://github.com/gmaxdev/gamitask/blob/main/app/src/editor.ts"
click node_workshop "https://github.com/gmaxdev/gamitask/blob/main/app/src/workshop.ts"
click node_catalog "https://github.com/gmaxdev/gamitask/blob/main/server/src/catalog.ts"
click node_landing "https://github.com/gmaxdev/gamitask/blob/main/app/src/landing.ts"
click node_waitlist "https://github.com/gmaxdev/gamitask/blob/main/server/src/waitlist.ts"
click node_twitch "https://github.com/gmaxdev/gamitask/blob/main/server/src/twitch.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_main,node_net,node_rooms,node_scene,node_chat toneBlue
class node_tasksui,node_tasks,node_scoring,node_pomo,node_pomoui,node_progress,node_journal toneAmber
class node_serverindex,node_database toneMint
class node_auth,node_look,node_editor,node_workshop,node_catalog toneRose
class node_landing,node_waitlist,node_twitch,node_player,node_google,node_twitchservice toneIndigo
```

## Components

### Café client

- [App coordinator](https://github.com/gmaxdev/gamitask/blob/main/app/src/main.ts): `app/src/main.ts`
- [Socket client](https://github.com/gmaxdev/gamitask/blob/main/app/src/net.ts): `app/src/net.ts`
- [Room selection](https://github.com/gmaxdev/gamitask/blob/main/app/src/rooms.ts): `app/src/rooms.ts`
- [3D café scene](https://github.com/gmaxdev/gamitask/blob/main/app/src/scene.ts): `app/src/scene.ts`
- [Room chat](https://github.com/gmaxdev/gamitask/blob/main/app/src/chat.ts): `app/src/chat.ts`

### Tasks and progression

- [Task interface](https://github.com/gmaxdev/gamitask/blob/main/app/src/tasks-ui.ts): `app/src/tasks-ui.ts`
- [Task state](https://github.com/gmaxdev/gamitask/blob/main/app/src/tasks.ts): `app/src/tasks.ts`
- [Scoring rules](https://github.com/gmaxdev/gamitask/blob/main/server/src/scoring.ts): `server/src/scoring.ts`
- [Focus timer](https://github.com/gmaxdev/gamitask/blob/main/app/src/pomo.ts): `app/src/pomo.ts`
- [Timer interface](https://github.com/gmaxdev/gamitask/blob/main/app/src/pomodoro-ui.ts): `app/src/pomodoro-ui.ts`
- [Player progress](https://github.com/gmaxdev/gamitask/blob/main/app/src/progress.ts): `app/src/progress.ts`
- [Daily journal](https://github.com/gmaxdev/gamitask/blob/main/app/src/journal.ts): `app/src/journal.ts`

### Realtime service

- [HTTP and sockets](https://github.com/gmaxdev/gamitask/blob/main/server/src/index.ts): `server/src/index.ts`
- [SQLite state](https://github.com/gmaxdev/gamitask/blob/main/server/src/index.ts): `server/src/index.ts`

### Identity and objects

- [Auth and roles](https://github.com/gmaxdev/gamitask/blob/main/server/src/auth.ts): `server/src/auth.ts`
- [Character looks](https://github.com/gmaxdev/gamitask/blob/main/app/src/look.ts): `app/src/look.ts`
- [Character editor](https://github.com/gmaxdev/gamitask/blob/main/app/src/editor.ts): `app/src/editor.ts`
- [Object workshop](https://github.com/gmaxdev/gamitask/blob/main/app/src/workshop.ts): `app/src/workshop.ts`
- [Catalog service](https://github.com/gmaxdev/gamitask/blob/main/server/src/catalog.ts): `server/src/catalog.ts`

### Landing and integrations

- [Landing experience](https://github.com/gmaxdev/gamitask/blob/main/app/src/landing.ts): `app/src/landing.ts`
- [Pro waitlist](https://github.com/gmaxdev/gamitask/blob/main/server/src/waitlist.ts): `server/src/waitlist.ts`
- [Twitch integration](https://github.com/gmaxdev/gamitask/blob/main/server/src/twitch.ts): `server/src/twitch.ts`

### Other components

- **Player**
- **Google identity**
- **Twitch service**

## Connections

- Player → App coordinator: uses
- App coordinator → Socket client: connects through
- App coordinator → Room selection: selects room
- Room selection → 3D café scene: mounts room
- App coordinator → 3D café scene: coordinates
- App coordinator → Character editor: opens editor
- Character editor → Character looks: edits look
- App coordinator → Object workshop: opens workshop
- Object workshop → Socket client: sends catalog edits
- Player → Task interface: manages tasks
- Task interface → Task state: updates state
- Task interface → Scoring rules: reads rules
- Task interface → Socket client: emits task actions
- Player → Timer interface: starts focus
- Timer interface → Focus timer: controls timer
- App coordinator → Daily journal: records events
- Socket client → HTTP and sockets: exchanges socket events
- HTTP and sockets → SQLite state: reads and writes
- HTTP and sockets → Scoring rules: applies task rules
- HTTP and sockets → Auth and roles: verifies permissions
- HTTP and sockets → Catalog service: handles catalog edits
- HTTP and sockets → Twitch integration: handles Twitch requests
- HTTP and sockets → Character looks: sends look state
- HTTP and sockets → Player progress: sends player state
- Google identity → App coordinator: provides sign-in
- App coordinator → HTTP and sockets: requests authentication
- Twitch service → Twitch integration: provides channel data
- Player → Landing experience: visits
- Landing experience → Pro waitlist: submits interest
- Pro waitlist → SQLite state: stores entries