# VerIQ — Product & Tech Specification

Version: 0.1 (2026-10-13)
Owner: Eugene (architecture decisions) · Navi (implementation)

## 1. Product vision

A public IQ test where the result is a **verifiable credential**, not a screenshot.

Market gap: every existing test (paid or free) outputs an image/PDF that anyone can forge. No mainstream test binds the result to a real identity with cryptographic proof. VerIQ does.

Target audience: people who argue about IQ on X/Twitter, Reddit, Telegram; communities (Mensa-adjacent, dev communities); HR-adjacent curiosity segment.

## 2. Core user flows

### 2.1 Anonymous flow (default)
1. Land on `/` → "Start test" (no registration required).
2. Test: 30–40 tasks, ascending difficulty, per-section timer, total ~25 min.
3. Result page: IQ score, percentile, breakdown by category.
4. "Claim & verify" → sign-in with X or Instagram → result bound to identity → permanent link `/v/<id>`.

### 2.2 Verification flow (third party)
1. Someone shares `/v/<id>` link.
2. Page shows: score, percentile, date, bound identity (avatar + handle), signature status (valid/invalid), service public key fingerprint.
3. No login required. Page is shareable and indexable (OG tags).

### 2.3 Premium flow (phase 3)
- Free: score + percentile + basic breakdown.
- Premium (Telegram Stars / crypto): full report — category analysis, response-time profile, retake history, printable certificate (signed PDF).

## 3. Scoring model

- Raw score: sum of task weights answered correctly (weights by difficulty tier).
- Normalization: IQ = 100 + 15 × z, where z = (raw − mean) / σ of the current calibration population.
- Until N ≥ 500 real completions: label "preliminary calibration" on result page.
- Anti-cheat: one attempt per identity per 30 days for verified results; response-time sanity checks (too fast = flagged); task order randomized from seeded bank.

## 4. Question bank

- 40+ original tasks across 4 categories:
  - numeric/symbolic sequences
  - logical matrices (original, NOT Raven copies)
  - verbal logic
  - spatial reasoning (SVG figures)
- Each task: `id`, `category`, `difficulty` (1–5), `weight`, `time_limit_s`, `prompt`, `choices[]`, `answer_index`, `explanation`.
- Stored as JSON in `content/questions.json`; versioned — result records bank version used.

## 5. Verification & signing

- Service holds Ed25519 keypair. Private key: env var / secret file on VPS (never in repo). Public key: served at `/.well-known/veriq-pubkey.txt` and shown on verify page.
- Signed payload (canonical JSON): `{result_id, score, percentile, bank_version, identity (optional), completed_at}`.
- Signature: base64 Ed25519 over the canonical payload; stored with result.
- Verify page re-checks signature server-side on every view (and shows "signature valid").
- Result IDs: 8-char base62, URL-safe, collision-checked.

## 6. Identity binding (phase 2)

- **X (Twitter) OAuth 2.0 PKCE**: scope `users.read` + `tweet.read`. We store: `x_id`, `@handle`, `avatar_url`, `name`. No posting permissions.
- **Instagram**: Facebook Login for Instagram (business/creator accounts) — store `ig_id`, `username`, `avatar`. Fallback if unavailable: "link your Instagram" via manual handle + confirmation post caption code (phase 2.5).
- Binding is optional: anonymous results get verify links too, but without identity badge.
- One identity can hold multiple results (history), latest is primary.

## 7. Tech stack & architecture

- **Backend:** FastAPI, Uvicorn, SQLite (WAL mode). Single VPS, single process + systemd. No external DB.
- **Frontend:** vanilla HTML/CSS/JS, no build step, mobile-first, dark brutalist theme (fits brand).
- **Signing:** `cryptography` (PyCA) — Ed25519.
- **Rate limiting:** per-IP token bucket (slowapi or hand-rolled).
- **Analytics:** self-hosted, minimal — events table (start, finish, share, claim), no third-party trackers.
- **Deploy:** systemd unit + nginx reverse proxy + certbot. `scripts/deploy.sh`.

## 8. Non-goals (v1)

- No native mobile apps.
- No gnexus-auth integration (standalone by owner's decision).
- No multi-language UI (EN first, RU second — phase 2).
- No adaptive item-response theory (IRT) — fixed weighted scoring for v1.

## 9. Milestones

| # | Milestone | Owner | Status |
|---|-----------|-------|--------|
| M1 | Repo + spec + skeleton | Navi | in progress |
| M2 | Question bank v1 (40 tasks) | Navi | pending |
| M3 | Test engine + scoring + result page | Navi | pending |
| M4 | Ed25519 signing + /v/<id> verify page | Navi | pending |
| M5 | X OAuth binding | Navi | pending (needs app registration by owner) |
| M6 | Instagram binding | Navi | pending |
| M7 | Deploy to VPS + domain | Navi + Eugene | blocked until VPS ready (2026-10-14) |
| M8 | OG cards + share buttons + analytics | Navi | pending |
| M9 | Premium report + payments | Navi | phase 3 |

## 10. Risks

- **Calibration validity:** mitigated by honest "preliminary" label + iterative norming.
- **Legal (test content):** all original items; no Raven/Mensa copies.
- **OAuth approval delays:** X developer account review can take days — owner registers apps; anonymous flow works without it.
- **Abuse (bot farming of high scores):** rate limits, response-time sanity, one verified attempt / 30 days / identity.