# tntcrafthim/piik architecture

> Architecture diagram of the GitHub repository tntcrafthim/piik, 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/tntcrafthim/piik
- Repository: https://github.com/tntcrafthim/piik

## Overview

Piik is a private screen-sharing product: a host selects a screen, window, tab, camera, and audio; creates a room and invitation; viewers join in a browser; media prefers direct peer connections, with optional server-side SFU forwarding. The graph covers the browser experience, desktop capture/runtime, and self-hosted room and signaling services. Source excerpts are partial, so uncertain module wiring is omitted; some server capabilities are included based on the README and file tree.

Main entry points: [`src/client/App.tsx`](https://github.com/tntcrafthim/piik/blob/main/src/client/App.tsx) (Client app), [`src/client/pages/HostPage.tsx`](https://github.com/tntcrafthim/piik/blob/main/src/client/pages/HostPage.tsx) (Host page), [`src/client/lib/session.ts`](https://github.com/tntcrafthim/piik/blob/main/src/client/lib/session.ts) (Room session), [`src/client/lib/signaling.ts`](https://github.com/tntcrafthim/piik/blob/main/src/client/lib/signaling.ts) (Signaling client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser experience"]
  node_client_app["Client app<br/>[App.tsx]"]
  node_host_page["Host page<br/>[HostPage.tsx]"]
  node_join_page["Join page<br/>[JoinPage.tsx]"]
  node_viewer_page["Viewer page<br/>[ViewerPage.tsx]"]
  node_signaling_client["Signaling client<br/>[signaling.ts]"]
  node_room_session["Room session<br/>[session.ts]"]
end

subgraph group_client_media["Client media"]
  node_browser_capture["Browser capture<br/>[capture-devices.ts]"]
  node_host_peer["Host peer media<br/>[host-peer.ts]"]
  node_viewer_peer["Viewer peer media<br/>[viewer-peer.ts]"]
  node_client_sfu["SFU client<br/>[publisher.ts]"]
end

subgraph group_desktop["Desktop app"]
  node_app_runtime["App runtime<br/>[app.go]"]
  node_loopback["Local control<br/>[server.go]"]
  node_native_capture["Native capture<br/>[stream.go]"]
  node_media_engine["Native media engine<br/>[engine.go]"]
end

subgraph group_server["Server services"]
  node_http_server["HTTP server<br/>[routes.go]"]
  node_signaling["Room signaling<br/>[server.go]"]
  node_room_store[("Room store<br/>[store.go]")]
  node_route_controller["Route controller<br/>[controller.go]"]
  node_sfu["SFU forwarding<br/>[media.go]"]
  node_forwarding["Media forwarding<br/>[transport.go]"]
end

node_host(("Host"))
node_viewer(("Viewer"))

node_host -->|"uses"| node_client_app
node_viewer -->|"joins through"| node_client_app
node_client_app -->|"dispatches"| node_host_page
node_client_app -->|"dispatches"| node_join_page
node_client_app -->|"dispatches"| node_viewer_page
node_host_page -->|"captures media"| node_browser_capture
node_host_page -->|"creates room"| node_room_session
node_join_page -->|"discovers room"| node_room_session
node_viewer_page -->|"loads session"| node_room_session
node_room_session -->|"exchanges signaling"| node_signaling_client
node_host_peer -->|"signals peers"| node_signaling_client
node_viewer_peer -->|"signals peers"| node_signaling_client
node_host_peer -->|"sends media"| node_viewer_peer
node_client_sfu -->|"receives assignment"| node_signaling_client
node_app_runtime -->|"starts"| node_loopback
node_app_runtime -->|"discovers capture"| node_native_capture
node_loopback -->|"controls process"| node_native_capture
node_app_runtime -->|"creates engine"| node_media_engine
node_host_page -.->|"uses local control"| node_loopback
node_viewer_page -->|"requests site"| node_http_server
node_http_server -->|"mutates rooms"| node_signaling
node_signaling -->|"reads and writes"| node_room_store
node_signaling -->|"executes routing"| node_route_controller
node_route_controller -->|"selects fallback"| node_sfu
node_sfu -->|"forwards media"| node_forwarding
node_client_sfu -.->|"publishes or subscribes"| node_sfu

click node_client_app "https://github.com/tntcrafthim/piik/blob/main/src/client/App.tsx"
click node_host_page "https://github.com/tntcrafthim/piik/blob/main/src/client/pages/HostPage.tsx"
click node_join_page "https://github.com/tntcrafthim/piik/blob/main/src/client/pages/JoinPage.tsx"
click node_viewer_page "https://github.com/tntcrafthim/piik/blob/main/src/client/pages/ViewerPage.tsx"
click node_signaling_client "https://github.com/tntcrafthim/piik/blob/main/src/client/lib/signaling.ts"
click node_room_session "https://github.com/tntcrafthim/piik/blob/main/src/client/lib/session.ts"
click node_browser_capture "https://github.com/tntcrafthim/piik/blob/main/src/client/media/capture-devices.ts"
click node_host_peer "https://github.com/tntcrafthim/piik/blob/main/src/client/webrtc/host-peer.ts"
click node_viewer_peer "https://github.com/tntcrafthim/piik/blob/main/src/client/webrtc/viewer-peer.ts"
click node_client_sfu "https://github.com/tntcrafthim/piik/blob/main/src/client/sfu/publisher.ts"
click node_app_runtime "https://github.com/tntcrafthim/piik/blob/main/internal/app/app.go"
click node_loopback "https://github.com/tntcrafthim/piik/blob/main/internal/app/loopback/server.go"
click node_native_capture "https://github.com/tntcrafthim/piik/blob/main/internal/app/nativecapture/stream.go"
click node_media_engine "https://github.com/tntcrafthim/piik/blob/main/internal/app/mediaedge/engine.go"
click node_http_server "https://github.com/tntcrafthim/piik/blob/main/internal/server/app/routes.go"
click node_signaling "https://github.com/tntcrafthim/piik/blob/main/internal/server/signal/server.go"
click node_room_store "https://github.com/tntcrafthim/piik/blob/main/internal/server/room/store.go"
click node_route_controller "https://github.com/tntcrafthim/piik/blob/main/internal/server/route/controller.go"
click node_sfu "https://github.com/tntcrafthim/piik/blob/main/internal/server/sfu/media.go"
click node_forwarding "https://github.com/tntcrafthim/piik/blob/main/internal/media/forwarding/transport.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_client_app,node_host_page,node_join_page,node_viewer_page,node_signaling_client,node_room_session,node_viewer toneBlue
class node_browser_capture,node_host_peer,node_viewer_peer,node_client_sfu toneAmber
class node_app_runtime,node_loopback,node_native_capture,node_media_engine toneMint
class node_http_server,node_signaling,node_room_store,node_route_controller,node_sfu,node_forwarding toneRose
class node_host toneIndigo
```

## Components

### Browser experience

- [Client app](https://github.com/tntcrafthim/piik/blob/main/src/client/App.tsx): `src/client/App.tsx`
- [Host page](https://github.com/tntcrafthim/piik/blob/main/src/client/pages/HostPage.tsx): `src/client/pages/HostPage.tsx`
- [Join page](https://github.com/tntcrafthim/piik/blob/main/src/client/pages/JoinPage.tsx): `src/client/pages/JoinPage.tsx`
- [Viewer page](https://github.com/tntcrafthim/piik/blob/main/src/client/pages/ViewerPage.tsx): `src/client/pages/ViewerPage.tsx`
- [Signaling client](https://github.com/tntcrafthim/piik/blob/main/src/client/lib/signaling.ts): `src/client/lib/signaling.ts`
- [Room session](https://github.com/tntcrafthim/piik/blob/main/src/client/lib/session.ts): `src/client/lib/session.ts`

### Client media

- [Browser capture](https://github.com/tntcrafthim/piik/blob/main/src/client/media/capture-devices.ts): `src/client/media/capture-devices.ts`
- [Host peer media](https://github.com/tntcrafthim/piik/blob/main/src/client/webrtc/host-peer.ts): `src/client/webrtc/host-peer.ts`
- [Viewer peer media](https://github.com/tntcrafthim/piik/blob/main/src/client/webrtc/viewer-peer.ts): `src/client/webrtc/viewer-peer.ts`
- [SFU client](https://github.com/tntcrafthim/piik/blob/main/src/client/sfu/publisher.ts): `src/client/sfu/publisher.ts`

### Desktop app

- [App runtime](https://github.com/tntcrafthim/piik/blob/main/internal/app/app.go): `internal/app/app.go`
- [Local control](https://github.com/tntcrafthim/piik/blob/main/internal/app/loopback/server.go): `internal/app/loopback/server.go`
- [Native capture](https://github.com/tntcrafthim/piik/blob/main/internal/app/nativecapture/stream.go): `internal/app/nativecapture/stream.go`
- [Native media engine](https://github.com/tntcrafthim/piik/blob/main/internal/app/mediaedge/engine.go): `internal/app/mediaedge/engine.go`

### Server services

- [HTTP server](https://github.com/tntcrafthim/piik/blob/main/internal/server/app/routes.go): `internal/server/app/routes.go`
- [Room signaling](https://github.com/tntcrafthim/piik/blob/main/internal/server/signal/server.go): `internal/server/signal/server.go`
- [Room store](https://github.com/tntcrafthim/piik/blob/main/internal/server/room/store.go): `internal/server/room/store.go`
- [Route controller](https://github.com/tntcrafthim/piik/blob/main/internal/server/route/controller.go): `internal/server/route/controller.go`
- [SFU forwarding](https://github.com/tntcrafthim/piik/blob/main/internal/server/sfu/media.go): `internal/server/sfu/media.go`
- [Media forwarding](https://github.com/tntcrafthim/piik/blob/main/internal/media/forwarding/transport.go): `internal/media/forwarding/transport.go`

### Other components

- **Host**
- **Viewer**

## Connections

- Host → Client app: uses
- Viewer → Client app: joins through
- Client app → Host page: dispatches
- Client app → Join page: dispatches
- Client app → Viewer page: dispatches
- Host page → Browser capture: captures media
- Host page → Room session: creates room
- Join page → Room session: discovers room
- Viewer page → Room session: loads session
- Room session → Signaling client: exchanges signaling
- Host peer media → Signaling client: signals peers
- Viewer peer media → Signaling client: signals peers
- Host peer media → Viewer peer media: sends media
- SFU client → Signaling client: receives assignment
- App runtime → Local control: starts
- App runtime → Native capture: discovers capture
- Local control → Native capture: controls process
- App runtime → Native media engine: creates engine
- Host page → Local control: uses local control
- Viewer page → HTTP server: requests site
- HTTP server → Room signaling: mutates rooms
- Room signaling → Room store: reads and writes
- Room signaling → Route controller: executes routing
- Route controller → SFU forwarding: selects fallback
- SFU forwarding → Media forwarding: forwards media
- SFU client → SFU forwarding: publishes or subscribes