silo-server/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

cmd/silo contains the main server entrypoint. Backend code lives in internal/, organized by domain (api, catalog, metadata, playback, scanner, jellycompat, etc.); keep new code in the package that owns the behavior instead of creating catch-all helpers. Database changes belong in migrations/sql/ as Goose SQL migrations. Legacy converted migrations intentionally keep their original numeric versions so existing schema_versions rows can bootstrap cleanly into Goose. New migrations must use timestamped filenames created with make migrate-create NAME=add_thing; do not run goose fix or create paired .up.sql / .down.sql files. The React frontend lives in web/src/, with feature code split across components/, pages/, hooks/, player/, and lib/. Reference material belongs in docs/architecture/ or docs/superpowers/{specs,plans}/; ad hoc SQL helpers live in scripts/.

When creating or editing docs/superpowers/specs/ or docs/superpowers/plans/, never include local absolute filesystem paths or transient worktree IDs. Use repository-relative paths and wording like "Commands assume the repository root is the cwd."

This repository is a VERY EARLY WIP. Proposing sweeping changes that improve long-term maintainability is encouraged.

Core Priorities

1. Performance first.
2. Reliability first.
3. Keep behavior predictable under load and during failures (session restarts, reconnects, partial streams).

If a tradeoff is required, choose correctness and robustness over short-term convenience.

Maintainability

Long term maintainability is a core priority. If you add new functionality, first check if there is shared logic that can be extracted to a separate module. Duplicate logic across multiple files is a code smell and should be avoided. Don't be afraid to change existing code. Don't take shortcuts by just adding local logic to solve a problem.

This repository is part of a broader multi-repo Silo workspace. The sibling repositories are usually checked out side-by-side in the same parent directory.

• silo-server owns the Go backend, web admin UI, API contracts, auth/session behavior, catalog/scanner/playback services, database migrations, Jellyfin compatibility, and host-side plugin runtime.
• silo-android owns the Android phone and TV clients. Client-visible API, auth, playback, session, library, and metadata changes may require Android follow-up.
• silo-apple owns the iOS, tvOS, and macOS clients. Client-visible API, auth, playback, session, library, and metadata changes may require Apple follow-up.

When changing server behavior consumed by clients, check whether both client repos need model, routing, playback, or UX updates. Prefer coordinated multi-repo changes over leaving one platform behind.

Do not assume all plugin-related code lives in this repo.

• silo-plugin-sdk owns the public plugin SDK, protobuf contracts, generated plugin API code, manifest helpers, and runtime bootstrap.
• silo-plugins owns the central plugin catalog / repository manifest.
• First-party plugins such as silo-plugin-tmdb, and silo-plugin-tvdb live in their own repositories.
• Silo owns host-side plugin installation, runtime management, API handlers, and integration logic.

When a task mentions plugins, first determine whether the change belongs in this repo, the SDK repo, the catalog repo, or a specific plugin repo. Prefer coordinated multi-repo changes over forcing plugin work into Silo.

Build, and Development Commands

Use the checked-in Makefile for the common paths:

• make build: install frontend deps, build web/dist, compile ./silo
• make dev-backend: run the Go server in integrated mode
• make dev-frontend: start the Vite dev server with HMR
• make dev-proxy / make dev-transcode: run standalone worker modes
• make lint: run golangci-lint and frontend ESLint
• make migrate-status / make migrate-up: inspect or apply Goose migrations through Silo's legacy-safe bootstrapping runner

Run before opening a merge request:

• cd web && pnpm run lint
• cd web && pnpm run format:check
• make verify-local-paths

For local services, start PostgreSQL and Redis with docker compose up -d postgres redis.

Coding Style & Naming Conventions

Go code must stay gofmt/goimports clean and pass golangci-lint. Keep package names lowercase and focused; Frontend code is TypeScript with 2-space indentation, semicolons, double quotes, trailing commas, and a 100-character line width (web/.prettierrc). Use PascalCase.tsx for components/pages, useThing.ts for hooks, and keep shared utilities in web/src/lib or web/src/utils.

Deployment Debugging

When troubleshooting a Silo deployment (container health, playback failures, database state, log analysis, deploys), follow the runbook at .claude/skills/deployment-debugging/SKILL.md. It includes step-by-step procedures and a first-run setup that configures SSH, database, and Redis connection details for your environment.

Commit & Merge Request Guidelines

Recent history follows Conventional Commit-style subjects such as feat(playback): add realtime session hub, fix(playback): ..., and docs: .... Keep commits scoped to one concern. For non-trivial work, open an issue or discussion first; this codebase moves quickly. Merge requests should explain the problem, why this approach was chosen, linked issue/spec/plan, risks or follow-up work, and AI-use disclosure. Include screenshots or recordings for UI changes.

Learned User Preferences

• When implementing from an attached plan, do not edit the plan file itself.
• After feature work, user may invoke the /simplify skill to improve readability without changing behavior.

Learned Workspace Facts

• Silo separates login accounts (users) from household profiles; multiple profiles on one account share the same user_id.
• Profile is_primary marks the household parent for that account; it is not the same as server-wide admin role on the user account.
• Point the Vite dev frontend at a remote backend with VITE_API_PROXY_TARGET in web/.env.local (or inline) when running make dev-frontend; the frontend calls relative /api URLs proxied by Vite.

Silo v1 Process (scope lock & API rules)

Silo is working toward a locked v1 feature set so client teams can plan against a stable core. These rules apply to every change.

Scope gate. Before implementing a new user-facing capability, check docs/architecture/v1-scope.md. If the capability is not listed there — or the file says scope is not yet locked — do NOT open a feature PR. File a v1 capability proposal issue (template in this repo) and wait for triage. Bug fixes, refactors, and work on already-locked capabilities proceed normally.

API rules — additive-only within /api/v1.

• Never rename or remove a response field, change a field's type, or repurpose a status code on an existing endpoint.
• New functionality adds new fields/endpoints; removals go through the existing Deprecation/Sunset header flow only.
• New features expose capability endpoints (feature detection) rather than relying on version sniffing.
• Contract strategy and tooling: issue #135.

PR requirements.

• Link the capability epic or sub-issue the PR serves (Part of #NNN). PRs with no linked scope item will be questioned at review.
• One concern per PR; Conventional Commit subject; AI-use disclosure in the PR body.

Pre-push checklist. make lint · cd web && pnpm run lint && pnpm run format:check · make verify-local-paths · Go tests in a libvips-capable container (a bare-host go test ./... silently skips CGO packages, including internal/api/handlers).