EasySudoku

• 

  EasySudoku main interface

• 

  Sudoku puzzle recognized from an uploaded image.

• 

  Step-by-step solving guidance with a technical explanation.

Inspiration

Most Sudoku applications focus on revealing the final answer. EasySudoku was created for learners who want to understand the next logically justified move and improve their solving skills.

The goal is to provide a step-by-step tutor that combines the reliability of deterministic solving with clear, human-readable explanations.

What it does

EasySudoku allows users to upload a Sudoku image, load a demonstration puzzle, or enter the givens manually.

The application:

• detects and recognizes the Sudoku grid using local OpenCV and ONNX inference;
• allows users to review and correct OCR results before locking the puzzle;
• displays candidates for empty cells;
• recommends the next logically valid move;
• explains each deduction in Brief, Teaching, or Technical mode;
• supports both English and Simplified Chinese;
• records every deduction and supports history replay;
• restores the board, settings, history, and uploaded image after a refresh.

The final Sudoku decisions are produced by deterministic human-style rules and Z3 SMT verification. The language model does not guess puzzle answers.

How we built it

The frontend was built with Vue 3, TypeScript, Vite, Tailwind CSS, and vue-i18n. The backend uses FastAPI and exposes structured APIs for image upload, cell hints, next-step deduction, and full solving.

OpenCV handles grid detection, perspective correction, and cell extraction. A locally trained ONNX model recognizes printed digits. The reasoning pipeline first attempts human-readable techniques such as Hidden Single and Naked Pair, then uses Z3 and UNSAT Core analysis as a verification fallback.

Structured deduction data is returned to the frontend, including the rule type, target cell, result, difficulty, verification method, and candidate changes. This allows the same verified deduction to be presented at different explanation depths and in multiple languages.

Codex GPT-5.6 sol assisted with repository auditing, the Vue and FastAPI hardening work, responsive interface improvements, structured API adaptation, automated tests, Docker and CI configuration, and submission documentation. The product direction, trust model, architecture, feature scope, and final review decisions were made by the project author.

Challenges we faced

One challenge was separating OCR uncertainty from solver correctness. Recognized digits remain editable until the user confirms the initial grid, preventing an OCR mistake from silently becoming a solver assumption.

Another challenge was translating SMT results into explanations that are useful to learners. Instead of exposing raw constraints, the backend returns structured deduction information that the interface turns into concise, teaching-oriented, or technical explanations.

Maintaining consistent state across history navigation, bilingual content, image persistence, responsive layouts, and API failures also required careful testing.

Accomplishments that we're proud of

• A complete photo-to-deduction workflow without an external OCR service.
• Solver-verified explanations rather than unverified generated answers.
• A responsive bilingual interface for desktop and mobile devices.
• Replayable deduction history and browser session recovery.
• Structured backend responses instead of parsing language-specific text.
• Automated backend, API, frontend, Playwright, Docker, and CI verification.

What we learned

We learned that recognition, reasoning, and explanation should be treated as separate layers. OCR proposes the initial input, deterministic rules and Z3 establish correctness, and the user interface communicates the verified result.

We also learned that structured explanation data is much easier to test, translate, and maintain than complete explanation sentences generated inside the solver.

What's next for EasySudoku

Future work includes adding Pointing Pair, Box-Line Reduction, Naked Triple, Hidden Pair, and eventually X-Wing. We also plan to create a labeled real-photo OCR evaluation set, improve candidate-removal visualization, and support generation and playback of a complete deduction chain.

Category

Education

Built With

• fastapi
• opencv
• python
• tailwind
• typescript
• vue.js
• z3