Algopia

A personal developer operating environment that continuously answers one question: "What should I work on next, and why?"

Algopia is a single-user learning tracker and AI mentor built around a core loop: learn a concept, attempt a problem, record what happened, understand the mistake, and get forced to revise it until it sticks. DSA (Data Structures & Algorithms) is the first domain; the data model is shaped so other skills can join later without a rewrite.

Status: Phase 1 — Foundation (auth, database, initial UI). Accounts work end to end (register → sign in → session refresh → sign out), the database schema and migrations are live, and the app shell + empty-state dashboard render on mobile and desktop in light and dark mode. DSA features begin in Phase 2.

What is Algopia?

Not a to-do list, not a chatbot wrapper, not a LeetCode stats page. Algopia is a system for one person — a CS student/developer — who practices DSA across LeetCode, Codeforces, GFG, and similar platforms, and wants:

• one honest place to log attempts and mistakes,
• a deterministic revision engine that forces spaced review of the things that actually went wrong,
• an AI mentor that pushes their thinking instead of solving problems for them,
• a dashboard that says what to do today and why — computed from their own data, not vanity metrics.

Core idea

Learning over gamification, and deterministic logic before AI.

• Revision scheduling, statistics, and "what's next" recommendations are computed with plain rules and SQL — an LLM is never the source of truth for state.
• The AI mentor is a hint-escalation state machine (nudge → concrete hint → concept → approach → pseudocode → solution) where the backend, not the model, gates how much help is revealed.
• Everything is user-scoped by design, mobile-first by design, and built to eventually wrap into an Android app via Capacitor without a rewrite.

Core learning loop

Learn a concept
   → Attempt a problem
   → Record the attempt (solved / failed / partial)
   → If failed: capture the mistake
   → Revision engine schedules it
   → Revise later → outcome recorded
   → Dashboard + recommendations surface: what's weak, what's due, what's next

Every feature in V1 exists to make one of these arrows real and reliable.

Current development stage

Phase 1 — Foundation (auth, database, initial UI). Authentication is implemented end to end (register, login, silent session refresh, logout; argon2 password hashing; rotating refresh tokens in an httpOnly cookie), the SQLAlchemy schema (users, sessions, user_preferences) is managed by Alembic with a full test suite against a real Postgres, and the frontend has an auth flow, responsive app shell (top bar / bottom tab bar), theme toggle (light/dark/system), and an empty-state dashboard. See STATUS.md for the living progress tracker.

Repository structure

algopia/
├── frontend/              # React SPA (Vite + TypeScript + Tailwind)
│   └── src/               # app/, pages/, components/, features/, api/, lib/, styles/
├── backend/               # FastAPI monolith
│   └── app/               # api/, core/, models/, schemas/, services/, repositories/, ai/
├── docs/                  # architecture notes and ADRs
├── scripts/               # one-off maintenance/dev scripts
├── .github/workflows/     # CI (lint, tests, build)
├── docker-compose.yml     # local PostgreSQL only (the app runs directly)
├── .env.example           # environment variable contract
├── PLAN.md                # product plan — the source of truth
├── ARCHITECTURE.md        # technical architecture
└── STATUS.md              # living progress tracker

Local development

docker compose up -d db    # local PostgreSQL (127.0.0.1:5432)

# Backend (http://localhost:8000, docs at /docs)
cd backend && python -m venv .venv && pip install -e ".[dev]"
alembic upgrade head
uvicorn app.main:app --reload

# Frontend (http://localhost:5173)
cd frontend && npm install && npm run dev

Planned technology stack

Layer	Choice
Frontend	React + TypeScript, Vite, React Router, TanStack Query, Zustand, React Hook Form + Zod, Tailwind CSS
Backend	Python + FastAPI, SQLAlchemy 2.x, Alembic, Pydantic
Database	PostgreSQL (managed — Neon preferred)
AI	Anthropic Claude API (server-side only, hint-escalation mentor)
PWA	Workbox via Vite PWA plugin (Phase 8)
Android	Capacitor wrapper (after the web product is validated)
Hosting	Static host for frontend, app host for backend, managed Postgres — ~$0/month at V1 scale
CI/observability	GitHub Actions, Sentry

Architecture overview

One React SPA, one FastAPI monolith, one PostgreSQL database. No microservices, no message queues, no caching tier in V1.

Frontend (React SPA)  ⇄  Backend (FastAPI)  →  PostgreSQL
                              └──→  AI mentor (external LLM provider, server-side only)

• The backend owns all deterministic logic: revision scheduling, derived problem status, recommendations, analytics.
• The frontend never talks to the LLM provider directly.
• Later stages: installable PWA with offline reads → Capacitor Android app reusing ~100% of the frontend.

See ARCHITECTURE.md for the full technical structure.

Planned features

Labels reflect the current stage: Planned (designed, not built) / In Progress / Implemented. Nothing is implemented yet.

V1 (MVP)

• Email/password auth (JWT access token + httpOnly refresh cookie) — implemented
• DSA problem tracker (statuses, topics, patterns, attempts)
• Structured mistake journal tied to failed attempts
• Deterministic revision engine with a daily queue
• Dashboard: "what should I do today"
• Basic analytics (success rate by topic/pattern, revision performance, activity)
• Simple goals (target + progress + deadline)
• AI Mentor in hint-escalation mode for DSA problems
• Light / Dark / System themes — implemented (client-side, sync later)
• Responsive mobile-first layout (mobile / tablet / desktop) — implemented (shell)
• Settings (profile, theme, account deletion)

Post-V1 — Planned

• PWA (installable, offline read access)
• Google OAuth
• Projects module
• Deeper analytics (consistency heatmap, pattern-level trends)
• Web push notifications for due revisions
• Generic learning system UI for non-DSA skills
• GitHub integration (repos, languages, commit activity — no vanity metrics)

Explicitly out of scope for the foreseeable future

• Multi-tenant/team accounts, real-time collaboration, gamification (badges/XP/leaderboards)
• React Native/Expo rewrite, SM-2-style spaced repetition, CRDT offline sync
• An in-house code judge — Algopia tracks problems solved on external platforms, it doesn't run code

Mobile strategy

Mobile is a first-class platform, not an afterthought:

1. Responsive web built mobile-first (bottom tab bar on phones, top bar on desktop) — the V1 product.
2. PWA (Phase 8): installable, offline reads of problems/notes/revision queue.
3. Capacitor Android app only after the web product is validated — reusing the same React codebase, not a second frontend.

Constraints that keep the Android path cheap (storage/config abstractions, no browser-only assumptions) are enforced from day one. See ARCHITECTURE.md.

Development status

• Phase 0: repository scaffolding — done (frontend/backend skeletons, Docker, CI, env templates).
• Phase 1 (now): foundation — auth, database schema + migrations, initial UI shell, design system base.
• Phases 2–9: DSA core → revision engine → dashboard → AI mentor → goals/projects → analytics → PWA & Android prep → production hardening.

Full phase breakdown: PLAN.md. Current status: STATUS.md.

Documentation

Document	What it is
PLAN.md	Master plan — product vision, MVP boundaries, phases, acceptance criteria. The source of truth.
ARCHITECTURE.md	Technical structure — how the system is built and how its parts communicate.
STATUS.md	Living progress tracker — what is done, what is next.

License

Not yet determined.