# PROJECT.md — Project Overview

> Working name pending — replace this title and any user-facing branding once a name is chosen. Everything else here holds regardless of name.

## What this is

A Georgia-focused platform where people take IQ, EQ, and general-knowledge quizzes (biology, geography, physics, etc.) and see how they compare to others in their city, occupation, age group, and country — not just a generic global score. Ships as a website (Laravel) plus Android/iOS apps (Flutter), evolving from a test site into a social/community product with clubs, leaderboards, and weekly competitions.

**Core differentiator: local comparison + community, not the test itself.** The global "online IQ test" market is crowded and low-trust. Being genuinely Georgian — language, content, and local leaderboards — is the actual moat. Don't let the product drift back toward "just another IQ test site."

## Framing commitments (don't relitigate without a real reason)

- **Entertainment framing, always.** Results are never presented as a clinical/diagnostic measurement. Score screens carry "for fun, not a clinical assessment" framing. Protects users — especially minors — and the business.
- **The headline score is always free.** Premium unlocks *depth* (subject breakdowns, history, filters, comparisons), never the basic number itself.
- **No claims of scientific certainty in aggregate stats.** "Smartest city" stats are self-selected-sample data, not population science. Never phrase as "our data shows X is smarter than Y." Never break stats down by ethnicity, even indirectly via region.
- **Public ranking is opt-in, not default.** Real name + photo + public leaderboard visibility default off, and gated to 18+ regardless of account age.

## Target users

Primarily Georgia-based, Georgian-speaking. Skews toward students/young adults given the comparison and club mechanics, but built for general adult use.

## Core features

### Testing
- IQ test, EQ test, subject quizzes: general knowledge, biology, geography, physics (extensible to more subjects)
- Weekly quizzes and challenges, rotated on a schedule
- Spaced-repetition resurfacing: failed questions reappear weeks later to check retention
- All scoring and timing validated server-side — never trust a client-reported score or elapsed time

### Results & certificates
- After finishing any test, the user gets a downloadable/shareable "certificate" — informal, clearly not an official credential, disclaimer included on the image itself
- Certificate and the Open Graph share-image (see Architecture) are the same underlying generator, not two separate systems

### Comparison & profiles
- Username by default; optional real name + photo, 18+ only
- "Verified" mode: stricter test conditions (time-boxed, tab-lock, possibly webcam-assisted later) earning its own badge — separates casual scores from scores that count competitively
- Leaderboards scoped by city, country, age group, occupation, time window (all-time / weekly)
- Progress tracking: per-subject skill breakdown over time, not one number

### Clubs
- Interest-based clubs (e.g. Android vs iOS, car brands) — public, joinable
- Custom clubs (friend groups, school groups) — private/invite-only by default
- Club creators get basic moderation tools: remove member, delete post, report
- Individual rank visibility inside a club is a setting separate from club membership — someone can participate without exposing their personal rank

### Competition
- Weekly club-vs-club battles with live score updates
- Aggregate public stats by city/age/occupation — explicitly framed as fun, never as scientific claims

### Economy
- Stars/points as an append-only ledger — never a mutable balance column (needed for audit/dispute resolution once real payments are involved)
- Earn via: weekly challenge wins, sponsor content ("learn about sponsor, answer questions"), purchase
- Spend via: premium features, custom club slots beyond free limit
- Sharing is not directly paid — incentivized sharing risks platform penalties. Growth relies on a genuinely shareable result card instead

### Monetization
- Ads (later stage, once there's real traffic)
- Premium subscription: full subject breakdowns, progress history, leaderboard filters, ad-free, verified mode, extra custom clubs
- Star purchases
- Sponsor deals: content modules + "presented by" clubs

## Localization

- Default language: Georgian
- Required at launch: English
- Architecture must support adding more languages later without a rebuild — never hardcode to two languages, in UI strings or quiz content
- **Development sequencing:** build and content-populate in English first. Every user-facing string still goes through the translation layer (never hardcoded), but Georgian *content* is filled in during a dedicated localization pass once the product is mostly feature-complete — see PHASES.md. Mark untranslated strings with a consistent TODO convention so nothing gets missed.
- **Admin panel is English-only, permanently** — it's an internal tool, not user-facing, so it's exempt from the translation requirement above.

## Frontend requirements

- Public-facing pages must be SEO-friendly: server-rendered (not a client-side-only SPA), proper meta tags, Open Graph/Twitter card support, sitemap, structured data where relevant. See ARCHITECTURE.md for specifics.
- City/occupation/age-group leaderboard pages double as long-tail SEO landing pages — treat them as real content pages, not just app screens.

## Theming

- Light and dark mode, light is default
- Registered users: preference persisted server-side, synced across devices
- Guests: local/device-level preference only, no account to persist to

## Compliance notes

- Georgia's Law on Personal Data Protection (2023, GDPR-aligned) applies. Minors under 16 need parental/legal-representative consent for any data processing; "special category" data — which scores like these plausibly are, or are close to — needs *written* parental consent for minors specifically, plus an ongoing duty to protect the minor's best interests.
- **v1 default: registration restricted to 16+.** Self-consent age under Georgian law; avoids needing a parental-consent flow before launch. Deliberate scope decision — see PHASES.md.
- Real name, photo, and public leaderboard display are 18+ only regardless of the registration floor.
- Not legal advice — confirm classification of score data with a local lawyer before scaling up.

## Payments

- Local rails: Keepz and BOG installment (see integration skills / existing notes)
- Prefer hosted/redirect flows where possible to minimize PCI/SAQ-A scope

## Explicitly out of scope for now

- Full scientific psychometric validity — this is entertainment content, not a clinical instrument
- Under-16 registration, until a consent flow exists
- Multi-currency or international payment rails