docs: add product overview and engineering documentation

Document architecture, security, deployment, and development for contributors.
2026-10-07 19:40:26 +03:30
parent 6a5d5bd6e8
commit 5b9b2a16e6
11 changed files with 746 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Development
+
+## Prerequisites
+
+- Docker + Compose
+- Go (aligned with the backend Dockerfile; currently 1.27-alpine)
+- Node 22+ / bun for the frontend (image builds use `npm ci`)
+- Optional: k3s, Helm 3/4, kubectl, ffmpeg (only to regenerate the sample video)
+
+## Local run (recommended)
+
+```bash
+cp .env.example .env
+# Fill POSTGRES_PASSWORD, REDIS_PASSWORD, RUSTFS_*, JWT_SECRET, ADMIN_PASSWORD
+./scripts/compose-dev.sh up -d --build
+```
+
+Equivalent:
+
+```bash
+docker compose -f deploy/compose/compose.yaml -f deploy/compose/compose.dev.yaml --env-file .env up -d --build
+```
+
+The root `docker-compose.yml` includes the same pair.
+
+For UI iteration without rebuilding the image, run `bun run dev` inside `frontend/` and keep `PUBLIC_URL` / `FRONTEND_ORIGINS` aligned; the standard path is still behind Traefik.
+
+## Code structure
+
+- Copy naming and patterns from sibling files; do not invent new top-level folders without agreement.
+- Backend tests use Go `testing`; frontend typechecks with `tsc`.
+- Frontend calls the API mainly via `http` / `@/lib/api`.
+
+## Tests
+
+```bash
+# With Postgres/Redis available (compose) and a correct REDIS_URL
+cd backend
+export GOTMPDIR="${GOTMPDIR:-$HOME/.cache/go-tmp}"
+go test ./internal/config/ -count=1
+go test ./internal/api/ -count=1
+# or filter:
+go test ./internal/api/ -count=1 -run 'TestPasswordRecovery|TestSessionCookie|TestAdminEvent'
+
+cd ../frontend
+bunx tsc --noEmit
+```
+
+Note: if Redis has a password, build `REDIS_URL=redis://:${REDIS_PASSWORD}@localhost:6379` from `.env`.
+
+## Seed and sample video
+
+- `SEED_CURRICULUM=true` seeds curriculum/events at startup.
+- `backend/media/sample.mp4` is tracked in git; the Docker image copies it; startup PutObjects if the key is missing.
+- Regenerate a corrupted file with `./scripts/regenerate-sample-mp4.sh` (needs ffmpeg; not a runtime dependency).
+
+## UI error contract
+
+- Empty list ≠ network error: show error UI + retry.
+- Mutations: `toUserError`.
+- Player: no infinite skeleton; explicit error state.
+
+## Fonts
+
+- Persian body: **Vazirmatn FD** (Persian digits)
+- Latin fields (password, username, captcha): regular Vazirmatn / `font-latin`