Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Praashh/buildml/llms.txt

Use this file to discover all available pages before exploring further.

Buildml is a full-stack AI/ML education platform that replaces passive reading with active implementation. Instead of watching tutorials or skimming textbooks, you solve curated coding challenges by writing real Python — implementing neural networks, NumPy operations, and ML algorithms from scratch. Every submission is executed against automated tests, so you get immediate, objective feedback on whether your understanding is correct.

​
What Problem Does Buildml Solve?

Most AI/ML learning resources stop at intuition. You understand what a softmax function does, but you have never had to differentiate through one yourself. Buildml closes that gap by presenting problems as coding tasks: given a specification and a test suite, implement the algorithm. The platform handles sandboxed execution, result storage, and leaderboard ranking — you focus entirely on the math and code.

​
Core Architecture

Buildml follows a clear request pipeline that separates the web layer from the compute layer, keeping the Next.js application fast and non-blocking even while user code is running. 
Next.js frontend  →  tRPC API  →  Upstash QStash (queue)
                                          ↓
                              FastAPI executor service
                                          ↓
                     Redis (run cache) / PostgreSQL (submit record)
                                          ↓
                     Client polls tRPC for status updates
  1. A user writes Python in the browser editor and clicks Run or Submit.
  2. The tRPC submission.run or submission.submit procedure enforces rate limits via Upstash Redis (run: 5 per 10 s, submit: 2 per 30 s).
  3. A job is published to an Upstash QStash async queue.
  4. QStash delivers the job to the Next.js webhook at api/webhooks/process-submission/.
  5. The webhook forwards the code to the FastAPI executor service at EXECUTOR_URL/execute.
  6. Run results are cached in Redis; Submit results are persisted to PostgreSQL with a final PASS, FAIL, or ERROR status.
  7. The browser polls a tRPC procedure until the result resolves.
The FastAPI executor service must be running and reachable at EXECUTOR_URL for any code execution to work. Without it, all submissions will time out. See the Quickstart for local setup and Self-Hosting for production deployment.

​
Tech Stack

LayerTechnologyVersion
Frontend frameworkNext.js (App Router)15
UI libraryReact19
Type safetyTypeScript5.8
StylingTailwind CSSv4
DatabasePostgreSQL—
ORMPrisma7
API layertRPC11
AuthenticationNextAuth.jsv5 (beta)
Cache / rate limitingUpstash Redis—
Async job queueUpstash QStash—
DeploymentVercel—

​
Key Concepts

Problem Sets are themed collections of problems (for example, NumPy Fundamentals or Neural Networks). Each Problem Set groups related challenges and is seeded via dedicated scripts (prisma/seed-numpy.ts, prisma/seed-nn.ts). Problems are individual coding challenges. Each problem ships with a description, a starter template, and a hidden test suite. Problems belong to exactly one Problem Set. Submissions are records produced when a user clicks Submit. A submission always carries one of four statuses:
StatusMeaning
PENDINGJob queued in QStash, not yet executed
PASSAll test cases passed
FAILOne or more test cases failed
ERRORExecution error (syntax, runtime, or timeout)
Run vs Submit — Run executes your code and streams the result directly to the browser from Redis. The result is ephemeral and does not count toward your score or leaderboard ranking. Submit records a permanent Submission row in PostgreSQL, updates your personal best, and feeds the leaderboard.

​
tRPC API Layer

The server API is built with tRPC v11. The root router at src/server/api/root.ts composes five sub-routers:
RouterPurpose
problemFetch individual problems and their metadata
problemSetList and retrieve problem set collections
submissionRun code (submission.run), submit solutions (submission.submit), and poll for results
userRead and update user profile data
feedbackSubmit platform feedback
Procedures are either publicProcedure (open, with timing middleware) or protectedProcedure (requires an authenticated session). All inputs are validated with Zod schemas. On the client, procedures are consumed as api.[router].[procedure].useQuery() or .useMutation().

​
Explore the Docs

Quickstart

Clone the repo, configure your environment, and have a working local instance running in five minutes.

Challenges

Learn how Problem Sets and Problems are structured, how tests are written, and how scoring works.

API Reference

Explore every tRPC procedure — from fetching problem sets to polling submission results.

Contributing

Set up a dev environment, follow the code-style guide, and open your first pull request.

Build docs developers (and LLMs) love

Get started for freeTalk to us