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
│
├── 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

cd spr/gen
python main.py  # Hub on :12000

Regenerating Models (infrequent)

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:

• Model schema defined (pawprint/models/schema.json)
• Generator working (fails/02/generators/)
• 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

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

# Health check
curl localhost:12000/health

# View systems
open http://localhost:12000