Whyku

Inspiration

Sudoku apps can tell you which number to enter, but they don't always explain why that number belongs there. I wanted to build something that makes solving Sudoku a learning experience rather than simply filling in cells.

That idea led to Whyku, a Sudoku tutor designed to help players understand the logic behind each deduction without immediately revealing the answer.

What it does

Whyku provides a progressive, five-level hint system:

• Nudge: Get a gentle push in the right direction.
• Area: Identify where to focus.
• Technique: Understand the logical technique being used.
• Reasoning: Follow the deduction step by step.
• Reveal: See the answer when you're ready.

Instead of relying on an AI model to invent Sudoku logic, Whyku uses a deterministic solver to identify valid deductions. The interface highlights relevant cells and candidates so users can connect the explanation to the board.

How we built it

We built Whyku using React and Vite for the frontend and Python with FastAPI for the backend. The backend handles Sudoku analysis and deduction selection, while the frontend manages the interactive board and progressive hint experience.

A central design decision was to separate finding a valid deduction from explaining it. The solver determines what the board logically supports, while the explanation layer communicates that reasoning. AI-generated explanations use approved reasoning clauses, with a deterministic template fallback when the AI is unavailable.

We also implemented automated tests for the solver, API, frontend interactions, and hint progression to help ensure that explanations remain grounded in actual deductions.

Challenges we faced

One of the biggest challenges was making the hints genuinely educational rather than simply repeating the same answer in different words. We needed to distinguish between identifying a deduction and progressively explaining it, while ensuring the highlighted evidence matched the solver's result.

Integrating an AI explanation layer introduced another challenge: explanations needed to remain consistent with the underlying logic, even when an API request failed or timed out. We addressed this with validated explanation clauses and a template fallback.

We also learned that a repeated deduction is not necessarily a bug. If the board has not changed, a deterministic solver should return the same next deduction. The hint ladder should deepen the explanation, and a new deduction should be computed after the board changes.

What we learned

Building Whyku taught us the importance of separating correctness from presentation. AI can make an explanation easier to understand, but the underlying logic should remain independently verifiable.

We also learned to build incrementally, test each component, and prioritize predictable behavior over unnecessary complexity.

Our goal is simple: help people learn to solve Sudoku, not just finish it.

Built With

• fastapi
• gemini-api
• javascript
• pytest
• python
• react
• vite
• vitest