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.

```bash
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:

```bash
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

```bash
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/`