Registry Architecture & Blueprint Spec

Decoupled Registry Specification

How Trak resolves and streams curriculum blueprints from GitHub without updating the CLI binary.

Decoupled Architecture

The CLI binary is lightweight and communicates with the public trak-registry repository over raw HTTPS endpoints. New templates are immediately available globally upon pushing to GitHub.

Deterministic Stamping

Every initialized workspace receives a stamped trak.json manifest recording the exact template ID, version tag, and UTC timestamp for reproducibility.

Template Schema (JSON AST)

Blueprints are represented as recursive file-system AST nodes with explicit type: "directory" | "file" and encoded UTF-8 contents.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "lang/go",
  "name": "Go (Golang)",
  "version": "1.2.0",
  "description": "Comprehensive Go fundamentals and concurrency",
  "root": {
    "name": "root",
    "type": "directory",
    "children": [
      {
        "name": "go.mod",
        "type": "file",
        "content": "module learn-go\n\ngo 1.22\n"
      },
      {
        "name": "00-setup-and-toolchain",
        "type": "directory",
        "children": [
          {
            "name": "README.md",
            "type": "file",
            "content": "# Module 00: Go Toolchain\n..."
          }
        ]
      }
    ]
  }
}

How to Contribute a New Track

Fork & Clone: Fork ndk123-web/trak-registry.

Create Blueprint JSON: Add your template under templates/<category>/<tool>.json.

Register in Catalog: Update registry.json with the track name, description, and version.

Submit Pull Request: Create a PR to the main branch!