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/
│       ├── artery/        # Amar-specific (merged into output)
│       │   └── shunts/amar/
│       ├── atlas/         # Amar-specific books
│       │   └── books/
│       ├── station/       # Amar-specific tools config
│       │   └── tools/datagen/
│       ├── link/          # Bridge to managed app
│       ├── soleprint/     # Soleprint docker config
│       ├── databrowse/
│       ├── tester/
│       ├── monitors/
│       └── models/
│
├── ctrl/                  # Build/run scripts
│
└── 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 (merged into output):

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

Build & Run

# Build
python build.py                    # -> gen/standalone/
python build.py --cfg amar         # -> gen/amar/
python build.py --all              # -> all rooms

# Run bare-metal
cd gen/standalone && python run.py

# Using ctrl scripts
./ctrl/build.sh [room]
./ctrl/start.sh [room] [-d]
./ctrl/stop.sh [room]

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:
# cfg/newroom/artery/shunts/...
# cfg/newroom/atlas/books/...
# cfg/newroom/station/tools/...

python build.py --cfg 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/