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	BDD/playwright test runner
graphgen	Generate navigable model graphs
databrowse	SQL data browser

External Paths

What	Path
Pipelines	/home/mariano/wdir/ppl

Files Ignored

• gen/ - Regenerate with python build.py
• fails/, def/ - Drafts
• __pycache__/, .venv/