Initial commit

server/README.md

@@ -0,0 +1,50 @@
+# Queue API
+
+Go 1.26 modular-monolith API for the scenic queue system. It uses the standard
+library HTTP router, GORM, PostgreSQL, versioned embedded SQL migrations and
+database-backed sessions.
+
+## Local run
+
+1. Start PostgreSQL and create the database in `DATABASE_URL`.
+2. Copy `.env.example` to `.env`, replace both cryptographic keys, and export
+   the variables. Keys must decode to exactly 32 random bytes.
+3. Run `go run ./cmd/api`. With `MIGRATE_ON_START=true`, embedded migrations run
+   under a PostgreSQL advisory lock.
+4. Seed the local demo users, projects, queues, batches, devices and audit data with:
+
+   ```sh
+   ADMIN_PASSWORD='replace-me' go run ./cmd/seed
+   ```
+
+   The command is repeatable and prints the demo display and visitor paths. It
+   resets only the `DEMO`, `RAFT` and `CABLE` projects. Default users are the
+   protected `xqkwljtadmin` account and `staff`; override the staff credential
+   and primary-project values with
+   `ADMIN_USERNAME`, `STAFF_USERNAME`, `ADMIN_PASSWORD`, `PROJECT_CODE` and
+   `PROJECT_NAME`.
+
+For a production release, run `go run ./cmd/migrate` as a separate release Job
+with `MIGRATE_ON_START=false`, then rotate the protected administrator password
+with `SUPER_ADMIN_PASSWORD='...' go run ./cmd/bootstrap-admin`. Do not run the
+seed command against production.
+
+`POST /api/staff/projects/{id}/tickets` and
+`POST /api/staff/projects/{id}/call-next` require an `Idempotency-Key` header.
+If a phone already has active tickets, ticket creation returns
+`DUPLICATE_PHONE`; repeat with the same request body except
+`allow_duplicate: true` and a new idempotency key after the employee confirms.
+
+## Tests
+
+```sh
+go test ./...
+go vet ./...
+```
+
+From the repository root, `make test-db` creates a disposable PostgreSQL
+database and runs migration/maintenance integration tests.
+
+Unit tests cover ETA, phone normalization, authenticated encryption, token
+hashing and password hashing. PostgreSQL integration tests run through
+`make test-db` against a disposable database.