From 4e5bca3c339def866ddc72bafdac885fe9b43b78 Mon Sep 17 00:00:00 2001
From: mkelvers <mikkelelvers@outlook.com>
Date: Sun, 19 Apr 2026 21:14:17 +0200
Subject: [PATCH] docs: add local structure notes

---
 .gitignore       |  1 +
 README.md        | 10 ++++++----
 cmd/README.md    | 11 +++++++++++
 scripts/check.sh |  8 ++++++++
 4 files changed, 26 insertions(+), 4 deletions(-)
 create mode 100644 cmd/README.md
 create mode 100755 scripts/check.sh

diff --git a/.gitignore b/.gitignore
index d6c0c56..86317e9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,6 +33,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+**/.DS_Store
 
 # Go
 main_server
diff --git a/README.md b/README.md
index d29a44f..88b69de 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,8 @@ Instead of treating the repository as one flat service, the codebase is organize
 | `static` | Source CSS, TypeScript, and static assets |
 | `dist` | Built frontend assets served at `/dist/*` |
 
+`cmd/` structure notes are documented in `cmd/README.md`.
+
 ## Runtime behavior
 
 On startup, the server opens SQLite using `DATABASE_FILE` (defaulting to `mal.db`), runs migrations automatically, initializes core services, starts the background worker, and then serves HTTP traffic on `PORT` (defaulting to `3000`). A request enters the router, passes through global middleware for origin and auth boundaries, reaches a feature handler, and then resolves through service logic that combines database access with upstream data where needed before rendering HTML.
@@ -89,8 +91,8 @@ For local development, install Go `1.24+`, Bun, and the `templ` CLI, then genera
 go install github.com/a-h/templ/cmd/templ@latest
 bun install
 templ generate
-bun run build:assets
-go run ./cmd/server
+./scripts/check.sh
+PLAYBACK_PROXY_SECRET="your-32+char-secret" go run ./cmd/server
 ```
 
 The frontend pipeline uses a single source stylesheet (`static/style.css`) and TypeScript sources in `static/*.ts`, then emits build artifacts into `dist/` (`dist/tailwind.css` and `dist/*.js`) for serving.
@@ -132,10 +134,10 @@ docker run --rm \
 
 Migrations run at startup, so schema changes are applied automatically before the server begins accepting traffic. Migration history includes the initial auth and watchlist schema, anime metadata expansion, relation tracking, Jikan cache persistence, indexing updates, and retry-queue support for failed fetches.
 
-Current automated tests are unit-focused and cover watchlist behavior, relation helpers, auth middleware boundaries, and watch-order parsing. Run the full test suite with:
+Current automated tests are unit-focused and cover watchlist behavior, relation helpers, auth middleware boundaries, and watch-order parsing. Run the full local validation suite with:
 
 ```bash
-go test ./...
+./scripts/check.sh
 ```
 
 There is currently no CI workflow in this repository, so validation is local.
diff --git a/cmd/README.md b/cmd/README.md
new file mode 100644
index 0000000..7e5788a
--- /dev/null
+++ b/cmd/README.md
@@ -0,0 +1,11 @@
+# cmd layout
+
+This repository keeps executable entrypoints under `cmd/`.
+
+- `cmd/server`: main web process (`go run ./cmd/server`)
+
+Why this exists:
+
+- Keeps the repository root focused on project metadata (`README.md`, `go.mod`, `Dockerfile`, etc)
+- Scales cleanly if more binaries are added later (for example: `cmd/migrate`, `cmd/admin`, `cmd/worker`)
+- Matches common Go repository conventions for multi-binary or growing services
diff --git a/scripts/check.sh b/scripts/check.sh
new file mode 100755
index 0000000..51866be
--- /dev/null
+++ b/scripts/check.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+go test ./...
+go vet ./...
+bun run typecheck
+bun run build:assets