The Problem
Most learning tools reward watching, not understanding: progress bars fill up when you click "complete", AI summaries arrive without sources, and the tools you actually practise with (a terminal, a debugger) live somewhere else. I wanted one workspace where study material, a roadmap, deliberate practice and focus time sit together — and where progress has to be earned.
It also had to keep working without an internet connection or a paid API, because that is the reality of studying from Rajshahi on personal hardware.
The Approach
Omnidesk BD is a local-first workspace with a FastAPI backend and a React client:
- Ingestion engine — Python adapters parse PDF (PyMuPDF with a pypdf fallback), Markdown, plain text and YouTube transcripts into chunks, each with a SHA-256 hash so generated topics can point back to their source.
- Analyze → Preview → Approve — generated roadmaps are shown as a preview first; nothing is written to the database until the learner approves it.
- Visual DAG roadmap — topics are stored as a dependency graph in PostgreSQL and rendered with React Flow, so prerequisites are explicit.
- Competency gates — a topic is not "done" until it has been explained, implemented and debugged; completion timing is checked against realistic pacing.
- Practice in place — an embedded terminal (Xterm.js over a WebSocket PTY bridge) and a focus-timer HUD that survives page changes.
Architecture
The client talks to a FastAPI gateway (Pydantic v2) that applies per-user isolation before routing to the ingestion engine, the AI layer, the scheduler and the template registry. PostgreSQL 16 (SQLAlchemy 2 + Alembic migrations) holds the topic graph and provenance; Redis serves as cache and task broker, with an in-memory fallback queue when it is absent. The whole stack runs with Docker Compose, and a Tauri shell packages it as a desktop app.
Engineering Decisions & Trade-offs
Decision: A three-tier AI cascade — Gemini free tier → local Ollama model → offline heuristic
Context: Cloud models are capable but need a connection; small local models run offline but are limited on modest hardware.
Trade-off: More code paths to test, in exchange for a workspace that always produces something useful and never depends on a paid key. This mirrors the reasoning in my journal entry on moving to a hybrid local/cloud AI strategy.
Decision: Preview before persistence
Context: AI output can be wrong, and silently saving it would pollute the learner's roadmap.
Trade-off: One extra step for the user, in exchange for a database that only contains approved, source-linked content.
Decision: Graceful degradation over hard requirements
Context: Redis, a GPU or an internet connection may not be available on every machine.
Trade-off: Fallbacks (in-memory queue, heuristic generation) are slower or simpler, but the core workflow still runs.
Current State & Future Direction
Omnidesk BD is in active development as an open-source (MIT) project. The repository includes backend test suites for ingestion, the AI cascade, approval persistence and user isolation, and desktop builds are available as a pre-release. Next steps are hardening the desktop packaging, broadening the curriculum templates and measuring performance on low-end hardware before calling a stable release.