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)
```bash
# 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)
```bash
# 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
```bash
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

```bash
# === 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/
```bash
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/`