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/kind-up.sh                  # still works directly
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/_dev/test_health.py imports ..endpoints, which does not exist in core — the module is unimportable.
• Client leaks remain in station/monitors/databrowse/ (README + index.html) and atlas/main.py (PAWPRINT_URL, role labels). Core should carry no client vocabulary; it belongs in cfg/<room>/.