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

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.