trak
StudioNEW
Registry Documentation

Community Registry & Publishing Guide

Everything you need to know about publishing your own learning tracks to the Trak Registry. No accounts, no servers — just a GitHub Pull Request.

How the CLI resolves blueprints

When you run trak init, the CLI determines whether you want an official or community track based on the path format, then fetches the JSON blueprint from the registry via a raw GitHub URL.

You typeTypeFile resolved in registry
trak init lang/goOfficialtemplates/lang/go.json
trak init trak/lang/goOfficial (explicit)templates/lang/go.json
trak init alice/db/postgresCommunityusers/alice/db/postgres.json
trak init alice/db/postgres@v1.1.0Community (versioned)users/alice/db/postgres@v1.1.0.json

Allowed Track Categories (5 Canonical Pillars)

Strict CI Validation

Every blueprint submitted to Trak Registry must belong to one of the 5 canonical engineering categories below. The CLI uses this category to resolve runtimes, parse commands, and route exercises. Any PR using custom or unlisted categories (e.g. web, frontend, misc) will fail GitHub Actions CI Pass 1.

langProgramming Languages
users/<you>/lang/<tool>.json

Syntax, memory management, concurrency models, compiler flags, and native standard libraries.

Examples:gorustpythontypescriptjavascriptccppzigjava
Native Compiler Testing (trak verify)
osOperating Systems & Kernel
users/<you>/os/<tool>.json

Kernel internals, POSIX syscalls, process scheduling, eBPF, memory paging, and Linux systems administration.

Examples:linuxkernelfreebsdunix
Milestone Laboratories (trak done <module>)
cloudCloud & Distributed Systems
users/<you>/cloud/<tool>.json

Cloud infrastructure architectures, distributed consensus, microservices, messaging, and cloud networking.

Examples:awsgcpazuredistributed-systems
Milestone Laboratories (trak done <module>)
dbDatabases & Storage Internals
users/<you>/db/<tool>.json

Storage engines, Write-Ahead Logging (WAL), B-Trees/LSM-Trees, indexing, crash recovery, and ACID isolation.

Examples:postgresredismysqlsqlitemongodb
Milestone Laboratories (trak done <module>)
toolDevOps & Developer Tooling
users/<you>/tool/<tool>.json

Container engines, CI/CD orchestration, Infrastructure as Code, configuration managers, and dev tools.

Examples:dockerkubernetesansiblegitterraform
Milestone Laboratories (trak done <module>)
Guideline for Contributors:

When creating a lang track, include runnable test harnesses (exercise_test.go, exercise_test.py, etc.) so users can run trak verify with their native compiler. For os, cloud, db, and tool tracks, focus on declarative config files (docker-compose.yml, playbooks, SQL scripts) and step-by-step architectural READMEs.

Publishing a community track

The entire publishing flow is a standard GitHub Pull Request. No accounts, API keys, or dashboards. Once your PR is merged, your track is instantly available to anyone via the CLI.

1
Create your blueprint

Use Blueprint Studio to visually scaffold directories and files, or write the JSON by hand. Export a valid AST JSON file when done.

2
Fork & commit

Fork ndk123-web/trak-registry on GitHub. Place your file at:
users/<your-github-username>/<category>/<track-name>.json
For versioned releases: track-name@v1.1.0.json

3
Open a Pull Request

GitHub Actions automatically runs the CI validator on your PR. It checks your identity, file path, schema structure, and security rules. If everything passes, a maintainer merges it.

4
Your track is live

Once merged, anyone can immediately run:
$ trak init <your-username>/<category>/<track-name>

CI validation rules

Every Pull Request triggers a GitHub Actions workflow that runs scripts/validate.go. It performs two passes: a security check on changed files, then a schema validation on every blueprint in the repo.

Pass 1 — PR author & file securitySecurity Check
•
Cannot touch CI infrastructure — Files under scripts/ or .github/ are blocked.
•
Cannot modify official templates — Anything under templates/ is reserved for the repo owner.
•
Cannot modify another user's namespace — You can only touch users/<your-username>/. If your GitHub username is alice, you can't modify users/bob/.
•
Cannot modify root repository files — Files like README.md or LICENSE at the repo root are blocked.
•
Path must be exactly 4 segments — users/<you>/<category>/<file>.json — no deeper, no shallower.
•
Must use a valid category — Allowed: lang, os, cloud, db, tool.
•
File must end in .json — Only .json files are accepted inside user namespaces.
Pass 2 — Blueprint schema & safetyAST Validation
•
Valid JSON with required fields — id, name, version, and root are mandatory.
•
Root must be a directory node — root.type must be "directory" with a non-empty name.
•
Max file size: 5 MB — Blueprint JSON files exceeding 5 MB are rejected.
•
No executable binaries — Nodes ending in .exe, .dll, .so, or .dylib are rejected.
•
No path traversal — Node names cannot contain /, \, :, null bytes, or be ...
•
Every node must have a valid type — Must be "file" or "directory". File nodes cannot have children.

The repo owner (ndk123-web) bypasses all Pass 1 security rules and can modify any file.

Multi-version releases

You can publish multiple versions of the same track side by side. Append @version to the filename. Useful for major upgrades, difficulty levels, or LTS releases.

File layout
users/alice/db/
├── postgres.json          # default (latest)
├── postgres@v1.1.0.json   # stable release
└── postgres@v2.0.0.json   # major upgrade
CLI usage
$ trak init alice/db/postgres→ resolves postgres.json (latest)
$ trak init alice/db/postgres@v1.1.0→ resolves postgres@v1.1.0.json

Blueprint schema specification

Blueprints are recursive file-system AST trees. Each node has a type of "file" or "directory", a name, and optionally content (for files) or children (for directories).

example-blueprint.json
{
  "id": "lang/go",
  "name": "Go (Golang) Comprehensive Mastery Track",
  "version": "1.2.0",
  "description": "Complete Go curriculum from basics to production concurrency",
  "root": {
    "name": "go-workspace",
    "type": "directory",
    "children": [
      {
        "name": "go.mod",
        "type": "file",
        "content": "module go-workspace\n\ngo 1.22\n"
      },
      {
        "name": "00-setup-and-prerequisites",
        "type": "directory",
        "children": [
          {
            "name": "README.md",
            "type": "file",
            "content": "# 00 - Setup & Toolchain\n..."
          }
        ]
      }
    ]
  }
}
FieldTypeRequiredDescription
idstringyesUnique identifier, e.g. "lang/go"
namestringyesHuman-readable track name
versionstringyesSemver string, e.g. "1.2.0"
descriptionstringnoShort summary of the curriculum
rootNodeyesRoot directory node of the AST tree

Frequently asked questions