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
├── cfg/                   # Framework configurations
│   ├── soleprint.config.json  # Model definitions
│   └── amar/              # Room-specific configs (absolute paths to Dockerfiles)
│       ├── .env.example
│       ├── docker-compose.yml
│       └── link/          # Databrowse adapter for amar
│
├── ctrl/                  # Soleprint room's own ctrl
│
├── artery/                # VERSIONED - Vital connections
│   ├── veins/             # Single-responsibility connectors
│   ├── pulses/            # Composed: Vein + Room + Depot
│   ├── rooms/             # Environment configs
│   └── depots/            # Data storage
│
├── atlas/                 # VERSIONED - Documentation system
│   ├── templates/         # Gherkin, BDD patterns
│   ├── books/             # Composed: Template + Depot
│   └── depots/            # Data storage
│
├── station/               # VERSIONED - Tools & execution
│   ├── tools/             # Utilities, generators, runners
│   │   ├── modelgen/      # Model generation from config/codebases
│   │   ├── datagen/       # Test data generation
│   │   ├── tester/        # Test runner (BDD/playwright)
│   │   └── ...
│   ├── desks/             # Composed: Cabinet + Room + Depots
│   ├── rooms/             # Environment configs
│   └── depots/            # Data storage
│
├── data/                  # JSON content files (versioned)
│
├── soleprint/             # VERSIONED - Core coordinator
│   ├── main.py            # Multi-port entry point (production)
│   ├── run.py             # Single-port bare-metal dev server
│   ├── index.html         # Landing page
│   ├── requirements.txt   # Dependencies
│   └── dataloader/        # Data loading module
│
├── gen/                   # RUNNABLE instance (gitignored, symlinks)
│   ├── main.py            # → ../soleprint/main.py
│   ├── run.py             # → ../soleprint/run.py
│   ├── index.html         # → ../soleprint/index.html
│   ├── requirements.txt   # → ../soleprint/requirements.txt
│   ├── dataloader/        # → ../soleprint/dataloader/
│   ├── artery/            # → ../artery/
│   ├── atlas/             # → ../atlas/
│   ├── station/           # → ../station/
│   ├── data/              # → ../data/
│   ├── cfg/               # Copied config
│   └── models/            # GENERATED (one-time per client)
│       └── pydantic/
│
└── mainroom/              # Orchestration: soleprint ↔ managed room
    ├── ctrl/              # Orchestration commands (acts on mainroom)
    ├── sbwrapper/         # Sidebar wrapper UI
    └── soleprint/         # Docker configs for soleprint services
        ├── docker-compose.yml
        ├── docker-compose.nginx.yml  # Path-based routing
        └── Dockerfile.fastapi
```

## 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 |

## Model Hierarchy

```
Shared:          Room (configs), Depot (data)
System-specific: Vein (artery), Template (atlas), Tool (station)
Composed:        Pulse (artery), Book (atlas), Desk (station)
```

**Formulas:**
- Pulse = Vein + Room + Depot
- Book = Template + Depot
- Desk = Cabinet + Room + Depots

## Key Concepts

### Rooms (Environments)
A **Room** is an environment with soleprint context, features, and conventions:
- Every room has a `ctrl/` folder with commands that act only on that room
- Tools are pluggable into any room
- Managed projects work with their own defaults (env vars set by mainroom ctrl for orchestration)

### Mainroom
The **mainroom** orchestrates interaction between soleprint and managed rooms:
- `sbwrapper/` - Sidebar UI overlay for any managed app (quick login, Jira info, etc.)
- `soleprint/` - Docker configs + ctrl scripts for running soleprint services
  - `ctrl/local/` - Local deployment scripts (push.sh, deploy.sh)
  - `ctrl/server/` - Server setup scripts
- `ctrl/` - Mainroom-level orchestration commands

Soleprint can run without a managed room (for testing veins, etc.).

### cfg/ - Configuration
- `cfg/soleprint.config.json` - Framework model definitions
- `cfg/<room>/` - Room-specific configs (e.g., `cfg/amar/`)
  - Uses absolute paths to external Dockerfiles
  - Room-specific tools/adapters (e.g., databrowse link adapter)

### soleprint/ vs gen/
- `soleprint/` = Versioned core files (main.py, run.py, dataloader, index.html)
- `gen/` = Gitignored runnable instance with symlinks to soleprint/ + systems
- `gen/models/` = Generated models (one-time per client, like an install)

**Development:** Edit in soleprint/, artery/, atlas/, station/, data/ → run from gen/
**Production:** Copy everything (resolve symlinks)

### Modelgen (Generic Tool)
Lives in `station/tools/modelgen/`. It:
1. Reads `cfg/soleprint.config.json` (source of truth)
2. Generates Pydantic models to `gen/models/`
3. Generation is **one-time per client** (like install)
4. Runs standalone (no model dependencies) for bootstrap

## Development Workflow

### Build Tool

The build script at spr root handles both development and deployment builds:

```bash
# From spr/
python build.py --help
python build.py dev                        # Build with symlinks (soleprint only)
python build.py dev --cfg amar             # Include amar room config
python build.py deploy --output /path/     # Build for production
python build.py models                     # Only regenerate models
```

### Setting Up Dev Environment
```bash
cd spr/
python build.py dev                        # Creates gen/ with symlinks

cd gen/
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python run.py                    # Single-port bare-metal dev server
# or
.venv/bin/python main.py                   # Multi-port (production-like)
```

### Bare-metal vs Docker
- **Bare-metal:** `python run.py` - Single port, all routes internal, for soleprint dev
- **Docker:** Use mainroom for managed rooms - separate containers, nginx routing

### Building for Deployment
```bash
cd spr/
python build.py deploy --output ../deploy/soleprint/ --cfg amar

# Then deploy:
rsync -av ../deploy/soleprint/ server:/app/soleprint/
ssh server 'cd /app/soleprint && ./start.sh'

# Or use mainroom ctrl scripts:
cd mainroom/soleprint/ctrl/local
./deploy.sh
```

### Orchestrating with Managed Room
```bash
cd spr/mainroom/ctrl
./start.sh  # Sets env vars, starts soleprint + managed room services
```

### Worktrees
Feature development in: `/home/mariano/wdir/wts/spr/<branch>`

Planned:
- `databrowse` - Data browser tool (uses modelgen extract)
- `sbwrapper` - Sidebar wrapper development

## External References

| What | Location | Notes |
|------|----------|-------|
| Amar Backend | `ama/amar_django_back` | Example managed room |
| Amar Frontend | `ama/amar_frontend` | Example managed room |

## Tools Status

| Tool | Location | Status | Notes |
|------|----------|--------|-------|
| modelgen | station/tools/modelgen | Working | Generic model generation (used by build.py, databrowse) |
| datagen | station/tools/datagen | Working | Test data generation |
| tester | station/tools/tester | Advanced | Full BDD/playwright |
| infra | station/tools/infra | Idea | Cloud deploy scripts |
| graphgen | station/tools/graphgen | Idea | Graph generation |

## Ports

| Service | Port |
|---------|------|
| Soleprint | 12000 |
| Artery | 12001 |
| Atlas | 12002 |
| Station | 12003 |

## Current State

**Done:**
- [x] Project structure finalized
- [x] Schema.json in place
- [x] Modelgen in station/tools/
- [x] soleprint/gen separation with symlinks
- [x] Mainroom structure
- [x] Docker configs with nginx path-based routing
- [x] Build tool with dev/deploy modes and --cfg argument
- [x] Bare-metal run.py for single-port dev
- [x] cfg/amar/ with absolute paths pattern
- [x] Renamed: hub→soleprint, config→cfg, nest→room, pawprint→soleprint

**Next:**
1. [ ] Test mainroom/soleprint/ctrl scripts
2. [ ] Test mainroom with managed room (amar)
3. [ ] Worktree for databrowse (uses modelgen extract)
4. [ ] Worktree for sbwrapper

## Files Ignored (gitignore)

- `fails/` - Previous attempts, reference only
- `def/` - Definition drafts
- `gen/` - Entire folder gitignored (regenerate with `python build.py dev`)
- `__pycache__/`, `*.pyc`
- `venv/`, `.venv/`

## Quick Reference

```bash
# Build for dev (from spr/)
python build.py dev
python build.py dev --cfg amar              # With amar room config

# Start dev server (bare-metal, single-port)
cd gen && .venv/bin/python run.py

# Start production-like (multi-port)
cd gen && .venv/bin/python main.py

# Health check
curl localhost:12000/health

# Build for deployment
python build.py deploy --output /path/to/deploy/ --cfg amar

# Deploy via ctrl scripts
cd mainroom/soleprint/ctrl/local && ./deploy.sh

# Docker (via mainroom)
cd mainroom/soleprint && docker compose up -d

# Modelgen (generic tool)
python -m station.tools.modelgen from-config -c cfg/soleprint.config.json -o gen/models/
```