Repository guide

Each TypeType component has a narrow ownership boundary, its own checks, and its own license. User-facing issues stay in the central TypeType tracker even when the fix belongs to a component repository.

Ownership at a glance

Change	Owning repository	Main source path
Docker Compose, installer, update, migration, or rollback	TypeType	docker-compose*.yml, scripts/
Page, route, nginx, settings control, account UI, or player controls	TypeType-Frontend	apps/web/src/, nginx.conf
Extraction, API route, account data, import, recommendation, or playback session	TypeType-Server	src/main/kotlin/dev/typetype/server/
PO token, YouTube player decoder, subtitle metadata, or remote-login browser	TypeType-Token	src/
Download queue, transfer, mux, storage, or artifact	TypeType-Downloader	cmd/, internal/, migrations/
MSE buffering, segment scheduling, seek, quality switch, or playback recovery	TypeType-Player	src/
Home page algorithm, its settings, or what it deduces	TypeType-Signals	recommender/
Discord presence detail, RPC handshake, or desktop tray behavior	TypeType-RPC	src-tauri/src/
User, operator, or project explanation	Docs-TypeType	docs/

Central stack

The TypeType repository is the integration point rather than a monolithic application. It contains Git submodules for the public components, but deployment uses the component images selected in docker-compose.yml.

Important paths:

• .env.example lists supported stack-level settings and image overrides.
• docker-compose.yml defines the stable service graph.
• docker-compose.dev.yml defines the beta graph.
• scripts/ owns install, update, migration backups, secret generation, Garage provisioning, and stable deployment helpers.

The default nginx configuration is bundled into the frontend image. The central stack therefore does not need to mount a matching host file on every update.

The repository is MIT licensed.

Frontend

The frontend is a Bun monorepo containing a React 19 application. TanStack Router and Query own navigation and server state, Zustand owns local state, Tailwind CSS owns styling, and Vidstack wraps the available playback providers.

Useful entry points:

• apps/web/src/routes for pages and route loaders;
• apps/web/src/components for shared UI and the player shell;
• apps/web/src/lib for API clients and browser integration;
• apps/web/src/hooks for query and feature behavior;
• apps/web/src/settings and apps/web/src/stores for persistent client choices.

Checks:

bun run check
bun run test
bun run knip
bun run sherif
bun run build

The repository is MIT licensed.

Server

The Server is a Kotlin/Ktor application on JDK 25. It uses PipePipeExtractor for supported media services, PostgreSQL through Exposed and HikariCP for persistent state, and Dragonfly through the Redis protocol for cache state.

Useful entry points:

• Application.kt and ApplicationRoutes.kt for service and route wiring;
• routes/ for the HTTP contract;
• services/ for application, extraction, and playback behavior;
• db/ for tables and migrations;
• openapi.yaml and openapi/ for the published API contract.

Checks:

./gradlew test
./gradlew shadowJar
./gradlew validateOpenApi

The repository is GPL-3.0 licensed because of its extractor integration.

Token

Token is an internal Bun service with a Playwright Chromium runtime. Its name is historical: it now provides much more than subtitles or a single token endpoint. It supplies YouTube visitor and PO-token data, player decoding, SABR session metadata, subtitles, and disposable remote-login browser sessions.

The frontend must not call Token directly. Server is its consumer and security boundary. See Security boundaries before customising its container.

Checks:

bun run lint
bun test
bun run build

The repository is MIT licensed.

Downloader

Downloader is a Go service with PostgreSQL-backed jobs, Dragonfly cache state, concurrent Range or SABR media transfer, libavformat muxing, SSE progress, and local or S3-compatible artifact storage.

Useful entry points:

• internal/api and internal/server for the internal HTTP API;
• internal/pipeline, internal/downloader, and internal/sabr for job execution;
• internal/mux and internal/ffmpeg for stream-copy muxing;
• internal/storage and internal/artifact for capacity and artifact delivery.

Checks:

gofmt -w cmd internal
go test ./...
go build ./...

The repository is GPL-3.0-or-later licensed.

Player

Player is the dependency-free TypeScript package published as @typetype/mse on npm and JSR. It turns a Server playback session into Media Source Extension buffers on an HTMLVideoElement. The package owns scheduling and recovery, while Frontend owns the controls and page layout.

Useful entry points include type-type-mse-player.ts, playback-loop.ts, segment-scheduler.ts, media-source-controller.ts, seek-controller.ts, and player-recovery.ts.

Checks:

bun run check
bun run check:docs
bun run check:jsr
bun run test:coverage
bun run build

The repository is MIT licensed.

RPC

RPC is the desktop companion that turns a user's current TypeType playback into a Discord Rich Presence status. It is a Tauri 2 app with a from-scratch Rust implementation of the Discord IPC protocol, no Electron and no Discord SDK dependency. It lives in the system tray and polls Server's presence endpoint only while sharing is turned on.

Useful entry points:

• src-tauri/src/discord_frame.rs and discord_socket.rs for the IPC wire format and local socket discovery;
• src-tauri/src/discord_rpc.rs for the handshake and activity commands;
• src-tauri/src/presence.rs for polling the presence endpoint;
• src-tauri/src/tray.rs for the tray menu and polling lifecycle;
• src/main.ts for the Settings window.

Checks:

cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml
bun run build

The repository is MIT licensed.

Signals

TypeType-Signals is the optional recommender: a Python service that holds the home page algorithms and nothing else. Server calls it, fetches the videos it asks for and filters what comes back. It is experimental.

docker compose up -d --build
uv run pytest

Important paths:

• recommender/algorithms/ holds one file per algorithm.
• recommender/contract.py and the contract_*.py files hold what Server sends and receives.
• tests/reference_pages.py builds the reference pages that prove a change altered no page.

See Signals, the recommender. The repository is licensed under the GNU Affero General Public License, version 3.

Documentation and organisation profile

Docs-TypeType is a VitePress site. User pages live in docs/guide, operator pages in docs/self-hosting, and developer-facing pages in docs/project. Build it with:

bun run docs:build

The documentation is MIT licensed. The .github profile repository contains only organisation presentation assets and does not declare a license.

Branch and issue workflow

Component development targets dev; main represents the stable release line. See Branches and releases before changing integration pins or images.

Open bugs, feature requests, and documentation reports in the central tracker. Once the owning component is known, open its code pull request against that component's dev branch. Documentation pull requests also target dev.

Source references

• Central repository README
• Frontend README
• Server README
• Token README
• Downloader README
• Player README
• RPC README
• Signals README