Enterprise-Grade Math Olympiad Speed Laboratory & Integer Decomposition Cloud Arena
Engineered by Olympiad Edge • Authorized by Rayaan Tasnim • Version 3.4 (Obsidian Aurora)
[Overview] • [Architecture] • [Features] • [Math Shortcuts] • [ELO & Rules] • [15 Facilities] • [Setup]
PrimeFactor.app (Version 3.4 — Obsidian Aurora) is an ultra-fast, cloud-synchronized computational playground and high-throughput competitive arena engineered specifically for competitive mathematicians, Math Olympiad contenders, and quantitative speed-solvers. The platform executes sub-second prime factorization verifications under intense competitive pressure, backed by Firebase Authentication (Google OAuth 2.0) and a real-time Cloud Firestore persistence layer.
By uniting low-latency client-side algorithmic execution with an interactive hero gateway and strict server-enforced cloud synchronization, PrimeFactor.app bridges raw number-theoretic intuition with verified global competition. Whether warming up in the interactive 5-second hero challenge or climbing the rated ladder across devices, PrimeFactor.app acts as an elite training facility for global mathematics competitors.
PrimeFactor.app utilizes a cloud-backed hybrid architecture. Heavy computational routines—such as deterministic primality tests and cycle-finding factorizations—are offloaded directly to non-blocking browser Web Worker threads, while user identities, competitive ELO ratings, and match ledgers are persisted and verified in real time via Firebase Auth and Cloud Firestore.
┌─────────────────────────────────────────────────────────┐
│ Browser Client (React 18) │
└────────────────────────────┬────────────────────────────┘
│
┌───────────────────────────────┴───────────────────────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Web Worker Math Engine │ │ UI & Interactive Hero │
├─────────────────────────┤ ├─────────────────────────┤
│ - Miller-Rabin (Det.) │ │ - Tailwind CSS │
│ - Pollard's Rho │ │ - Framer Motion │
│ - Brent's Cycle Finding │ │ - GSAP + ScrollToPlugin │
│ - Zero-UI-Blocking │ │ - 5s Live Mini-Arena │
└────────────┬────────────┘ └────────────┬────────────┘
│ │
└───────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Firebase Cloud, Security & AI Integration │
├─────────────────────────────────────────────────────────┤
│ - Firebase Authentication (Google OAuth 2.0) │
│ - Cloud Firestore Real-Time Persistence & Ledger Sync │
│ - Server-Enforced firestore.rules (Anti-Tamper Shield) │
│ - @google/genai SDK (Adaptive Challenge Generation) │
└─────────────────────────────────────────────────────────┘
The landing viewport features a live, playable 5-second factorization sandbox paired with a real-time Cloud Ledger preview. Prospective competitors can test their mental decomposition speed against high-frequency millisecond timers with instant validation before stepping into the main arena.
- Guest vs. Competitor Protocol: Unauthenticated visitors can practice freely in unrated mode, whereas competitors signing in via Google OAuth 2.0 initialize at a verified 500 ELO baseline.
- Real-Time Cross-Device Sync: Automatically synchronizes ELO ratings, win streaks, range milestone medals, and complete match logs across desktop and mobile devices via Cloud Firestore.
- Deterministic Miller-Rabin Primality Testing: Eliminates probabilistic ambiguity across all supported integer ranges.
- Pollard's Rho & Brent's Cycle Detection: Optimized non-blocking Web Worker routines capable of decomposing large composites into prime factors within milliseconds.
- Interfaces natively with Google's GenAI SDK to generate adaptive, contextual mathematical challenge problems and instant strategy breakdowns tailored to competitor performance.
- 12-Tier Olympiad ELO Ladder: Ascend from Composite Apprentice (500 ELO) through 12 distinct competitive divisions up to Prime Grandmaster.
- Dual-Vault Medals & Insignias: Unlock 100 Range Milestone Medals and 100 Tactical Cognitive Insignias.
- Fade-to-Inspire UI Protocol: Unearned operational achievements and high-tier ranges are locked behind a 25% opacity grayscale filter, restoring full color saturation dynamically upon meeting mathematical benchmarks.
- Sudden Death Spin Wheel: Integrated with procedural Web Audio API ticking physics for high-tension random category selection.
- 5-Second Visual Scratchpad Overlay: Provides a low-latency digital canvas to pause time and sketch manual factor trees mid-round.
- Post-Match 10.0 Verification Ledger: Evaluates score efficiency, accuracy rate, lifeline economy, and solve time consumption on a fractional 10.0 scale.
Top-tier Math Olympiad competitors do not rely on brute-force trial division during speed rounds. PrimeFactor.app incorporates 3 foundational cognitive tactics designed to mentally factorize large composites in under 200ms.
For any base-10 integer
-
Decadic Stripping: If
$N \equiv 0 \pmod{10}$ , strip all trailing zeros by pulling factor pairs$(2 \times 5)^k$ . -
Even Parity: While
$N \equiv 0 \pmod 2$ , continuously extract$2$ until$N$ becomes odd. -
Modulo 5: If the terminal digit of
$N$ is$5$ , then$N \equiv 0 \pmod 5$ . Continuously extract$5$ until$N \not\equiv 0 \pmod 5$ .
Removing factors of
Using digital roots ("Casting Out Nines"), modular congruences allow instant detection of factors
-
Rule for 3:
$N \equiv S(N) \pmod 3$ . If$S(N) \in {3, 6, 9}$ , extract$3$ . -
Rule for 9:
$N \equiv S(N) \pmod 9$ . If$S(N) = 9$ , extract$9 = 3^2$ immediately.
Executing digit sum checks before setting up any trial divisions eliminates powers of
When an odd composite
- Calculate
$\lceil\sqrt{899}\rceil = 30$ . - Test
$a = 30$ :$$b^2 = a^2 - N = 30^2 - 899 = 900 - 899 = 1 = 1^2$$ - Since
$b = 1$ is an integer square, apply the algebraic identity:$$899 = (30 - 1)(30 + 1) = 29 \times 31$$
Both
🔽 Dropdown 1: Dynamic ELO Formula, Volatility (K), Velocity (V), High-Tier Dampener & Asymmetric Range Firewall
Rating Initialization & Core Formulas
-
Zero-Guest Strict Baseline: Guests practice in unrated mode; all authenticated Google OAuth 2.0 candidate profiles initialize strictly at a verified 500 ELO floor baseline (Composite Apprentice).
-
Rating Delta Equation:
$$\Delta R = K \times (\text{Net Accuracy%} - E) \times V$$ Where$E$ represents expected performance based on question difficulty versus current player ELO. -
Volatility Index (
$K$ ):$$K = 32 \times (1 + \log_{10}(\text{Streak} + 1))$$ Sustained correct streaks amplify$K$ , allowing fast upward mobility for skilled candidates. -
Velocity Index (
$V$ ): Scales dynamically up to$3.5\times$ for verified sub-second answers.
High-Tier Dampeners & Inactivity Penalties
-
High-Tier Dampener: For users with ratings
$R_{\text{user}} \ge 1800$ , positive ELO gains are dampened by a multiplier of$\frac{1800}{R_{\text{user}}}$ . Negative ELO losses remain 100% exposed to prevent rating inflation. - Inactivity Decay: Profiles inactive for more than 14 consecutive days incur an automatic penalty of -10 ELO per week.
Asymmetric Range Firewall
To prevent high-tier players from farming ELO on trivial integer ranges:
- If
$R_{\text{user}} \ge 1500$ and the candidate selects difficulty bounds below their rank threshold, the session automatically enters Unrated Practice Mode ($\Delta R = 0$ ).
🔽 Dropdown 2: In-Game Scoring Matrix, Tactical Lifelines Table & 3-Strike Disqualification
- Pure 1st-Attempt Clear: +10 pts
- Hint / Overtime 2nd-Chance Clear: +5 pts
- Standard Error / Skip: -5 pts (and adds 1 strike count)
Candidates may invoke tactical lifelines at a direct point/ELO cost:
| Tactical Lifeline Asset | Direct Point Cost | Additional Condition / Constraint |
|---|---|---|
| Pause Clock | -2 pts | Maximum 2 per session |
| Regenerate Question | -2 pts | Maximum 1 per session |
| Extend Clock (+30s) | -3 pts | Dampens session ELO gains by 2% |
| Eliminate Noise | -4 pts | Removes invalid keypads/inputs |
| Launch 5s Scratchpad | -5 pts | Pauses time for 5 seconds for visual math work |
| Voluntarily Exit | -5 pts | Forfeits active session match |
- 3-Strike Rule: Amassing 3 errors or skips within a single match triggers immediate session disqualification and a flat -10 point deduction.
🔽 Dropdown 3: Hardware Focus Anti-Cheat (Page Visibility API) & Server-Enforced Firestore Security Rules
- Window Visibility Tracking: Switching tabs, minimizing the browser window, or moving application focus out of the active arena screen is captured immediately via the Page Visibility API, triggering an instant warning strike and a -5 point deduction.
- Request External Access Bypass: Players may click "Request External Access Bypass" to purchase a strict 10-second exemption window at the cost of a -5 point tactical fee.
PrimeFactor.app protects competitive integrity by pairing Google OAuth 2.0 authentication with server-enforced Cloud Firestore Security Rules (request.auth.uid == userId), eliminating unauthorized writes and client-side score manipulation:
[ Match Completion / Profile Mutation Requested ]
│
▼
┌───────────────────┐
│ Google OAuth 2.0 │
│ & UID == userId? │
└─────────┬─────────┘
│
┌────────────┴────────────┐
▼ ▼
[ Allowed: Commit to Cloud ] [ Denied: PERMISSION_DENIED ]
- Google OAuth 2.0 Identity Gate: Unauthenticated guests operate strictly in ephemeral practice mode; only verified Google accounts can initialize a 500 ELO ledger, record match histories, or claim medals.
- Server-Enforced Ownership (
request.auth.uid == userId): Firestore Security Rules validate every incoming read/write operation at the database boundary so users can only mutate their ownusers/{userId}document. - Page Visibility Focus Enforcement: Any loss of viewport focus during live ranked play is intercepted by the hardware focus monitor and penalized before match results are committed to the cloud.
🔽 Dropdown 4: The 15 Core Platform Facilities Matrix (Upgraded services.html Hub)
PrimeFactor.app integrates 15 tightly-coupled facilities across services.html and the core arena, providing real-time feedback, cross-device cloud persistence, and post-match analytical scoring:
| # | Facility Name | System Description |
|---|---|---|
| 01 | Deterministic Prime Engine | Executes Miller-Rabin and Pollard's Rho factorization sub-routines on non-blocking Web Worker threads. |
| 02 | Dynamic ELO Calculator | Computes real-time rating updates from a verified 500 ELO baseline using velocity, difficulty, and streak multipliers. |
| 03 | Page Visibility Focus Monitor | Tracks browser focus and tab visibility events via Page Visibility API to detect window blur and penalize tab switching. |
| 04 | Cloud Security & Anti-Tamper Shield | Server-enforced Firestore Security Rules (request.auth.uid == userId) blocking client-side score tampering. |
| 05 | Fade-to-Inspire UI Matrix | Locks unearned range achievements and dual-vault badges behind a 25% opacity grayscale filter until unlocked. |
| 06 | Post-Match Verification Ledger | Generates a 4-category performance report (Score, Accuracy, Lifelines, Time) rated out of 10.0. |
| 07 | Tactical Lifeline Dispatcher | Manages point deductions, ELO dampeners, and per-session usage limits for in-game assistance assets. |
| 08 | Adaptive Clock System | Tracks millisecond solve times, enforces countdown bounds, and manages overtime penalties. |
| 09 | GenAI Problem Synthesizer | Interfaces with @google/genai to construct custom contextual challenge problems and strategy breakdowns. |
| 10 | Scratchpad Overlay Engine | Renders a lightweight, low-latency visual canvas for rapid mental factorization work. |
| 11 | Streak & Volatility Vector | Tracks consecutive correct solves to scale the dynamic volatility index ( |
| 12 | 12-Tier Rank Progression Index | Maps player ELO across 12 competitive divisions from Composite Apprentice (500 ELO) to Prime Grandmaster. |
| 13 | Cloud Onboarding Gate | Manages the Zero-Guest entry flow, transitioning visitors from the 5s hero mini-challenge into authenticated play. |
| 14 | Cloud Identity Portal | Authenticates competitors via Firebase Auth (Google OAuth 2.0) and manages active session identity state. |
| 15 | Cumulative Cloud Arrays | Real-time Cloud Firestore collections synchronizing ratings, dual-vault medals, streaks, and match logs across devices. |
Clone the repository and install all TypeScript, React, Vite, Firebase, and Google GenAI dependencies:
# Clone the official repository
git clone https://github.com/rayaantasnim/Prime-Factorization-Web.git
# Navigate into the project directory
cd Prime-Factorization-Web
# Install all dependencies (including firebase and @google/genai)
npm install
npm install firebaseConfigure your Firebase project credentials in src/firebase.ts and create a .env file in the root directory for your API keys:
# Google GenAI SDK Key
VITE_GENAI_API_KEY=your_google_genai_api_key_here
# Firebase Configuration (consumed by src/firebase.ts)
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
VITE_FIREBASE_APP_ID=your_firebase_app_id- In the Firebase Console, enable Google under Authentication → Sign-in method.
- Add
localhostand your GitHub Pages domain (rayaantasnim.github.io) to Authentication → Settings → Authorized domains. - Deploy your
firestore.rulesfile (request.auth.uid == userId) using the Firebase CLI:
# Install Firebase CLI globally if needed
npm install -g firebase-tools
# Authenticate and link your Firebase project
firebase login
firebase use --add
# Deploy server-enforced Cloud Firestore security rules
firebase deploy --only firestore:rulesLaunch the local Vite development server or compile and test the exact GitHub Pages production bundle locally:
# Start local Vite development server with HMR (http://localhost:5173)
npm run dev
# Build the production bundle for GitHub Pages
npm run build
# Preview and test the production build locally
npm run preview© Olympiad Edge. Authorized by Rayaan Tasnim. All rights reserved.
---Firebase / Firestore
firestore.rulesnow validates profile shape, makesuid/email/createdAtimmutable, forces a pristine 500-ELO baseline on create, and bounds every progression field per write (ELO ±250,total_matches+1, counters monotonic, ≤50 logs). Deploy withfirebase deploy --only firestore:rules.- Rules cannot prove a match was played honestly. For fully authoritative ratings, settle matches in a Cloud Function and deny client writes to progression fields.
js/firebase.js: transactional, idempotent (matchId) match commits; allow-listedupdateUserProfile; penalty-onlyapplyEloPenalty; deduplicated profile bootstrap; graceful popup-cancel / popup-blocked (redirect) handling; session data cleared on sign-out.- Restrict the Firebase API key by HTTP referrer and enable App Check (set
VITE_RECAPTCHA_SITE_KEY). Config can be overridden withVITE_FIREBASE_*(see.env.example).
Hero & motion (js/hero-fx.js, js/hero-shaders.js, css/hero-fx.css)
- WebGL prime-sieve shader + Three.js (2,3) torus-knot constellation (raw-WebGL fallback if Three.js fails to load, static image if WebGL is unavailable).
- GSAP + ScrollTrigger: intro timeline, parallax, heading reveals. Motion (Framer Motion engine): scroll progress, in-view springs, hover/press.
- Respects
prefers-reduced-motion; pauses off-screen / in background tabs; adaptive pixel ratio.
css/ux-core.css+js/ux-core.jsload last on every page: one dark canvas with a slow CSS aurora, a single glass-surface recipe, unified header/controls/focus states, calmer card hovers, and cross-page transitions (View Transitions API with a fade fallback).- UX patterns: scroll-progress bar, back-to-top, scroll reveals, toasts (
UX.toast(msg, 'success'|'error')), and a command palette (Ctrl/Cmd+K or/) to jump to any module. The timed exam page gets the theme only (no reveals, palette or shortcuts). - Hero: the shader measures the copy block and keeps the lattice calm behind it; the 3D knot sits at the edge, dimmed, with a text scrim for guaranteed contrast.
- Bugs fixed on the way:
profile.jsundefinedlastResult/ledger, header gear double-offset, invisible text on light-era buttons/banners,edu.htmlhorizontal scroll on phones.
- Invisible checkboxes / washed-out content (home → Cloud Profile & Settings, and 9 other home sections, exam arena): each section's absolutely-positioned dark backdrop layer painted over any sibling that wasn't itself positioned. Fixed globally in
css/ux-core.css(siblings lifted above the backdrop). - Signed-in users treated as guests on the result page (match never saved, "ELO Not Saved" banner):
result.jsrendered before Firebase restored the session. It now waits for auth. profile.js:compute64BitBackupHash/ENGINE_HMAC_SECRETwere never defined (diagnostics export threw, every import failed) — implemented;lastResult/ledgerundefined references fixed.notification-engine.js:timestamp.split is not a functioncrash for non-string timestamps.- Three malformed SVG icon paths (file icon on
edu.html, gear icon onprofile.html/result.html). - Earlier: triple-counted matches, auth race, header XSS, simulated-ELO persisting, header gear offset,
edu.htmlhorizontal scroll.
- Readability:
js/readability-guard.js+css/aurora-pro.csslift navy/slate text to WCAG AA on dark surfaces (palette unchanged). - Ranges: spring-physics 3D cards with cursor glow (
js/ranges-3d.js,css/ranges-3d.css), bento stats, 60/40 spotlight hero. - Responsive:
css/contract-media-query.css, extendedcss/result-media-query.css, global safety net inaurora-pro.css. - Firebase speed: persistent multi-tab Firestore cache, lazy auth popup resolver, instant cached-session header, parallel profile fetch, single-transaction match commit, preconnect hints,
firestore.indexes.json(deploy withfirebase deploy --only firestore:indexes).
| Layer | Files |
|---|---|
| WebGL (raw, zero-dependency) — hero cardioid "orrery", Ulam-spiral GPU primality, times-table envelopes, Sieve of Eratosthenes, digit-spark particles | js/pf-gl-core.js, js/pf-orrery.js, js/pf-observatory.js, js/pf-sparks.js |
Framer Motion (motion package; jsDelivr fallback) — spring reveals, 3D tilt, counters, decode kickers, prime-ruler HUD, number-curtain intro |
js/pf-motion.js, js/pf-motion-loader.js |
12-Tier Hierarchy Matrix — interactive ELO gauge, live tier readout, synced to profile.elo |
js/pf-ladder.js |
| UI theme — math-olympiad styling, crop marks, § numbering, container queries | css/math-ui.css |
| Responsive layer for all 18 pages (xs 320 → 4K, landscape, coarse pointer, contrast, print) | css/responsive-global.css |
Entry point: js/index-fx.js. Every layer degrades independently (no WebGL → inspector still works; no Motion → content is never hidden; prefers-reduced-motion → static).


