# 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
│
├── artery/                # ACTUAL source - Vital connections
│   ├── veins/             # Single-responsibility connectors
│   ├── pulses/            # Composed: Vein + Room + Depot
│   ├── rooms/             # Environment configs
│   └── depots/            # Data storage
│
├── atlas/                 # ACTUAL source - Documentation system
│   ├── templates/         # Gherkin, BDD patterns
│   ├── books/             # Composed: Template + Depot
│   └── depots/            # Data storage
│
├── station/               # ACTUAL source - 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/                  # Site content as JSON files
│
└── gen/                   # RUNNABLE instance (run from here)
    ├── main.py            # Hub entry point
    ├── index.html         # Landing page
    ├── requirements.txt
    ├── models/            # Generated Pydantic models
    ├── data/              # Symlink → ../data/
    ├── artery/            # Symlink → ../artery/
    ├── atlas/             # Symlink → ../atlas/
    └── station/           # Symlink → ../station/
```

## 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
- **core_room** is special: orchestrates soleprint + managed sites (Docker lives outside soleprint)

### The Generator
Lives in `station/tools/generator/`. It:
1. Reads `schema.json` (source of truth)
2. Generates Pydantic models to `gen/models/`
3. Model generation is **infrequent** - only when schema changes

**Bootstrap:** Generator runs standalone (no model dependencies), generates models, then station can use them.

### Development Symlinks
For development, `gen/` contains symlinks back to source:
- `gen/artery/` → `../artery/`
- `gen/atlas/` → `../atlas/`
- `gen/station/` → `../station/`
- `gen/data/` → `../data/`

This means: edit in `spr/artery/`, run from `spr/gen/`, no regeneration needed.

**Production:** Copy everything (resolve symlinks).

### Naming Flexibility
Code inside soleprint components should NOT have imports too tied to "artery", "atlas", "station" names. At some point these could be swapped for different naming schemes (for teams with different domain language).

## Development Workflow

### Running Locally
```bash
cd spr/gen
python main.py  # Hub on :12000
```

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

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

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

## External Dependencies

| What | Location | Notes |
|------|----------|-------|
| Core Room | `core_nest/` | Orchestration + Docker (outside spr) |
| Amar Backend | `ama/amar_django_back` | Test subject |
| Amar Frontend | `ama/amar_frontend` | Test subject |
| Pawprint | `ama/pawprint` | Legacy - migrate tools then deprecate |

## Tools Status

| Tool | Source | Status | Notes |
|------|--------|--------|-------|
| generator | fails/02/generators | Move to station/tools/ | Refactor file IO |
| datagen | pawprint/ward/tools | Consolidate | Merge with tester/generate_test_data |
| tester | pawprint/ward/tools | Advanced | Full BDD/playwright |
| databrowse | - | WIP | Separate worktree |
| hub | pawprint/ward/tools | Idea | Port management |
| infra | pawprint/ward/tools | Idea | Cloud deploy scripts |
| graphgen | pawprint/ward/tools | Idea | Graph generation |

## Ports

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

## Current State

**Done:**
- [x] Model schema defined (pawprint/models/schema.json)
- [x] Generator working (fails/02/generators/)
- [x] Generated instance in gen/

**Next (in order):**
1. [ ] Create folder structure (artery/, atlas/, station/, config/)
2. [ ] Move schema.json to spr/
3. [ ] Move generator to station/tools/generator/
4. [ ] Move config to spr/config/
5. [ ] Set up symlinks in gen/
6. [ ] Consolidate tools from pawprint/ward/tools/
7. [ ] Integrate core_room (sbwrapper)
8. [ ] Worktrees for databrowse, sbwrapper

## Files Ignored (gitignore)

- `fails/` - Previous attempts, reference only
- `gen/` - Generated/runnable, not source (except models/)
- `def/` - Definition drafts

## Quick Reference

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

# Health check
curl localhost:12000/health

# View systems
open http://localhost:12000
```