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
│
├── cfg/                   # Room configurations
│   ├── standalone/        # Base soleprint config
│   │   ├── config.json    # Framework branding/terminology
│   │   └── data/          # Data files (veins.json, shunts.json, etc.)
│   └── amar/              # AMAR room config
│       ├── config.json    # Can rebrand (e.g., "pawprint")
│       ├── data/          # Room-specific data files
│       ├── .env.example
│       ├── docker-compose.yml
│       ├── soleprint/     # Soleprint Docker config for this room
│       ├── databrowse/depot/
│       ├── tester/tests/
│       ├── monitors/
│       └── models/
│
├── ctrl/                  # Build/run scripts
│   ├── build.sh           # ./build.sh [room]
│   ├── start.sh           # ./start.sh [room] [-d]
│   ├── stop.sh            # ./stop.sh [room]
│   └── logs.sh            # ./logs.sh [room]
│
├── artery/                # Vital connections
│   ├── veins/             # Stateless API connectors (jira, slack, google)
│   ├── shunts/            # Fake connectors for testing
│   ├── pulses/            # Composed: Vein + Room + Depot
│   └── plexus/            # Full apps: backend + frontend + DB
│
├── atlas/                 # Documentation system
│   └── books/             # Soleprint docs (external via depots)
│
├── station/               # Tools & execution
│   ├── tools/             # modelgen, datagen, tester, sbwrapper
│   └── monitors/          # databrowse
│
├── soleprint/             # Core entry points (versioned)
│   ├── main.py
│   ├── run.py
│   ├── index.html
│   ├── requirements.txt
│   ├── Dockerfile
│   └── dataloader/
│
└── gen/                   # Built instances (gitignored)
    ├── standalone/        # python build.py dev
    └── amar/              # python build.py dev --cfg 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

Type	State	Frontend	Deploy
Vein	None (or OAuth)	Optional test UI	With soleprint
Shunt	Configurable responses	Config UI	With soleprint
Pulse	Vein + config	Uses vein's	With soleprint
Plexus	Full app state	Required	Self-contained

Room Configuration

Each room in cfg/ has:

• config.json - Framework branding/terminology (can rebrand soleprint)
• data/ - Data files (veins.json, shunts.json, depots.json, etc.)
• Room-specific: databrowse depot, tester tests, monitors, models

Managed rooms (like amar) also have:

• docker-compose.yml - Room's own services
• soleprint/ - Soleprint Docker config for this room
• .env.example - Environment template

Build & Run

Commands

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

# Using ctrl scripts
./ctrl/build.sh                        # Build standalone
./ctrl/build.sh amar                   # Build amar
./ctrl/build.sh --all                  # Build all

./ctrl/start.sh                        # Start standalone
./ctrl/start.sh amar                   # Start amar
./ctrl/start.sh amar -d                # Detached
./ctrl/stop.sh amar                    # Stop
./ctrl/logs.sh amar                    # View logs

# Bare-metal dev
cd gen/standalone && .venv/bin/python run.py

Adding a New Managed Room

# 1. Create room config
mkdir -p cfg/clientx/data

# 2. Copy base config
cp cfg/standalone/config.json cfg/clientx/
cp -r cfg/standalone/data/* cfg/clientx/data/

# 3. Customize as needed (shunts, depots, branding)

# 4. Build and run
python build.py dev --cfg clientx
./ctrl/start.sh clientx

Ports

Service	Port
Soleprint	12000
Amar Backend	8000
Amar Frontend	3000

Tools

Tool	Location	Purpose
modelgen	station/tools/modelgen	Model generation
datagen	station/tools/datagen	Test data generation
tester	station/tools/tester	BDD/playwright test runner
sbwrapper	station/tools/sbwrapper	Sidebar wrapper UI
databrowse	station/monitors/databrowse	SQL data browser

Integration with ppl/ (Infrastructure)

wdir/
├── spr/           # This repo (soleprint)
├── ppl/           # Pipelines & infrastructure
│   ├── pipelines/spr-standalone/  # CI/CD for standalone
│   ├── pipelines/spr-managed/     # Manual deploy for rooms
│   └── gateway/                   # Nginx configs
└── ama/           # Amar source code

Pipeline (standalone only)

• git push -> woodpecker -> build gen/standalone/ -> docker push -> deploy
• Managed rooms deploy manually (no pipeline for client code)

External Paths

What	Path
Amar Backend	/home/mariano/wdir/ama/amar_django_back
Amar Frontend	/home/mariano/wdir/ama/amar_frontend
Pipelines	/home/mariano/wdir/ppl

Files Ignored

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