# hades0050/noteboard-speek architecture

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

- Interactive diagram: https://gitdiagram.com/hades0050/noteboard-speek
- Repository: https://github.com/hades0050/noteboard-speek

## Overview

Noteboard combines notes, a kanban board, image/audio attachments, and background speech transcription. Users create and manage notes through the web UI and ConnectRPC; audio is uploaded separately over REST, queued for transcription, and the resulting text is stored with the note. The Go app wires transport adapters, use cases, persistence, and STT implementations. The README and sampled wiring establish the main architecture; some UI-to-board and RPC-handler details are represented only as documented or unverified relationships.

Main entry points: [`internal/app/app.go`](https://github.com/hades0050/noteboard-speek/blob/main/internal/app/app.go) (Application wiring), [`internal/usecase/transcribe.go`](https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/transcribe.go) (Transcription worker), [`internal/controller/rpc`](https://github.com/hades0050/noteboard-speek/tree/main/internal/controller/rpc) (ConnectRPC handlers), [`web/app/composables/useNotes.ts`](https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useNotes.ts) (Notes state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_webui["Notes and board UI<br/>[index.vue]"]
  node_note_modal["Note editor modal<br/>[NoteModal.vue]"]
  node_recorder["Audio recorder<br/>[useRecorder.ts]"]
  node_notes_state["Notes state<br/>[useNotes.ts]"]
  node_rpc_client["RPC clients<br/>[useRpc.ts]"]
  node_ts_proto["TypeScript API types<br/>[noteboard_pb.ts]"]
end

subgraph group_transport["API adapters"]
  node_proto["API contract<br/>[noteboard.proto]"]
  node_main["Process entry<br/>[main.go]"]
  node_app["Application wiring<br/>[app.go]"]
  node_rpc["ConnectRPC handlers"]
  node_connect_gen["Generated Connect handlers"]
  node_rest["REST files and health"]
  node_static["Embedded web delivery<br/>[webui.go]"]
end

subgraph group_domain["Use cases"]
  node_notes_uc["Notes workflows<br/>[notes.go]"]
  node_board_uc["Board workflows<br/>[board.go]"]
  node_transcribe_uc["Transcription worker<br/>[transcribe.go]"]
  node_entities["Domain entities"]
end

subgraph group_storage["Persistence"]
  node_sqlite_notes["Notes repository<br/>[notes.go]"]
  node_sqlite_board["Board repository<br/>[board.go]"]
  node_sqlite_queue["Transcription queue<br/>[queue.go]"]
  node_database[("SQLite database")]
  node_blob["Audio and image files<br/>[blob.go]"]
end

subgraph group_speech["Speech processing"]
  node_stt["STT engine adapters"]
  node_converter["Audio conversion<br/>[ffmpeg.go]"]
end

node_user(("User"))
node_stt_service["STT service"]

node_user -->|"uses"| node_webui
node_webui -->|"opens"| node_note_modal
node_webui -->|"loads notes"| node_notes_state
node_note_modal -.->|"records audio"| node_recorder
node_note_modal -.->|"edits notes"| node_notes_state
node_notes_state -->|"calls"| node_rpc_client
node_rpc_client -.->|"uses contract"| node_proto
node_rpc_client -->|"sends RPC"| node_rpc
node_notes_state -->|"uploads audio"| node_rest
node_main -->|"starts"| node_app
node_app -->|"mounts"| node_rpc
node_app -->|"constructs"| node_rest
node_app -->|"loads handler"| node_static
node_connect_gen -.->|"dispatches handlers"| node_rpc
node_rpc -.->|"handles note calls"| node_notes_uc
node_rpc -.->|"handles board calls"| node_board_uc
node_rest -->|"handles files"| node_blob
node_notes_uc -.->|"persists notes"| node_sqlite_notes
node_board_uc -.->|"persists board"| node_sqlite_board
node_transcribe_uc -->|"claims and finishes"| node_sqlite_queue
node_transcribe_uc -->|"converts audio"| node_converter
node_transcribe_uc -->|"transcribes"| node_stt
node_stt -.->|"calls when configured"| node_stt_service
node_app -->|"starts worker"| node_transcribe_uc
node_app -->|"constructs repository"| node_sqlite_notes
node_app -->|"constructs repository"| node_sqlite_board
node_app -->|"constructs repository"| node_sqlite_queue
node_sqlite_notes -.->|"reads and writes"| node_database
node_sqlite_board -->|"reads and writes"| node_database
node_sqlite_queue -.->|"stores queue"| node_database
node_notes_uc -.->|"uses domain types"| node_entities
node_board_uc -.->|"uses domain types"| node_entities
node_transcribe_uc -->|"processes notes"| node_entities
node_app -->|"constructs stores"| node_blob

click node_webui "https://github.com/hades0050/noteboard-speek/blob/main/web/app/pages/index.vue"
click node_note_modal "https://github.com/hades0050/noteboard-speek/blob/main/web/app/components/NoteModal.vue"
click node_recorder "https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useRecorder.ts"
click node_notes_state "https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useNotes.ts"
click node_rpc_client "https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useRpc.ts"
click node_ts_proto "https://github.com/hades0050/noteboard-speek/blob/main/web/app/gen/noteboard/v1/noteboard_pb.ts"
click node_proto "https://github.com/hades0050/noteboard-speek/blob/main/api/proto/noteboard/v1/noteboard.proto"
click node_main "https://github.com/hades0050/noteboard-speek/blob/main/cmd/noteboard/main.go"
click node_app "https://github.com/hades0050/noteboard-speek/blob/main/internal/app/app.go"
click node_rpc "https://github.com/hades0050/noteboard-speek/tree/main/internal/controller/rpc"
click node_connect_gen "https://github.com/hades0050/noteboard-speek/blob/main/internal/gen/noteboard/v1/noteboardv1connect/noteboard.connect.go"
click node_rest "https://github.com/hades0050/noteboard-speek/tree/main/internal/controller/rest"
click node_notes_uc "https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/notes.go"
click node_board_uc "https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/board.go"
click node_transcribe_uc "https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/transcribe.go"
click node_entities "https://github.com/hades0050/noteboard-speek/tree/main/internal/entity"
click node_sqlite_notes "https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/notes.go"
click node_sqlite_board "https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/board.go"
click node_sqlite_queue "https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/queue.go"
click node_database "https://github.com/hades0050/noteboard-speek/tree/main/internal/repo/sqlite"
click node_blob "https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/blob/blob.go"
click node_stt "https://github.com/hades0050/noteboard-speek/tree/main/internal/stt"
click node_converter "https://github.com/hades0050/noteboard-speek/blob/main/internal/stt/ffmpeg.go"
click node_static "https://github.com/hades0050/noteboard-speek/blob/main/internal/webui/webui.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_webui,node_note_modal,node_recorder,node_notes_state,node_rpc_client,node_ts_proto,node_user toneBlue
class node_proto,node_main,node_app,node_rpc,node_connect_gen,node_rest,node_static toneAmber
class node_notes_uc,node_board_uc,node_transcribe_uc,node_entities toneMint
class node_sqlite_notes,node_sqlite_board,node_sqlite_queue,node_database,node_blob toneRose
class node_stt,node_converter,node_stt_service toneIndigo
```

## Components

### Web app

- [Notes and board UI](https://github.com/hades0050/noteboard-speek/blob/main/web/app/pages/index.vue): `web/app/pages/index.vue`
- [Note editor modal](https://github.com/hades0050/noteboard-speek/blob/main/web/app/components/NoteModal.vue): `web/app/components/NoteModal.vue`
- [Audio recorder](https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useRecorder.ts): `web/app/composables/useRecorder.ts`
- [Notes state](https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useNotes.ts): `web/app/composables/useNotes.ts`
- [RPC clients](https://github.com/hades0050/noteboard-speek/blob/main/web/app/composables/useRpc.ts): `web/app/composables/useRpc.ts`
- [TypeScript API types](https://github.com/hades0050/noteboard-speek/blob/main/web/app/gen/noteboard/v1/noteboard_pb.ts): `web/app/gen/noteboard/v1/noteboard_pb.ts`

### API adapters

- [API contract](https://github.com/hades0050/noteboard-speek/blob/main/api/proto/noteboard/v1/noteboard.proto): `api/proto/noteboard/v1/noteboard.proto`
- [Process entry](https://github.com/hades0050/noteboard-speek/blob/main/cmd/noteboard/main.go): `cmd/noteboard/main.go`
- [Application wiring](https://github.com/hades0050/noteboard-speek/blob/main/internal/app/app.go): `internal/app/app.go`
- [ConnectRPC handlers](https://github.com/hades0050/noteboard-speek/tree/main/internal/controller/rpc): `internal/controller/rpc`
- [Generated Connect handlers](https://github.com/hades0050/noteboard-speek/blob/main/internal/gen/noteboard/v1/noteboardv1connect/noteboard.connect.go): `internal/gen/noteboard/v1/noteboardv1connect/noteboard.connect.go`
- [REST files and health](https://github.com/hades0050/noteboard-speek/tree/main/internal/controller/rest): `internal/controller/rest`
- [Embedded web delivery](https://github.com/hades0050/noteboard-speek/blob/main/internal/webui/webui.go): `internal/webui/webui.go`

### Use cases

- [Notes workflows](https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/notes.go): `internal/usecase/notes.go`
- [Board workflows](https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/board.go): `internal/usecase/board.go`
- [Transcription worker](https://github.com/hades0050/noteboard-speek/blob/main/internal/usecase/transcribe.go): `internal/usecase/transcribe.go`
- [Domain entities](https://github.com/hades0050/noteboard-speek/tree/main/internal/entity): `internal/entity`

### Persistence

- [Notes repository](https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/notes.go): `internal/repo/sqlite/notes.go`
- [Board repository](https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/board.go): `internal/repo/sqlite/board.go`
- [Transcription queue](https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/sqlite/queue.go): `internal/repo/sqlite/queue.go`
- [SQLite database](https://github.com/hades0050/noteboard-speek/tree/main/internal/repo/sqlite): `internal/repo/sqlite`
- [Audio and image files](https://github.com/hades0050/noteboard-speek/blob/main/internal/repo/blob/blob.go): `internal/repo/blob/blob.go`

### Speech processing

- [STT engine adapters](https://github.com/hades0050/noteboard-speek/tree/main/internal/stt): `internal/stt`
- [Audio conversion](https://github.com/hades0050/noteboard-speek/blob/main/internal/stt/ffmpeg.go): `internal/stt/ffmpeg.go`

### Other components

- **User**
- **STT service**

## Connections

- User → Notes and board UI: uses
- Notes and board UI → Note editor modal: opens
- Notes and board UI → Notes state: loads notes
- Note editor modal → Audio recorder: records audio
- Note editor modal → Notes state: edits notes
- Notes state → RPC clients: calls (evidence: `web/app/composables/useNotes.ts`)
- RPC clients → API contract: uses contract
- RPC clients → ConnectRPC handlers: sends RPC (evidence: `web/app/composables/useRpc.ts`)
- Notes state → REST files and health: uploads audio (evidence: `web/app/composables/useNotes.ts`)
- Process entry → Application wiring: starts (evidence: `cmd/noteboard/main.go`)
- Application wiring → ConnectRPC handlers: mounts (evidence: `internal/app/app.go`)
- Application wiring → REST files and health: constructs (evidence: `internal/app/app.go`)
- Application wiring → Embedded web delivery: loads handler (evidence: `internal/app/app.go`)
- Generated Connect handlers → ConnectRPC handlers: dispatches handlers
- ConnectRPC handlers → Notes workflows: handles note calls
- ConnectRPC handlers → Board workflows: handles board calls
- REST files and health → Audio and image files: handles files (evidence: `internal/controller/rest/router.go`)
- Notes workflows → Notes repository: persists notes
- Board workflows → Board repository: persists board
- Transcription worker → Transcription queue: claims and finishes (evidence: `internal/usecase/transcribe.go`)
- Transcription worker → Audio conversion: converts audio (evidence: `internal/usecase/transcribe.go`)
- Transcription worker → STT engine adapters: transcribes (evidence: `internal/usecase/transcribe.go`)
- STT engine adapters → STT service: calls when configured
- Application wiring → Transcription worker: starts worker (evidence: `internal/app/app.go`)
- Application wiring → Notes repository: constructs repository (evidence: `internal/app/app.go`)
- Application wiring → Board repository: constructs repository (evidence: `internal/app/app.go`)
- Application wiring → Transcription queue: constructs repository (evidence: `internal/app/app.go`)
- Notes repository → SQLite database: reads and writes
- Board repository → SQLite database: reads and writes (evidence: `internal/repo/sqlite/board.go`)
- Transcription queue → SQLite database: stores queue
- Notes workflows → Domain entities: uses domain types
- Board workflows → Domain entities: uses domain types
- Transcription worker → Domain entities: processes notes (evidence: `internal/usecase/transcribe.go`)
- Application wiring → Audio and image files: constructs stores (evidence: `internal/app/app.go`)
