# OI Workforce Test Centre — clean handover (application 2.1.0)

Open **My testing** or **Question bank**, open a question, ask it in the OI, then attach screenshots, paste the OI reply or describe the result, select Pass/Failed/Blocked and click **Save result & evidence** — all on the same question card. No separate Record test popup or manual session setup is needed.

The OI name and Voice/Chat selection are simple defaults at the top. Testers never have to know a software build, version or environment. The server may supply these using optional OI_BUILD and OI_TEST_ENVIRONMENT settings. Missing details are recorded as Not recorded, never guessed. Sessions group automatically; after a context/release change or 30 minutes of inactivity, the next opened question starts a fresh session and pauses the earlier one.

Screenshots can be chosen, dragged or pasted. The application stores screenshots and comments; it does not automatically read or judge screenshot content. Technical notes, release matching and document references remain available behind the simple form.

For personal review, use **OI_Test_Centre_Personal_Preview_v2.html**. It saves only to the current browser. Use Back up preview before switching HTML files or clearing browser storage. To restore a v1 preview backup, use Restore backup in v2. Such backups are not PostgreSQL imports.

For cPanel: start with START_HERE.html and cpanel.env.example. The HTML preview can be served as a static file. The full shared application needs Node.js application hosting and compatible PostgreSQL access enabled by the hosting provider. Docker is not assumed on shared cPanel accounts. See docs/CPANEL.md.

---

# OI Workforce Test Centre — server package

**Start with `START_HERE.html`.** This is a self-hosted Next.js + React application with PostgreSQL (`pg`), not a static HTML file. It runs separately from OI Workforce. It does not require ChatGPT hosting, Cloudflare D1 or R2.

## For Cliff

1. Give the complete ZIP to Brijesh and the server administrator.
2. They configure your server address and database credentials, then start the application using the hosting provider’s supported method.
3. Sign in as the administrator and change your temporary password.
4. Upload 01 to 011, your rules and quick-answer reference files through **Documents**.
5. Open **Edit question** and link the correct uploaded documents. Codes can be anything; links use permanent database IDs.
6. Add John and other people through **People**. Each gets their own account and temporary password.
7. Testers use **Choose question → ask the OI → attach screenshot → choose result → save**.

There is no requirement to complete all 116 questions. A blank selection means any question is available, not that every question must be completed. Session start/pause/resume/finish timestamps come from the server. These are activity records, not timesheets.

## Install using Docker Compose

Requirements: Docker Engine with Compose v2, 2 GB+ RAM for the application build (4 GB recommended), persistent disk, and a domain with HTTPS for production. PostgreSQL 16 is included; a managed PostgreSQL 16+ instance is also supported.

```bash
cp .env.example .env
# Edit .env. Set one strong database password and your exact public APP_URL.
docker compose up -d --build
# Database migration and non-destructive question seeding run automatically.
docker compose run --rm migrate node scripts/create-admin.mjs
```

The last command asks for the initial administrator name, email and password. Use **cliff@hyphenconnect.ai** if this is your chosen administrator email. No default administrator or password is shipped. Command-line password entry is visible; use your server's secret manager with ADMIN_EMAIL, ADMIN_NAME and ADMIN_PASSWORD for unattended setup. Never commit these credentials.

For the included local setup use `APP_URL=http://localhost:3000` and visit http://localhost:3000. For production set APP_URL to the exact HTTPS address, configure the reverse proxy, then recreate the app container: `docker compose up -d app`. Do not use a different origin or port from APP_URL; writes are protected by an origin check. The app binds to localhost on the host; your reverse proxy forwards to 127.0.0.1:3000. An example is in `docs/nginx.conf.example`.

### What is in the package?

| Item | Purpose |
|---|---|
| `app/` | React screens and Next.js server API routes |
| `lib/` | PostgreSQL access, permissions, validation, workflow and reporting |
| `database/001_initial.sql` | Schema used by the migration command |
| `database/questions.json` | The 116 starter questions from the existing assessment bank |
| `database/oi_test_centre_complete.sql` | Alternative fresh-database schema plus question data for a database administrator |
| `scripts/` | Migration, seeding, initial admin creation and backup |
| `compose.yaml`, `Dockerfile` | Container build and startup |
| `.env.example` | Required server settings, without real credentials |
| `tests/` | Automated workflow checks using embedded PostgreSQL |
| `docs/` | Operations, API, acceptance checklist and validation record |

**Use one database setup route.** Docker runs migration + JSON seed automatically. The complete SQL file is an alternative for a fresh manually managed database; it also marks migration 001 as applied. Do not apply the schema twice.

## Without Docker

Use Node.js 22.13+ and PostgreSQL 16+. Set DATABASE_URL and APP_URL in your process environment (do not assume `.env` is automatically loaded by plain Node scripts). Then run:

```bash
npm ci
npm run db:migrate
npm run db:seed
npm run admin:create
npm run build
npm start
```

Use your service manager to restart the app and supply environment settings. `npm start` serves port 3000. With an external database, configure DATABASE_URL with your provider's verified TLS settings; never disable certificate verification. The Compose example uses a private Docker network for its bundled database.

## What is built

- Tester, Technical and Administrator accounts, password change, account disabling and password reset by administrator.
- Sessions start automatically when a question is opened. Tester identity and timestamps are automatic; no manual session setup is required.
- Draft notes saved after 1.5 seconds of inactivity. The result form stays on the question card; allow the draft-save confirmation before leaving it. Unsent edits during connection failure cannot be guaranteed saved. Screenshots must be reattached if a draft is reopened.
- Explicit Pass/Failed/Blocked/N/A choices with green/red/amber/neutral colours; no automatic Pass.
- Expected result alongside the question. Choosing Pass confirms the tester checked the actual outcome; evidence is still required for Pass.
- Up to five screenshots per attempt (PNG/JPEG/WebP, up to 5 MB each). Evidence references and discussion notes.
- Optional overall attempt cost, tokens, sources and duration, plus separate individual search measurements.
- Shared dashboard for technical/administrators; tester view limited to their own attempts and sessions.
- Unique tester comparisons, filtered by build, environment, channel, date and question version.
- Live document IDs, arbitrary codes, replacement history and reference snapshots on saved attempts.
- Technical ownership, impact, fix/build, linked retests and evidence consolidation. Only a passing retest on the stated fixed build resolves an issue.
- Change flags when an attempted question/document version differs from the current register.
- JSON export, server-side audit events, health check and complete PostgreSQL backup including file bytes.

## Boundaries

This is a delivery package. It has not been installed on your server. Your server administrator must configure credentials, HTTPS, backups and run the acceptance checklist. The current hosted Test Centre is not replaced by this ZIP.

The actual 01 to 011 files, private screenshots, existing hosted test results, user accounts and the full current set of quick answers are **not bundled**. The question bank is included; upload authoritative reference files before using it for acceptance decisions. Existing legacy reference notes are retained as notes, not treated as live document IDs. Uploading a file does not automatically read it, discover its section numbers, rewrite questions, or train OI Workforce.

Search measurements can be entered manually now. Automatic measurements require Brijesh to connect OI Workforce to the documented telemetry endpoint. No OI Workforce integration, email delivery, SSO or OI Pro ticket integration is claimed. The telemetry endpoint attaches measurements to a previously saved attempt using its run ID; the originating system must capture the real measurements and retain that correlation.

See `docs/OPERATIONS.md` for backups, role access, recovery and retention. See `docs/ACCEPTANCE.md` before giving live access to testers.
