Architecture

Architecture Overview

How the TLD platform is built — from CLI to API to Docker to validator.

System diagram

Component	Language	Role
CLI (agent)	Go	User-facing tool — runs commands, manages labs, calls API
Backend	Python / FastAPI	REST API — auth, progress, lab metadata, scoring
Frontend	Next.js / React	Web dashboard — progress tracking, lab browser, profile
Database	PostgreSQL	Persistent storage — users, XP, lab completion history
Lab Engine	Docker + Bash	Spins up lab containers, runs validators
Landing Page	Next.js	Marketing site — you're looking at the docs app inside this

When you run tld lab start docker-fundamentals:

1
CLI authenticates
The CLI reads your local token and sends a request to the API with the lab ID.
2
API validates
The backend verifies the token, records that the lab was started, and returns lab metadata.
3
CLI pulls the lab
The CLI git-pulls or downloads the lab content to ~/.tld/labs/.
4
Lab engine starts containers
Docker Compose (or plain docker run) spins up the broken environment.
5
You work
The lab environment is running. You investigate and fix.
6
Validator runs
tld check executes validator.sh inside the lab environment and streams results to your terminal.
7
Results reported
On pass, the CLI reports completion to the API. XP is awarded.

Choice	Why
Go for the CLI	Single static binary, fast startup, no runtime dependencies, great cross-platform support
Python / FastAPI for the API	Rapid development, excellent async support, strong typing with Pydantic
Next.js for the frontend	React server components, file-based routing, great DX
PostgreSQL	Reliable, battle-tested, excellent with complex queries for progress tracking
Docker for labs	Reproducible, isolated, runs anywhere, standard tooling
Bash for validators	Zero dependencies, universally available, testable with standard tools