soleprint/CLAUDE.md

Soleprint - Development Control Room

What Is This?

Soleprint is a development workflow platform - a self-contained environment where you can run, test, and document everything in isolation. Born from the friction of working on small teams where testing required PRs, documentation was scattered, and quick API connectors took too long to set up.

Core idea: BDD -> Gherkin -> Backend/Frontend Tests, with reusable connectors and tools that work across projects.

Name: Soleprint - "Cada paso deja huella" / "Each step leaves a mark"

Project Structure

spr/
├── CLAUDE.md              # You are here
├── README.md              # User-facing docs
├── schema.json            # Source of truth for models
├── build.py               # Build tool
│
├── soleprint/             # Core framework (all systems inside)
│   ├── main.py            # Hub entry point
│   ├── run.py             # Bare-metal dev server
│   ├── index.html
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── dataloader/
│   │
│   ├── artery/            # Connectors
│   │   ├── veins/         # Real API connectors (jira, slack, google)
│   │   ├── shunts/        # Fake connectors for testing
│   │   ├── pulses/        # Composed: Vein + Room + Depot
│   │   └── depots/
│   │
│   ├── atlas/             # Documentation
│   │   ├── books/         # Documentation (soleprint-only)
│   │   ├── templates/
│   │   ├── depots/
│   │   └── static/
│   │
│   └── station/           # Tools & execution
│       ├── tools/         # modelgen, datagen, tester, sbwrapper
│       ├── monitors/      # databrowse
│       └── desks/
│
├── cfg/                   # Room configurations
│   ├── standalone/        # Base soleprint config
│   │   ├── config.json
│   │   ├── data/
│   │   └── soleprint/
│   │
│   └── amar/              # Amar room config
│       ├── config.json
│       ├── data/
│       ├── soleprint/     # Room overlay — merged over soleprint/ on build
│       │   ├── artery/    #   room shunts, pulses
│       │   │   └── shunts/amar/
│       │   ├── atlas/     #   room books
│       │   │   └── books/
│       │   ├── station/   #   room tool configs
│       │   │   └── tools/datagen/
│       │   └── nginx/
│       ├── ctrl/          # Room lifecycle scripts (copied into gen/<room>/)
│       ├── link/          # Bridge to managed app
│       └── amar/          # The managed app itself
│
├── ctrl/                  # Build/run scripts (see Build & Run)
│
└── gen/                   # Built instances (gitignored)
    ├── standalone/
    └── amar/

The Four Systems

System	Purpose	Tagline
Soleprint	Core coordinator	Cada paso deja huella
Artery	Connectors to external services	Todo lo vital
Atlas	Actionable documentation	Mapeando el recorrido
Station	Tools, environments, execution	Centro de control

Artery Hierarchy

Vein ──────► Pulse ──────► Plexus
│           │              │
│           │              └── Full app: backend + frontend + DB
│           │
│           └── Composed: Vein + Room + Depot
│
└── Stateless API connector

Shunt ─── Fake connector for testing

Room Configuration

Each room in cfg/ has:

• config.json - Framework branding/terminology
• data/ - Data files (veins.json, shunts.json, etc.)

Room-specific system configs live under cfg/<room>/soleprint/ and are merged over the core soleprint/ tree at build time:

• soleprint/artery/ - Room-specific shunts, pulses
• soleprint/atlas/ - Room-specific books
• soleprint/station/ - Room-specific tool configs (datagen generators, tester tests)

A room's own lifecycle scripts live in cfg/<room>/ctrl/ and land in gen/<room>/ctrl/ — that is what make start <room> dispatches to.

Build & Run

make is the front door — one target per ctrl/ script, with the subcommand as an argument (make cluster up, not make cluster-up). The logic lives in the scripts, never in the Makefile. make help lists every target.

make                          # = make help
make build [room|all|models]  # -> gen/<room>/   (default: standalone)
make start [room] [-d]        # dispatches to gen/<room>/ctrl/start.sh
make stop  [room]
make cluster [up|down|status] # the shared `spr` kind cluster
make component [list|sync|watch|publish|diff]
make deploy [--build|--sync-only]

Every script stays runnable on its own — the standalone rule holds:

python build.py --cfg amar         # -> gen/amar/
cd gen/standalone && python run.py # bare-metal
./ctrl/cluster.sh up               # still runs directly; rig builds the cluster
cd gen/<room> && ./ctrl/start.sh   # each room owns its lifecycle scripts

Adding a New Room

mkdir -p cfg/newroom/data
cp cfg/standalone/config.json cfg/newroom/
cp -r cfg/standalone/data/* cfg/newroom/data/

# Add room-specific configs as needed (note the soleprint/ overlay level):
# cfg/newroom/soleprint/artery/shunts/...
# cfg/newroom/soleprint/atlas/books/...
# cfg/newroom/soleprint/station/tools/datagen/<name>.py

make build newroom

Ports

Service	Port
Soleprint	12000

Tools

Tool	Purpose
modelgen	Generate models from config
datagen	Generate test data (uses faker)
tester	HTTP contract test runner
graphgen	Generate navigable model graphs
databrowse	SQL data browser

Shared UI (soleprint/common/ui)

Upstream copy of the soleprint-ui package. mpr/ui/framework and meetus/ui/framework are downstream copies synced by ctrl/spr.py — edit here, never there, or the next sync overwrites the change.

cd soleprint/common/ui
pnpm install && pnpm typecheck && pnpm test
pnpm build          # -> dist/soleprint-ui.js + dist/style.css

The theme ships with the bundle. Every component styles itself with var(--surface-0) and friends from src/tokens.css, so src/index.ts imports src/theme.css (tokens + base.css). A bundle without it renders broken, not merely unbranded. Retheme by overriding the variables in tokens.css; don't inline colours in components.

dist/ and node_modules/ are gitignored — the dist is an artifact a container boots, not source. To hand someone a running artifact without the sources:

python ctrl/spr.py publish soleprint-ui <dest> --dist   # bundle + manifest only

Tests

No test bodies are committed to core. soleprint/station/tools/tester/ ships the base class, runner and UI; tests belong to a room at cfg/<room>/soleprint/station/tools/tester/tests/.

Two rules, both in tester/tests/test_template.py:

1. One suite, any environment — a test states what the API promises, never who implements it or where it runs.
2. No helper framework tools — stdlib unittest + httpx. No pytest fixtures, no framework test client, no factories, no ORM or database access.

Django, where it appears, is an optional private DB editor via its admin — never the framework, and never something a test reaches into.

External Paths

What	Path
Pipelines	/home/mariano/wdir/ppl

Files Ignored

• gen/ - Regenerate with make build [room]
• dist/ - Build artifact; regenerate with pnpm build
• node_modules/
• fails/, def/ - Drafts
• __pycache__/, .venv/

Known Broken (found, not yet fixed)

• tester/tests/example/test_health.py imports pytest, which is neither a dependency nor allowed here — tests/README.md says stdlib unittest and httpx, no pytest. It fails to import, so python -m tester discover reports it as _FailedTest. It also duplicates test_template.py, which is the sanctioned example. Removing it is probably the fix; core ships no tests.
• Old vocabulary survives in prose — album, larder, ward, nest and pawprint still appear in READMEs, docs/, and this file's history. Live code is clean; the docs lag.

Fixed

• A real API key was tracked in station/tools/tester/.env. Untracked, .env added to .gitignore, .env.example added. The key is still in git history and must be rotated — untracking does not unpublish it.
• Client vocabulary is out of live code. atlas/main.py was written entirely as Album/larder/PAWPRINT_URL; databrowse docs described a larder/ the code stopped using; get-api-key.sh defaulted to the client's database name.
• Two dead back-links, found while renaming: atlas/main.py passed pawprint_url and artery/index.html read pawprint_url, while run.py passes soleprint_url. Neither "← Soleprint" link had ever rendered.
• atlas/main.py fetched /api/data/album; main.py serves /api/data/atlas. get_data() had been failing and returning empty lists.
• tester/tests/_dev/test_health.py imported a non-existent ..endpoints. The import was unused; removing it makes the module discoverable (2 tests).