# 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.

`POST /api/public/status/search` is a temporary non-production operational-test
endpoint. It accepts `{ "phone": "..." }` and returns all current active
tickets associated with that phone. It is disabled when `APP_ENV=production`;
replace it with OTP or an external identity interface before formal launch.

## 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.