mariano/soleprint
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spr migrated books, and tester

Browse Source
This commit is contained in:
buenosairesam
2025-12-31 09:07:27 -03:00
parent 21b8eab3cb
commit cccc6b5a93
136 changed files with 15763 additions and 472 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
CLAUDE.md
View File

@@ -15,67 +15,91 @@ spr/
├── CLAUDE.md # You are here
├── README.md # User-facing docs
├── schema.json # Source of truth for models
├── cfg/ # Framework configurations
│ ├── soleprint.config.json # Model definitions
│ └── amar/ # Room-specific configs (absolute paths to Dockerfiles)
│ ├── .env.example
├── build.py # Build tool (dev/deploy)
│
├── cfg/ # Room configurations
│ ├── soleprint.config.json # Framework model definitions
│ └── amar/ # AMAR room config
│ ├── .env
│ ├── docker-compose.yml
│ └── link/ # Databrowse adapter for amar
│ ├── 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 room's own ctrl
├── ctrl/ # Soleprint standalone ctrl (Docker)
│ ├── build.sh # python build.py dev --cfg <room>
│ ├── start.sh # docker compose up
│ ├── stop.sh
│ └── logs.sh
│
├── artery/ # VERSIONED - Vital connections
│ ├── veins/ # Single-responsibility connectors
├── 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
│ ├── room/ # Base room code and ctrl templates
│ └── depots/ # Data storage
│ ├── plexuses/ # Full apps: backend + frontend + DB
│ └── room/ # Base room templates
│
├── atlas/ # VERSIONED - Documentation system
│ ├── templates/ # Gherkin, BDD patterns
│ ├── books/ # Composed: Template + Depot
│ └── depots/ # Data storage
│
├── station/ # VERSIONED - Tools & execution
│ ├── tools/ # Utilities, generators, runners
│ │ ├── modelgen/ # Model generation from config/codebases
│ │ ├── 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)
│
├── soleprint/ # VERSIONED - Core coordinator
│ ├── main.py # Multi-port entry point (production)
│ ├── run.py # Single-port bare-metal dev server
│ ├── index.html # Landing page
│ ├── requirements.txt # Dependencies
│ └── dataloader/ # Data loading module
│
├── gen/ # RUNNABLE instance (gitignored, copies)
├── atlas/ # Documentation system
│ ├── book/ # Gherkin samples, feature docs, arch diagrams
│ ├── static/ # Prism syntax highlighting
│ ├── main.py
│ ├── run.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/
│ ├── artery/
│ ├── atlas/
│ ├── station/
│ ├── data/
│ ├── cfg/
│ └── models/ # Generated by modelgen
│ └── pydantic/
│ └── dataloader/
│
└── mainroom/ # Orchestration: soleprint ↔ managed room
├── ctrl/ # Orchestration commands (acts on mainroom)
├── sbwrapper/ # Sidebar wrapper UI
└── soleprint/ # Docker configs for soleprint services
├── docker-compose.yml
├── docker-compose.nginx.yml # Path-based routing
└── Dockerfile.fastapi
├── 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
@@ -87,130 +111,90 @@ spr/
| **Atlas** | Actionable documentation | Mapeando el recorrido |
| **Station** | Tools, environments, execution | Centro de control |
## Model Hierarchy
## Artery Hierarchy
```
Shared: Room (configs), Depot (data)
System-specific: Vein (artery), Template (atlas), Tool (station)
Composed: Pulse (artery), Book (atlas), Desk (station)
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)
```
**Formulas:**
- Pulse = Vein + Room + Depot
- Book = Template + Depot
- Desk = Cabinet + Room + Depots
| 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 (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)
### 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
The **mainroom** orchestrates interaction between soleprint and managed rooms:
- `sbwrapper/` - Sidebar UI overlay for any managed app (quick login, Jira info, etc.)
- `soleprint/` - Docker configs for running soleprint services
- `ctrl/` - Mainroom-level orchestration commands (start.sh, stop.sh, etc.)
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
Soleprint can run without a managed room (for testing veins, etc.).
### cfg/ - Configuration
- `cfg/soleprint.config.json` - Framework model definitions
- `cfg/<room>/` - Room-specific configs (e.g., `cfg/amar/`)
- Uses absolute paths to external Dockerfiles
- Room-specific tools/adapters (e.g., databrowse link adapter)
### soleprint/ vs gen/
- `soleprint/` = Versioned core files (main.py, run.py, dataloader, index.html)
- `gen/` = Gitignored runnable instance (copies, not symlinks - Docker compatible)
- `gen/models/` = Generated models
**Development:** Edit source → `python build.py dev` → run from gen/
### Modelgen (Generic Tool)
Lives in `station/tools/modelgen/`. It:
1. Reads `cfg/soleprint.config.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
### Build & Gen
- `soleprint/` = Versioned source
- `gen/` = Built instance (gitignored, Docker-ready)
- `python build.py dev --cfg amar` copies everything + room config
## Development Workflow
### Build Tool
The build script at spr root handles both development and deployment builds:
```bash
# From spr/
python build.py dev # Build gen/ from source (copies)
python build.py dev --cfg amar # Include amar room config
python build.py deploy --output /path/ # Build for production
python build.py models # Only regenerate models
```
### Setting Up Dev Environment
### Soleprint Standalone (no managed room)
```bash
# Build
cd spr/
python build.py dev # Creates gen/ with symlinks
python build.py dev
cd gen/
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python run.py # Single-port bare-metal dev server
# or
.venv/bin/python main.py # Multi-port (production-like)
# Run with Docker
./ctrl/start.sh
# Or bare-metal
cd gen && .venv/bin/python run.py
```
### Bare-metal vs Docker
- **Bare-metal:** `python run.py` - Single port, all routes internal, for soleprint dev
- **Docker:** Use mainroom for managed rooms - separate containers, nginx routing
### Building for Deployment
### Soleprint + Amar (with managed room)
```bash
# Build soleprint with amar config
cd spr/
python build.py deploy --output ../deploy/soleprint/ --cfg amar
python build.py dev --cfg amar
# Then deploy:
rsync -av ../deploy/soleprint/ server:/app/soleprint/
ssh server 'cd /app/soleprint && ./start.sh'
# Create shared network
docker network create soleprint_network
# Or use mainroom ctrl scripts:
cd mainroom/soleprint/ctrl/local
./deploy.sh
# Start everything
cd mainroom/ctrl
./start.sh -d # Detached
./start.sh # Foreground (logs)
./stop.sh # Stop all
```
### Orchestrating with Managed Room
### Deploy to AWS
```bash
cd spr/mainroom/ctrl
./start.sh # Sets env vars, starts soleprint + managed room services
cd mainroom/ctrl
./deploy.sh --dry-run # Preview
./deploy.sh # Deploy
```
### Worktrees
Feature development in: `/home/mariano/wdir/wts/spr/<branch>`
Planned:
- `databrowse` - Data browser tool (uses modelgen extract)
- `sbwrapper` - Sidebar wrapper development
## External References
| What | Location | Notes |
|------|----------|-------|
| Amar Backend | `ama/amar_django_back` | Example managed room |
| Amar Frontend | `ama/amar_frontend` | Example managed room |
## 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 |
| infra | station/tools/infra | Idea | Cloud deploy scripts |
| graphgen | station/tools/graphgen | Idea | Graph generation |
## Ports
| Service | Port |
@@ -219,60 +203,119 @@ Planned:
| Artery | 12001 |
| Atlas | 12002 |
| Station | 12003 |
| Amar Backend | 8000 |
| Amar Frontend | 3000 |
## Current State
## Tools
**Done:**
- [x] Project structure finalized
- [x] Schema.json in place
- [x] Modelgen in station/tools/
- [x] soleprint/gen separation with symlinks
- [x] Mainroom structure
- [x] Docker configs with nginx path-based routing
- [x] Build tool with dev/deploy modes and --cfg argument
- [x] Bare-metal run.py for single-port dev
- [x] cfg/amar/ with absolute paths pattern
- [x] Renamed: hub→soleprint, config→cfg, nest→room, pawprint→soleprint
| Tool | Location | Status |
|------|----------|--------|
| modelgen | station/tools/modelgen | Working |
| datagen | station/tools/datagen | Working |
| tester | station/tools/tester | Advanced |
| graphgen | station/tools/graphgen | WIP |
**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
## Monitors
## Files Ignored (gitignore)
| Monitor | Location | Notes |
|---------|----------|-------|
| databrowse | station/monitors/databrowse | Generic SQL browser |
| turnos | cfg/amar/monitors/turnos | AMAR-specific |
- `fails/` - Previous attempts, reference only
- `def/` - Definition drafts
- `gen/` - Entire folder gitignored (regenerate with `python build.py dev`)
- `__pycache__/`, `*.pyc`
- `venv/`, `.venv/`
## Veins
| Vein | Location | Auth |
|------|----------|------|
| jira | artery/veins/jira | Token |
| slack | artery/veins/slack | Token |
| google | artery/veins/google | OAuth2 |
## Quick Reference
```bash
# Build for dev (from spr/)
python build.py dev
python build.py dev --cfg amar # With amar room config
# === Build ===
python build.py dev # Soleprint only
python build.py dev --cfg amar # With amar config
python build.py deploy --output /path/ # Production build
# Start dev server (bare-metal, single-port)
cd gen && .venv/bin/python run.py
# === Standalone (soleprint only) ===
./ctrl/build.sh amar # Build with amar
./ctrl/start.sh # Docker start
./ctrl/stop.sh # Docker stop
# Start production-like (multi-port)
cd gen && .venv/bin/python main.py
# === 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
# Health check
curl localhost:12000/health
# === Bare-metal Dev ===
cd gen
.venv/bin/python run.py # Single-port dev server
# Build for deployment
python build.py deploy --output /path/to/deploy/ --cfg amar
# 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 cfg/soleprint.config.json -o gen/models/
# === 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/`