# markgrushevski/justpaint architecture

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

- Interactive diagram: https://gitdiagram.com/markgrushevski/justpaint
- Repository: https://github.com/markgrushevski/justpaint

## Overview

justpaint is a web drawing product centered on asynchronous, AI-judged drawing duels, with practice and a free-draw editor as companion modes. The principal flow is players joining a match, drawing the shared prompt, submitting vector documents, and receiving judged results that update ratings and the leaderboard. The Vue client shares a vector-editor package; the Go service coordinates match and AI workflows, persistence, and live updates. README capabilities are retained, but several client-to-API links are unverified because their callers were not sampled.

Main entry points: [`apps/web/src/router/index.ts`](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/router/index.ts) (Route views), [`server/internal/game/service.go`](https://github.com/markgrushevski/justpaint/blob/main/server/internal/game/service.go) (Duel lifecycle), [`server/cmd/server/app.go`](https://github.com/markgrushevski/justpaint/blob/main/server/cmd/server/app.go) (HTTP service), [`apps/web/src/core/api/http.ts`](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/core/api/http.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Vue application<br/>[App.vue]"]
  node_routes["Route views<br/>[index.ts]"]
  node_duelview["Duel screen<br/>[PlayView.vue]"]
  node_practiceview["Practice screen<br/>[PracticeView.vue]"]
  node_drawview["Free-draw screen<br/>[DrawView.vue]"]
  node_gallery["Drawing gallery<br/>[GalleryView.vue]"]
  node_leaderboard["Leaderboard"]
  node_api["HTTP client<br/>[http.ts]"]
end

subgraph group_editor["Drawing editor"]
  node_editorhost["Editor host<br/>[useEditorHost.ts]"]
  node_editorcore["Editor runtime<br/>[editor.ts]"]
  node_history["Undo history<br/>[history.ts]"]
  node_vector["Vector document<br/>[types.ts]"]
end

subgraph group_workflows["Game workflows"]
  node_game["Duel lifecycle<br/>[service.go]"]
  node_practice["Practice scoring<br/>[service.go]"]
  node_guess["Drawing guess<br/>[service.go]"]
  node_assist["AI assist<br/>[handler.go]"]
  node_drawings["Saved drawings<br/>[handler.go]"]
  node_ratings["Ratings and ranking<br/>[service.go]"]
  node_websocket["Live match updates<br/>[handler.go]"]
end

subgraph group_ai["AI and rendering"]
  node_judge["AI judge<br/>[judge.go]"]
  node_render["Raster renderer<br/>[render.go]"]
end

subgraph group_platform["Service and data"]
  node_backend["HTTP service<br/>[app.go]"]
  node_database[("Postgres<br/>[db.go]")]
end

node_player(("Player"))
node_ai_provider["AI provider"]

node_player -->|"opens modes"| node_routes
node_app -->|"renders routes"| node_routes
node_routes -->|"routes to"| node_duelview
node_routes -->|"routes to"| node_practiceview
node_routes -->|"routes to"| node_drawview
node_routes -->|"routes to"| node_gallery
node_routes -->|"routes to"| node_leaderboard
node_drawview -.->|"hosts editor"| node_editorhost
node_editorhost -->|"creates editor"| node_editorcore
node_editorcore -->|"records commands"| node_history
node_editorcore -->|"maintains document"| node_vector
node_player -->|"draws prompt"| node_duelview
node_duelview -.->|"requests match"| node_api
node_practiceview -.->|"requests scoring"| node_api
node_drawview -.->|"uses AI features"| node_api
node_gallery -.->|"manages drawings"| node_api
node_leaderboard -.->|"loads rankings"| node_api
node_api -->|"calls API"| node_backend
node_backend -->|"registers routes"| node_game
node_backend -->|"registers routes"| node_practice
node_backend -->|"registers routes"| node_guess
node_backend -->|"registers routes"| node_assist
node_backend -->|"registers routes"| node_drawings
node_game -->|"renders submissions"| node_render
node_game -->|"scores drawings"| node_judge
node_practice -->|"renders drawing"| node_render
node_practice -->|"scores drawing"| node_judge
node_guess -->|"renders drawing"| node_render
node_guess -->|"requests guess"| node_judge
node_assist -->|"validates preview"| node_render
node_player -.->|"AI evaluation"| node_ai_provider
node_judge -.->|"delegates scoring"| node_ai_provider
node_game -.->|"persists match"| node_database
node_practice -.->|"stores runs"| node_database
node_drawings -.->|"reads and writes"| node_database
node_game -->|"updates Elo"| node_ratings
node_ratings -->|"reads rankings"| node_database
node_game -->|"publishes updates"| node_websocket
node_player -->|"saves and reopens"| node_gallery
node_editorcore -->|"shares rendering"| node_render

click node_app "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/App.vue"
click node_routes "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/router/index.ts"
click node_duelview "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/play/PlayView.vue"
click node_practiceview "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/practice/PracticeView.vue"
click node_drawview "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/draw/DrawView.vue"
click node_gallery "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/gallery/GalleryView.vue"
click node_leaderboard "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/leaderboard/LeaderboardView.vue"
click node_api "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/core/api/http.ts"
click node_editorhost "https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/editor/useEditorHost.ts"
click node_editorcore "https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/editor.ts"
click node_history "https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/history.ts"
click node_vector "https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/document/types.ts"
click node_backend "https://github.com/markgrushevski/justpaint/blob/main/server/cmd/server/app.go"
click node_game "https://github.com/markgrushevski/justpaint/blob/main/server/internal/game/service.go"
click node_practice "https://github.com/markgrushevski/justpaint/blob/main/server/internal/practice/service.go"
click node_guess "https://github.com/markgrushevski/justpaint/blob/main/server/internal/guess/service.go"
click node_assist "https://github.com/markgrushevski/justpaint/blob/main/server/internal/assist/handler.go"
click node_drawings "https://github.com/markgrushevski/justpaint/blob/main/server/internal/drawings/handler.go"
click node_judge "https://github.com/markgrushevski/justpaint/blob/main/server/internal/judge/judge.go"
click node_render "https://github.com/markgrushevski/justpaint/blob/main/server/internal/render/render.go"
click node_ratings "https://github.com/markgrushevski/justpaint/blob/main/server/internal/ratings/service.go"
click node_websocket "https://github.com/markgrushevski/justpaint/blob/main/server/internal/ws/handler.go"
click node_database "https://github.com/markgrushevski/justpaint/blob/main/server/internal/db/db.go"

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_app,node_routes,node_duelview,node_practiceview,node_drawview,node_gallery,node_leaderboard,node_api toneBlue
class node_editorhost,node_editorcore,node_history,node_vector toneAmber
class node_game,node_practice,node_guess,node_assist,node_drawings,node_ratings,node_websocket toneMint
class node_judge,node_render toneRose
class node_backend,node_database,node_player,node_ai_provider toneIndigo
```

## Components

### Web experience

- [Vue application](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/App.vue): `apps/web/src/App.vue`
- [Route views](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/router/index.ts): `apps/web/src/router/index.ts`
- [Duel screen](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/play/PlayView.vue): `apps/web/src/features/play/PlayView.vue`
- [Practice screen](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/practice/PracticeView.vue): `apps/web/src/features/practice/PracticeView.vue`
- [Free-draw screen](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/draw/DrawView.vue): `apps/web/src/features/draw/DrawView.vue`
- [Drawing gallery](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/gallery/GalleryView.vue): `apps/web/src/features/gallery/GalleryView.vue`
- [Leaderboard](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/leaderboard/LeaderboardView.vue): `apps/web/src/features/leaderboard/LeaderboardView.vue`
- [HTTP client](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/core/api/http.ts): `apps/web/src/core/api/http.ts`

### Drawing editor

- [Editor host](https://github.com/markgrushevski/justpaint/blob/main/apps/web/src/features/editor/useEditorHost.ts): `apps/web/src/features/editor/useEditorHost.ts`
- [Editor runtime](https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/editor.ts): `packages/editor/src/editor.ts`
- [Undo history](https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/history.ts): `packages/editor/src/history.ts`
- [Vector document](https://github.com/markgrushevski/justpaint/blob/main/packages/editor/src/document/types.ts): `packages/editor/src/document/types.ts`

### Game workflows

- [Duel lifecycle](https://github.com/markgrushevski/justpaint/blob/main/server/internal/game/service.go): `server/internal/game/service.go`
- [Practice scoring](https://github.com/markgrushevski/justpaint/blob/main/server/internal/practice/service.go): `server/internal/practice/service.go`
- [Drawing guess](https://github.com/markgrushevski/justpaint/blob/main/server/internal/guess/service.go): `server/internal/guess/service.go`
- [AI assist](https://github.com/markgrushevski/justpaint/blob/main/server/internal/assist/handler.go): `server/internal/assist/handler.go`
- [Saved drawings](https://github.com/markgrushevski/justpaint/blob/main/server/internal/drawings/handler.go): `server/internal/drawings/handler.go`
- [Ratings and ranking](https://github.com/markgrushevski/justpaint/blob/main/server/internal/ratings/service.go): `server/internal/ratings/service.go`
- [Live match updates](https://github.com/markgrushevski/justpaint/blob/main/server/internal/ws/handler.go): `server/internal/ws/handler.go`

### AI and rendering

- [AI judge](https://github.com/markgrushevski/justpaint/blob/main/server/internal/judge/judge.go): `server/internal/judge/judge.go`
- [Raster renderer](https://github.com/markgrushevski/justpaint/blob/main/server/internal/render/render.go): `server/internal/render/render.go`

### Service and data

- [HTTP service](https://github.com/markgrushevski/justpaint/blob/main/server/cmd/server/app.go): `server/cmd/server/app.go`
- [Postgres](https://github.com/markgrushevski/justpaint/blob/main/server/internal/db/db.go): `server/internal/db/db.go`

### Other components

- **Player**
- **AI provider**

## Connections

- Player → Route views: opens modes (evidence: `README.md`)
- Vue application → Route views: renders routes (evidence: `apps/web/src/main.ts`)
- Route views → Duel screen: routes to (evidence: `apps/web/src/router/index.ts`)
- Route views → Practice screen: routes to (evidence: `apps/web/src/router/index.ts`)
- Route views → Free-draw screen: routes to (evidence: `apps/web/src/router/index.ts`)
- Route views → Drawing gallery: routes to (evidence: `apps/web/src/router/index.ts`)
- Route views → Leaderboard: routes to (evidence: `apps/web/src/router/index.ts`)
- Free-draw screen → Editor host: hosts editor
- Editor host → Editor runtime: creates editor (evidence: `apps/web/src/features/editor/useEditorHost.ts`)
- Editor runtime → Undo history: records commands (evidence: `packages/editor/src/editor.ts`)
- Editor runtime → Vector document: maintains document (evidence: `packages/editor/src/editor.ts`)
- Player → Duel screen: draws prompt (evidence: `README.md`)
- Duel screen → HTTP client: requests match
- Practice screen → HTTP client: requests scoring
- Free-draw screen → HTTP client: uses AI features
- Drawing gallery → HTTP client: manages drawings
- Leaderboard → HTTP client: loads rankings
- HTTP client → HTTP service: calls API (evidence: `README.md`)
- HTTP service → Duel lifecycle: registers routes (evidence: `server/cmd/server/app.go`)
- HTTP service → Practice scoring: registers routes (evidence: `server/cmd/server/app.go`)
- HTTP service → Drawing guess: registers routes (evidence: `server/cmd/server/app.go`)
- HTTP service → AI assist: registers routes (evidence: `server/cmd/server/app.go`)
- HTTP service → Saved drawings: registers routes (evidence: `server/cmd/server/app.go`)
- Duel lifecycle → Raster renderer: renders submissions (evidence: `server/internal/game/service.go`)
- Duel lifecycle → AI judge: scores drawings (evidence: `server/internal/game/service.go`)
- Practice scoring → Raster renderer: renders drawing (evidence: `server/internal/practice/service.go`)
- Practice scoring → AI judge: scores drawing (evidence: `server/internal/practice/service.go`)
- Drawing guess → Raster renderer: renders drawing (evidence: `server/internal/guess/service.go`)
- Drawing guess → AI judge: requests guess (evidence: `server/internal/guess/service.go`)
- AI assist → Raster renderer: validates preview (evidence: `server/internal/assist/handler.go`)
- Player → AI provider: AI evaluation (evidence: `README.md`)
- AI judge → AI provider: delegates scoring (evidence: `README.md`)
- Duel lifecycle → Postgres: persists match
- Practice scoring → Postgres: stores runs
- Saved drawings → Postgres: reads and writes
- Duel lifecycle → Ratings and ranking: updates Elo (evidence: `README.md`)
- Ratings and ranking → Postgres: reads rankings
- Duel lifecycle → Live match updates: publishes updates (evidence: `README.md`)
- Player → Drawing gallery: saves and reopens (evidence: `README.md`)
- Editor runtime → Raster renderer: shares rendering (evidence: `README.md`)
