# Version 2 operating flow

Tester sessions start automatically on opening a question. No build/environment input is shown to testers. Optional OI_BUILD and OI_TEST_ENVIRONMENT server settings supply technical context; missing values remain Not recorded. Opening another question after 30 minutes without recorded activity starts a new session; context or release changes also create a new session. Earlier sessions are paused, not given an invented finish time.

A Pass with missing release metadata records the tester's outcome but does not automatically resolve a technical issue. Technical must configure/verify the relevant release and arrange a matching retest.

# Operations — simple ownership guide

## Access

- **Tester:** sees the shared question bank and reference documents; starts own sessions; sees own drafts, attempts, screenshots, searches and discussions. Can add notes and retest their visible cases. Cannot edit questions, documents, users or technical fixes.
- **Technical:** sees consolidated results and evidence, updates technical issues, consolidates duplicate issues, adds notes and can run tests. Does not manage users or authoritative questions/documents.
- **Administrator:** all technical permissions plus account allocation, disabling/resetting access, question editing and document uploads.

The application is one organisation per installation. It is not a multi-tenant service. Adding a tester grants access to the organisation's question bank and uploaded reference documents. Do not upload material this audience should not see. Disabled users lose sign-in access. Disabling an account does not delete their evidence. Temporary passwords must change at first sign-in. Password reset invalidates all sessions for that account. Forgotten passwords are reset by an administrator; no email reset service is included.

Sign-in cookies are HttpOnly, SameSite=Lax, expire after 12 hours and are Secure when APP_URL uses HTTPS. Origin checks protect browser writes. Failed sign-ins are limited to ten per email in fifteen minutes in PostgreSQL. Place the app behind a reverse proxy and add network-level rate limiting for internet deployments. No external access should bypass that proxy.

## Data and backup

PostgreSQL stores all records and uploaded file bytes. This keeps a backup consistent across evidence and metadata. Files are served through authenticated routes, not public disk paths. Document files download as attachments; screenshots can be viewed after access checks. Files have size limits, generated IDs and SHA-256 hashes. Uploaded documents are stored as reference copies; content is never executed. Signature/extension checks do not constitute antivirus scanning. Use your organisation's file-scanning policy before handling untrusted uploads.

Run `bash scripts/backup.sh` from the project root. Schedule it with your server's scheduler, copy the resulting dump to protected off-server storage, and monitor failures. No backup schedule is created merely by installing this package. Set retention and access according to your company requirements. Backups include screenshots and document contents.

Restore drill, on an isolated fresh database first:

```bash
# The destination database must be empty. Stop app writes first.
docker compose stop app
# For a fresh recovery database, stream the selected dump:
cat backups/YOUR_BACKUP.dump | docker compose exec -T db sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner --no-privileges'
# Check question counts, people, sessions, attempts and download an attachment.
docker compose up -d app
```

Do not restore over an existing populated database without a reviewed database recovery plan. Do not run `docker compose down -v`; it removes the persistent database volume. Use encrypted disks/backups and your server's access controls. Files in exports contain evidence metadata, not file bytes; JSON export is not a full backup.

## Server health and upgrades

`GET /api/health` returns 200 only when PostgreSQL and the question table are reachable. It exposes no credentials. Watch health status, disk usage, logs and backup age. Application errors do not print passwords or request payloads. Review the audit tab; exported activity is limited to the latest 1,000 entries visible to that role. The complete audit remains in the database and backups.

Before an upgrade: backup, run tests, build and verify on staging, apply forward-only migrations, and run smoke tests. Migration 001 is immutable after use. Add new numbered migrations and extend the migration list before future schema changes. This release has one migration. Pinned npm dependencies and package-lock.json are included; review vulnerability/patch updates as part of normal maintenance.

For a lost sole administrator, the server/DB owner can create another account with `npm run admin:create` using a new email. The command does not overwrite an existing account. Restore normal account control through People and retain an audit of the recovery outside the app.

## Reading the dashboard fairly

- Attempt pass rate uses Pass and Failed only; Blocked/N/A stay visible separately.
- Unique questions are different from total attempts and different from people.
- The per-question comparison uses the latest attempt per tester **within the selected filters**. Filter by a single build, channel, environment and question version for fair comparison.
- A reference-change flag highlights historical differences; it is a review signal. A fresh relevant passing test still needs human review before dismissing a change flag. It is deliberately not an automatic release gate.
- Cost tables keep currencies/types/scopes separate. They do not convert currencies. Missing costs are excluded, confirmed zero costs included. Search and attempt costs may overlap: never add them together.
- Session start/finish does not measure active labour or prove uninterrupted testing. Pause/resume events are preserved.
- Retest records never overwrite prior attempts. The technical team must mark the issue ready and name its fixed build before a passing linked retest resolves it. Consolidated issues retain original evidence and redirect to the shared issue.
