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