Silo Server MigrationandClaude Opus 4.7
e8143d5757
- Narrow the worktree-id/T3-path check to docs/superpowers/specs and docs/superpowers/plans. Scanning the whole repo flagged any legitimate reference to .t3/worktrees or t3code-<hex> (fixtures, example configs) and would block unrelated commits. - Switch the pre-commit hook shebang to bash and call the check via an absolute path derived from git rev-parse so the hook works regardless of the cwd git happens to invoke it from. - install-hooks now warns when it overwrites an existing core.hooksPath rather than silently clobbering a custom setup. - Add make verify-local-paths to the AGENTS.md pre-MR checklist so contributors run it explicitly even when --no-verify is used. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
90 lines
5.8 KiB
Markdown
90 lines
5.8 KiB
Markdown
# 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/` as paired numbered `.up.sql` and `.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
|
|
|
|
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.
|