How Poussée Works

Exercise Variety

Duolingo uses 8+ exercise formats to test knowledge from different angles. We apply the same principle. A single lesson may include:

• Interactive board challenges — find the best move on the board
• Multiple-choice quizzes — test conceptual understanding
• Find the blunder — identify which move is the mistake from a list
• Move ordering — arrange moves in the correct sequence
• Concept matching — pair chess terms with their definitions
• Rapid-fire drills — timed yes/no questions to build instinct

Testing the same concept in multiple ways builds deeper neural pathways than repeating the same format.

Crown Mastery Levels

Each lesson has 5 crown levels that require progressively higher performance:

Higher crown levels don't just repeat the same lesson — they transform it. At crown 3+, the system inserts review exercises from past mistakes. At crown 4+, hints are removed and difficulty increases. This is progressive overload applied to chess learning.

Lesson Categories

How Lessons Work

1. Step-by-step progression — Each lesson is a sequence of steps: text explanations, board positions, interactive challenges, and quizzes. A progress bar at the top shows how far you are.
2. Mentor-guided — A mentor bot appears in the corner, offering encouragement, hints, and personality-specific reactions. Their dialogue adapts to your performance.
3. Hearts are at stake — Wrong answers cost hearts. Run out and you must wait for hearts to refill (30 minutes each) or spend 50 gems for an instant refill.
4. Adaptive difficulty — At higher crown levels, lessons transform: quiz options are shuffled, review exercises from past mistakes are inserted mid-lesson, and hints are disabled.
5. XP & Crown rewards — Completing a lesson earns XP (with a bonus for perfect performance) and a crown level based on accuracy.
6. Spaced review — Steps you got wrong are added to your spaced repetition queue and resurface in your Daily Review.

Lesson Locking

Lessons within a category are sequential. You must earn at least 1 crown on a lesson before the next one unlocks. The first lesson in each category is always available. This prevents skipping fundamentals while still allowing you to explore different categories freely.

Puzzle Library Architecture

Puzzles are organized into shards — files grouped by rating bucket (400-2800, in 200-point increments) and tactical theme (30+ themes). When you need puzzles in a particular range, only the relevant shard is downloaded from our CDN.

Puzzle Rating (Glicko-2)

Your puzzle rating uses the Glicko-2 system (same as Lichess). Every puzzle has its own rating. When you solve one, both your rating and the puzzle's rating are adjusted. The system accounts for rating deviation (uncertainty) — your first 20 puzzles will see larger swings as it calibrates.

• Solve a puzzle rated higher than you → big rating gain
• Solve a puzzle rated lower → small gain
• Fail a puzzle rated lower → significant loss
• Rating deviation decreases as you solve more puzzles

Adaptive Puzzle Queue

When you enable Adaptive Mode, puzzles are selected by an algorithm that balances four priorities:

A difficulty oscillator adjusts in real-time: solve 2 in a row and the target rises +50; fail one and it drops -25. This keeps you in your zone of proximal development throughout the session.

Puzzle Themes

Every puzzle is tagged with one or more tactical themes. There are 30+ themes across these categories:

• Tactical — Fork, pin, skewer, double attack, discovered check, sacrifice, pawn fork, knight fork
• Checkmate — Back-rank, smothered, Arabian, quiet move, removing defender
• Positional — Deflection, decoy, zugzwang, interference, overloading, trapped piece, X-ray, zwischenzug
• Endgame — Basic endgame, promotion, king & pawn
• Special — Mate-in-1, mate-in-2, opening trap, Greek gift, windmill

Puzzle Modes

• Daily Puzzle — A new puzzle every day (sourced from Lichess). The same for everyone.
• Puzzle Rush — Solve as many as you can before time runs out. Sprint (3 min), Marathon (5 min), Survival (3 strikes).
• The Gauntlet — 7 daily puzzles themed by day of week (Fork Monday, Pin Tuesday, etc.).
• Puzzle Survival — Roguelike: each puzzle advances a floor. Rating increases ~50 per floor. 3 lives, choose perks every 10 floors.
• Puzzle Chains — 5 linked thematic puzzles with a narrative arc. 12+ chains available.
• Time Warp — Same difficulty puzzles with shrinking time limits (60s → 30s → 15s → 10s → 5s).
• Sacrifice or Safe — Judge whether a move is a brilliant sacrifice or a blunder.
• Puzzle Architect — Design your own puzzles and share them.
• Puzzle Audit — Rate and review community-submitted puzzles.

Hearts

Hearts are your "lives" for lessons and exercises. You start with 5 hearts. Every wrong answer costs 1 heart. When you run out:

• Wait — Hearts refill passively, 1 every 30 minutes
• Spend gems — Instant full refill for 50 gems
• Leave — Return to the lesson list and come back later

Hearts are global session state, not per-lesson. This matches Duolingo's model and creates real consequence for careless mistakes across your entire session.

XP & Levels

XP (experience points) track your cumulative effort. You earn XP from:

• Completing lessons (amount varies by lesson length)
• Perfect lesson bonus (+25 XP for zero mistakes)
• Daily review sessions (+5 XP per reviewed puzzle)

XP accumulates into levels (50+ levels total). Each level requires more XP than the last. Your level is a rough measure of how much time you've invested in learning.

Gems

Gems are Poussée's in-app currency. You earn gems from:

• Completing puzzles (varies by theme/difficulty)
• Finishing daily quests
• Gauntlet completion
• Review sessions (15 gems per session)
• Achievements

You spend gems on:

• Heart refills (50 gems)
• Streak freezes (25 gems)
• Board themes & app themes
• Cosmetic items in the Gem Shop

Streaks

Your streak counts consecutive days of activity. Any qualifying activity (solving a puzzle, completing a lesson, doing a review) extends your streak by one day.

• Streak Freeze — Protects your streak for one missed day. Costs 25 gems. Max 3 freezes stored at a time.
• Streak Celebrations — Milestone messages at 3, 7, 14, 30, 50, 100, and 365 days
• Streak display — Visible in the sidebar nav and on your profile

Daily Quests

Five quests refresh daily (UTC midnight). Each has a gem reward. Quest types include:

• Solve the daily puzzle
• Complete a lesson
• Solve N puzzles of a specific theme
• Win a bot game
• Complete a review session

Completing all 5 quests unlocks a bonus reward.

Achievements

Long-term goals organized by rarity tier:

• Common — Getting started milestones (first puzzle, first lesson)
• Rare — Theme mastery (solve 50 fork puzzles, beat 5 bots)
• Epic — Serious milestones (1000 puzzles, 100-day streak)
• Legendary — Extraordinary feats (all bots defeated, all lessons mastered)

Achievements award gems, titles, and cosmetic items.

Spaced Repetition

Poussée uses a modified SM-2 algorithm (the same algorithm behind Anki) to schedule reviews of puzzles you've gotten wrong:

The Daily Review page shows all puzzles due for review. It works like a mini-lesson: progress bar, hearts at stake, XP awarded. You can also review lesson steps you struggled with — not just puzzles.

Bot Personalities

Each bot has a unique identity: a name, avatar, emoji, play style (aggressive, defensive, tactical, positional), rating range, and dialogue set. Bots react emotionally to the game state — they taunt when ahead, panic when losing, and congratulate when you find a good move.

Bots are unlocked progressively. Beat one to unlock the next. The Climb mode structures this as a 10-floor ladder challenge.

Stockfish Engine

Bot play and analysis are powered by Stockfish 17 running as WebAssembly in your browser. Key technical details:

• Multi-threaded — Uses SharedArrayBuffer where available (routes with COEP/COOP headers)
• Configurable strength — Search depth and thinking time mapped to bot rating for realistic difficulty
• Runs locally — No server calls. Your moves never leave your device.
• Analysis mode — Full evaluation with move classification (best, good, inaccuracy, mistake, blunder)

Bot Mood System

During a game, each bot maintains an emotional state that evolves based on game events:

• Capturing their piece → frustration or surprise
• Putting them in check → panic or respect
• Blundering a piece → mockery or encouragement (personality-dependent)
• Winning → congratulations or "well played" depending on margin

This makes every bot game feel like a conversation, not just a calculation.

Opening Knowledge

The Opening Explorer contains a curated database of opening lines with ECO codes, variation trees, and trap warnings. The Opening Trainer lets you practice specific repertoire lines. Bots themselves follow openings consistent with their personality — aggressive bots play the Sicilian, positional bots play the Queen's Gambit.

Game Analysis

After any bot game, you can run a full analysis. Stockfish evaluates every move and classifies it:

• Best — The engine's top choice
• Good — A strong alternative
• Inaccuracy — Suboptimal but not punished immediately
• Mistake — Loses significant advantage
• Blunder — Loses material or the game

An accuracy percentage summarizes your overall play quality. You can step through the game move-by-move with engine evaluation at each position.

AI Coach

The AI coach provides plain-English explanations during puzzles and games:

• Move explanations — Why a move is good or bad, in words you understand
• Hints — Progressive hints that nudge without spoiling the answer
• Position summaries — "White is better because of the strong knight on d5 and weak dark squares around Black's king"
• Opponent move analysis — "Your opponent played Nf3 to develop the knight and prepare castling"

On iOS, the coach runs entirely on-device using Apple Foundation Models. On the web, it uses pre-built explanation templates. Your moves never leave your device.

PGN Import & Board Scanner

• Import PGN — Paste or upload a PGN file to replay and analyze any game
• Board Scanner — Capture a physical chess board position using your camera, or set up a position manually
• Replay Viewer — Step through recorded games with full analysis overlay

Player DNA

Your Player DNA is a radar chart of 8 chess dimensions, built from your puzzle and game data:

• Tactical Vision — Ability to spot forks, pins, skewers, and combinations
• Positional Sense — Understanding of pawn structure, piece placement, and long-term plans
• Opening Accuracy (White) — How well you play the opening as White
• Opening Accuracy (Black) — How well you play the opening as Black
• Middlegame Accuracy — Decision quality in complex middlegame positions
• Endgame Accuracy — Technical proficiency in endgame conversions
• Time Management — How efficiently you use your clock
• Blunder Rate — How often you make serious mistakes (lower is better)

The DNA is displayed as a radar chart on your profile. It updates after every game and puzzle session. Systems like the Adaptive Queue and Weakness Assassin use it to target your weakest areas.

Weekly Recap

Every week, you get a multi-card recap slideshow showing:

• Games played and win rate
• Puzzles solved and accuracy
• Rating change (up or down)
• Streak status
• Achievement unlocks
• A motivational message tailored to your progress

Themes & Customization

• Board Themes — Multiple color schemes for the chessboard (classic wood, midnight, coral, etc.)
• App Themes — Full app color customization (dark, light, and accent variations)
• Unlocking — Some themes are free, others are unlocked via achievements or the Gem Shop
• Preview — Try any theme before unlocking to see if you like it

Leaderboards

Multiple leaderboard dimensions so everyone can find something to compete on:

• Puzzle Rating — Highest Glicko-2 rating
• Duel Rating — Head-to-head competitive rating
• Theme-Specific — e.g., "Top Forkers," "Pin Masters"
• Longest Streak — Most consecutive days
• Achievement Hunters — Most achievements unlocked
• Gem Earners — Most gems earned (all time)

Filter by period: All Time, This Week, Today.

Tournaments

Create and join tournaments with configurable formats:

• Swiss — Multi-round, flexible player count, automatic pairing
• Round Robin — Everyone plays everyone
• Single Elimination — Win or go home
• Double Elimination — Two losses to eliminate

Time controls include Rapid (10 min), Blitz (5 min), and Bullet (1 min). Live standings update as results come in.

Friends & Profiles

• Search for friends by username
• View public profiles with stats, ratings, DNA, and game history
• Challenge friends to duels or tournament games
• See activity feed of what friends are doing

Content Ratings & Votes

Every puzzle and lesson can be liked/disliked and rated 1-5 stars. Ratings and votes are visible to everyone (no account needed to see them). You must be logged in to vote or rate. Counts update in real time via Supabase Realtime — you can see other people's votes appear live.

How Offline Works

Service Worker Caching Strategy

• Static assets (CSS, JS, fonts, images) — Cache-first. Served instantly from cache, updated in background.
• Navigation — Network-first with offline fallback. If the network is down, you see a cached version or the offline page.
• Stockfish WASM — Cached aggressively. The ~2MB engine binary is stored locally after first download.
• API requests (Supabase) — Network-only. These require connectivity. Changes made offline are queued.

PWA Installation

Poussée can be installed as a Progressive Web App on any platform:

• Desktop — Chrome/Edge: click the install icon in the address bar
• iOS Safari — Tap Share → Add to Home Screen
• Android Chrome — Tap the install banner or Menu → Add to Home Screen

Once installed, Poussée runs in a standalone window (no browser chrome), feels native, and works offline.

What Works Offline

Native Apps

For the best offline experience, use the native apps (iOS, macOS, Windows, Linux). They offer:

• Full offline play with no initial download needed
• Multi-threaded Stockfish (faster analysis)
• On-device AI coach (iOS 26+ via Apple Foundation Models)
• iCloud sync (iOS/macOS)
• Apple Watch companion app
• Haptic feedback, Siri Shortcuts, Live Activities

Local-First Architecture

All progression data is stored in your browser's localStorage first. This means:

• The app works without any account or internet connection
• Your data is yours — it lives on your device
• Server sync is optional and additive

Cloud Sync

When you sign in with your email (magic link, no password), your local data syncs to Supabase:

• On sign-in — All local data is pushed to the server, then server data is pulled and merged
• On page load — Any queued changes are drained, then latest server state is pulled
• Conflict resolution — Timestamp-based merge. Most recent change wins.

Sync Queue

If you make changes while offline (or before signing in), they're stored in a sync queue. When connectivity is restored and you're signed in, the queue is automatically drained — your offline progress is never lost.

Privacy

• No tracking cookies
• AI coach runs on-device (no move data sent to servers)
• Sentry crash reports have personal data scrubbed
• Analytics (PostHog) track feature usage, not personal data
• See our full Privacy Policy

Platforms

• Web — Any modern browser (Chrome, Firefox, Safari, Edge)
• iOS — iPhone and iPad
• macOS — Native app
• Windows — Native app
• Linux — Native app
• Apple Watch — Daily puzzle, streak, complications

Accessibility Features

• Keyboard navigation for all interactive elements
• ARIA labels on chess board squares (e.g., "a8 black king")
• Reduced motion support (prefers-reduced-motion)
• High contrast mode via app themes
• Sound effects with mute toggle
• Responsive design for all screen sizes

Browser Requirements

• Stockfish requires WebAssembly support (all modern browsers)
• Multi-threaded Stockfish requires SharedArrayBuffer (Chrome, Edge, Firefox with COEP/COOP headers)
• Service Worker required for offline caching
• localStorage required for progress persistence