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
├── config/                # Framework configurations
│   └── soleprint.config.json
│
├── 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
│   │   ├── generator/     # Model/framework generator
│   │   ├── 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)
│
├── hub/                   # VERSIONED base files
│   ├── main.py            # Hub entry point
│   ├── index.html         # Landing page
│   ├── requirements.txt   # Dependencies
│   └── dataloader/        # Data loading module
│
├── gen/                   # RUNNABLE instance (gitignored, symlinks)
│   ├── main.py            # → ../hub/main.py
│   ├── index.html         # → ../hub/index.html
│   ├── requirements.txt   # → ../hub/requirements.txt
│   ├── dataloader/        # → ../hub/dataloader/
│   ├── artery/            # → ../artery/
│   ├── atlas/             # → ../atlas/
│   ├── station/           # → ../station/
│   ├── data/              # → ../data/
│   └── models/            # GENERATED (one-time per client)
│       └── pydantic/
│
└── mainroom/              # Orchestration: soleprint ↔ managed room
    ├── ctrl/              # Orchestration commands
    ├── sbwrapper/         # Sidebar wrapper UI
    ├── link/              # Adapters (connect without modifying either side)
    │   └── adapters/      # Framework-specific adapters (django, etc.)
    └── soleprint/         # Docker configs for soleprint services
        ├── docker-compose.yml
        └── Dockerfile.fastapi
```

## The Three Systems

| System | Purpose | Tagline |
|--------|---------|---------|
| **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.)
- `link/` - Adapters to connect soleprint to managed app data WITHOUT modifying either
- `soleprint/` - Docker configs for running soleprint services
- `ctrl/` - Commands for orchestration (sets env vars, starts services)

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

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

### The Generator
Lives in `station/tools/generator/`. It:
1. Reads `schema.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

### Naming Flexibility
Code inside soleprint should NOT have imports too tied to system names. Display names are configurable. Future: swap entire naming domains without breaking functionality.

## Development Workflow

### Running Locally
```bash
cd spr/gen
pip install -r requirements.txt
python main.py  # Hub on :12000
```

### Regenerating Models (one-time / rare)
```bash
cd spr/station/tools/generator
python -m generators.orchestrator \
    --config ../../../config/soleprint.config.json \
    --output ../../../gen
```

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

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

Planned:
- `databrowse` - Data browser tool (separate CLAUDE.md)
- `sbwrapper` - Sidebar wrapper development

## External References

| What | Location | Notes |
|------|----------|-------|
| Core Nest (legacy) | `core_nest/` | Original orchestration, being replaced by mainroom |
| Amar Backend | `ama/amar_django_back` | Example managed room |
| Amar Frontend | `ama/amar_frontend` | Example managed room |
| Pawprint (legacy) | `ama/pawprint` | Original pet-themed naming, deprecated |

## Tools Status

| Tool | Location | Status | Notes |
|------|----------|--------|-------|
| generator | station/tools/generator | Working | Refactor file IO pending |
| datagen | station/tools/datagen | Working | Test data generation |
| tester | station/tools/tester | Advanced | Full BDD/playwright |
| hub | station/tools/hub | Idea | Port management |
| infra | station/tools/infra | Idea | Cloud deploy scripts |
| graphgen | station/tools/graphgen | Idea | Graph generation |

## Ports

| Service | Port |
|---------|------|
| Hub (soleprint) | 12000 |
| Artery | 12001 |
| Atlas | 12002 |
| Station | 12003 |

## Current State

**Done:**
- [x] Project structure finalized
- [x] Schema.json in place
- [x] Generator moved to station/tools/
- [x] Hub/gen separation with symlinks
- [x] Mainroom structure from core_nest
- [x] Docker configs updated to soleprint naming
- [x] Tools consolidated from pawprint

**Next:**
1. [ ] Test gen/ runs correctly
2. [ ] Create spr/ctrl/ scripts
3. [ ] Complete mainroom/ctrl/ orchestration scripts
4. [ ] Worktree for databrowse
5. [ ] Worktree for sbwrapper

## Files Ignored (gitignore)

- `fails/` - Previous attempts, reference only
- `def/` - Definition drafts
- `gen/` - Runnable instance (except gen/models/)
- `__pycache__/`, `*.pyc`
- `venv/`, `.venv/`

## Quick Reference

```bash
# Start dev server
cd gen && python main.py

# Health check
curl localhost:12000/health

# View landing
open http://localhost:12000

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