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 + 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.) but is always initiated from mainroom.

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

Build Tool

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

# From spr/
python build.py --help
python build.py dev                        # Build with symlinks
python build.py deploy --output /path/     # Build for production
python build.py models                     # Only regenerate models

Modelgen (Generic Tool)

Modelgen is a generic model generation tool in station/tools/modelgen/:

# Generate models from config
python -m station.tools.modelgen from-config --config config/soleprint.config.json --output gen/models/

# Future: extract models from codebases (for databrowse)
python -m station.tools.modelgen extract --source /path/to/django/project --output models/

Setting Up Dev Environment

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 main.py                   # Hub on :12000

Building for Deployment

cd spr/
python build.py deploy --output ../deploy/soleprint/

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

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

Regenerating Models Only (rare)

cd spr/
python build.py models

Orchestrating with Managed Room

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

• Project structure finalized
• Schema.json in place
• Generator moved to station/tools/
• Hub/gen separation with symlinks
• Mainroom structure from core_nest
• Docker configs updated to soleprint naming
• Tools consolidated from pawprint
• Build tool with dev/deploy modes
• gen/ runs correctly

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

# Build for dev (from spr/)
python build.py dev

# Start dev server
cd gen && .venv/bin/python main.py

# Health check
curl localhost:12000/health

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

# 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 config/soleprint.config.json -o gen/models/