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
├── build.py               # Build tool (dev/deploy)
│
├── cfg/                   # Room configurations
│   ├── soleprint.config.json  # Framework model definitions
│   └── amar/              # AMAR room config
│       ├── .env
│       ├── docker-compose.yml
│       ├── Dockerfile.backend
│       ├── Dockerfile.frontend
│       ├── ctrl/          # Room-specific scripts
│       ├── databrowse/depot/   # AMAR schema for databrowse
│       ├── tester/tests/       # AMAR-specific tests
│       ├── monitors/turnos/    # AMAR-specific monitors
│       ├── models/             # AMAR models (pydantic, django, prisma)
│       └── link/               # Databrowse adapter
│
├── ctrl/                  # Soleprint standalone ctrl (Docker)
│   ├── build.sh           # python build.py dev --cfg <room>
│   ├── start.sh           # docker compose up
│   ├── stop.sh
│   └── logs.sh
│
├── artery/                # Vital connections
│   ├── veins/             # Stateless API connectors
│   │   ├── jira/
│   │   ├── slack/
│   │   ├── google/
│   │   ├── base.py
│   │   ├── oauth.py
│   │   └── PATTERNS.md
│   ├── shunts/            # Fake connectors for testing
│   │   └── example/
│   ├── pulses/            # Composed: Vein + Room + Depot
│   ├── plexuses/          # Full apps: backend + frontend + DB
│   └── room/              # Base room templates
│
├── atlas/                 # Documentation system
│   ├── book/              # Gherkin samples, feature docs, arch diagrams
│   ├── static/            # Prism syntax highlighting
│   ├── main.py
│   └── index.html
│
├── station/               # Tools & execution
│   ├── tools/
│   │   ├── modelgen/      # Model generation
│   │   ├── datagen/       # Test data generation
│   │   ├── tester/        # BDD/playwright test runner
│   │   ├── graphgen/      # Graph generation
│   │   └── ...
│   └── monitors/
│       └── databrowse/    # SQL data browser (generic)
│
├── data/                  # JSON content files
│   ├── rooms.json
│   ├── depots.json
│   ├── veins.json
│   └── ...
│
├── soleprint/             # Core entry points (versioned)
│   ├── main.py            # Multi-port entry
│   ├── run.py             # Single-port dev server
│   ├── index.html
│   ├── requirements.txt
│   ├── Dockerfile
│   └── dataloader/
│
├── gen/                   # Built instance (gitignored)
│   ├── ... (copies from soleprint/, artery/, atlas/, station/)
│   ├── models/            # Generated by modelgen
│   └── docker-compose.yml # For standalone Docker
│
└── mainroom/              # Orchestration: soleprint + managed room
    ├── amar -> ../cfg/amar    # Symlink to room config
    ├── soleprint/             # Soleprint Docker config
    │   ├── docker-compose.yml
    │   └── docker-compose.nginx.yml
    ├── sbwrapper/             # Sidebar wrapper UI
    │   ├── config.json
    │   ├── sidebar.js
    │   └── sidebar.css
    └── ctrl/                  # Orchestration scripts
        ├── start.sh           # Start amar + soleprint
        ├── stop.sh
        ├── deploy.sh          # Deploy to AWS
        └── server/            # AWS setup scripts

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

Artery Hierarchy

Vein ──────► Pulse ──────► Plexus
│           │              │
│           │              └── Full app: backend + frontend + DB
│           │                  (e.g., WhatsApp with chat UI)
│           │
│           └── Composed: Vein + Room + Depot
│               (e.g., Jira vein for specific project)
│
└── Stateless API connector
    (e.g., Jira, Slack, Google)


Shunt ─── Fake connector for testing
          (e.g., mercadopago mock with UI to set responses)

Type	State	Frontend	Deploy
Vein	None (or OAuth)	Optional test UI	With soleprint
Pulse	Vein + config	Uses vein's	With soleprint
Plexus	Full app state	Required	Self-contained
Shunt	Configurable responses	Config UI	With soleprint

Key Concepts

Rooms

A Room is an environment config with:

• ctrl/ folder with commands for that room
• .env with paths and settings
• Room-specific configs (databrowse depot, tester tests, monitors, models)

Mainroom

Orchestrates soleprint + managed room together:

• mainroom/amar → symlink to cfg/amar
• mainroom/soleprint/ → soleprint Docker config
• mainroom/sbwrapper/ → sidebar overlay for quick login, Jira info
• mainroom/ctrl/ → start/stop/deploy scripts

Build & Gen

• soleprint/ = Versioned source
• gen/ = Built instance (gitignored, Docker-ready)
• python build.py dev --cfg amar copies everything + room config

Development Workflow

Soleprint Standalone (no managed room)

# Build
cd spr/
python build.py dev

# Run with Docker
./ctrl/start.sh

# Or bare-metal
cd gen && .venv/bin/python run.py

Soleprint + Amar (with managed room)

# Build soleprint with amar config
cd spr/
python build.py dev --cfg amar

# Create shared network
docker network create soleprint_network

# Start everything
cd mainroom/ctrl
./start.sh -d              # Detached
./start.sh                 # Foreground (logs)
./stop.sh                  # Stop all

Deploy to AWS

cd mainroom/ctrl
./deploy.sh --dry-run      # Preview
./deploy.sh                # Deploy

Ports

Service	Port
Soleprint	12000
Artery	12001
Atlas	12002
Station	12003
Amar Backend	8000
Amar Frontend	3000

Tools

Tool	Location	Status
modelgen	station/tools/modelgen	Working
datagen	station/tools/datagen	Working
tester	station/tools/tester	Advanced
graphgen	station/tools/graphgen	WIP

Monitors

Monitor	Location	Notes
databrowse	station/monitors/databrowse	Generic SQL browser
turnos	cfg/amar/monitors/turnos	AMAR-specific

Veins

Vein	Location	Auth
jira	artery/veins/jira	Token
slack	artery/veins/slack	Token
google	artery/veins/google	OAuth2

Quick Reference

# === Build ===
python build.py dev                    # Soleprint only
python build.py dev --cfg amar         # With amar config
python build.py deploy --output /path/ # Production build

# === Standalone (soleprint only) ===
./ctrl/build.sh amar                   # Build with amar
./ctrl/start.sh                        # Docker start
./ctrl/stop.sh                         # Docker stop

# === With Managed Room (mainroom) ===
cd mainroom/ctrl
./start.sh -d                          # Start detached
./start.sh amar                        # Start only amar
./start.sh soleprint                   # Start only soleprint
./stop.sh                              # Stop all
./deploy.sh                            # Deploy to AWS

# === Bare-metal Dev ===
cd gen
.venv/bin/python run.py                # Single-port dev server

# === Health Checks ===
curl localhost:12000/health            # Soleprint
curl localhost:8000/health             # Amar backend

Integration with ppl/ (Infrastructure)

The ppl/ repo manages infrastructure alongside spr:

wdir/
├── spr/           # This repo (soleprint)
├── ppl/           # Pipelines & infrastructure
│   ├── ctrl/
│   │   ├── deploy-gen.sh   # Build spr + deploy via mainroom
│   │   └── dns.sh          # Route53 DNS management
│   ├── ci/                 # Woodpecker CI configs
│   ├── gateway/            # Nginx/Caddy configs
│   └── pipelines/          # CI/CD pipelines
└── ama/           # Amar source code
    ├── amar_django_back/
    └── amar_frontend/

Deploy from ppl/

cd ppl/ctrl
./deploy-gen.sh              # Build spr + deploy to AWS
./deploy-gen.sh --dry-run    # Preview
./dns.sh add soleprint       # Add soleprint.mcrn.ar DNS

Server Structure (mcrn.ar)

~/mainroom/              # Deployed mainroom
├── amar/                # Amar Docker services
├── soleprint/           # Soleprint Docker services
└── ctrl/                # Server-side scripts

# Services run on:
soleprint.mcrn.ar:12000  # Soleprint
amar.mcrn.ar             # Amar (nginx proxied)

Adding New Services

1. Add DNS: ppl/ctrl/dns.sh add <service>
2. Add nginx config in ppl/gateway/
3. Add docker-compose in mainroom/<service>/
4. Update mainroom/ctrl/start.sh if needed

External Paths

What	Path
Amar Backend	/home/mariano/wdir/ama/amar_django_back
Amar Frontend	/home/mariano/wdir/ama/amar_frontend
Venv	/home/mariano/wdir/venv/spr
Pipelines	/home/mariano/wdir/ppl

Files Ignored

• gen/ - Regenerate with python build.py dev
• fails/, def/ - Drafts
• __pycache__/, .venv/