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

1.1 changes

Browse Source
This commit is contained in:
buenosairesam
2025-12-29 14:17:53 -03:00
parent 11fde0636f
commit c5546cf7fc
58 changed files with 1048 additions and 496 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
CLAUDE.md
View File

@@ -15,8 +15,12 @@ spr/
├── CLAUDE.md # You are here
├── README.md # User-facing docs
├── schema.json # Source of truth for models
├── config/ # Framework configurations
│ └── soleprint.config.json
├── cfg/ # Framework configurations
│ ├── soleprint.config.json # Model definitions
│ └── amar/ # Room-specific configs (absolute paths to Dockerfiles)
│ ├── .env.example
│ ├── docker-compose.yml
│ └── link/ # Databrowse adapter for amar
│
├── ctrl/ # Soleprint room's own ctrl
│
@@ -33,7 +37,7 @@ spr/
│
├── station/ # VERSIONED - Tools & execution
│ ├── tools/ # Utilities, generators, runners
│ │ ├── generator/ # Model/framework generator
│ │ ├── modelgen/ # Model generation from config/codebases
│ │ ├── datagen/ # Test data generation
│ │ ├── tester/ # Test runner (BDD/playwright)
│ │ └── ...
@@ -43,38 +47,41 @@ spr/
│
├── data/ # JSON content files (versioned)
│
├── hub/ # VERSIONED base files
│ ├── main.py # Hub entry point
├── 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, symlinks)
│ ├── main.py # → ../hub/main.py
│ ├── index.html # → ../hub/index.html
│ ├── requirements.txt # → ../hub/requirements.txt
│ ├── dataloader/ # → ../hub/dataloader/
│ ├── main.py # → ../soleprint/main.py
│ ├── run.py # → ../soleprint/run.py
│ ├── index.html # → ../soleprint/index.html
│ ├── requirements.txt # → ../soleprint/requirements.txt
│ ├── dataloader/ # → ../soleprint/dataloader/
│ ├── artery/ # → ../artery/
│ ├── atlas/ # → ../atlas/
│ ├── station/ # → ../station/
│ ├── data/ # → ../data/
│ ├── cfg/ # Copied config
│ └── models/ # GENERATED (one-time per client)
│ └── pydantic/
│
└── mainroom/ # Orchestration: soleprint ↔ managed room
├── ctrl/ # Orchestration commands
├── ctrl/ # Orchestration commands (acts on mainroom)
├── 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
├── docker-compose.nginx.yml # Path-based routing
└── Dockerfile.fastapi
```
## The Three Systems
## 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 |
@@ -103,32 +110,34 @@ A **Room** is an environment with soleprint context, features, and conventions:
### 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.
Soleprint can run without a managed room (for testing veins, etc.).
### Hub vs Gen
- `hub/` = Versioned base files (main.py, dataloader, index.html)
- `gen/` = Gitignored runnable instance with symlinks to hub/ + systems
### 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 with symlinks to soleprint/ + systems
- `gen/models/` = Generated models (one-time per client, like an install)
**Development:** Edit in hub/, artery/, atlas/, station/, data/ → run from gen/
**Development:** Edit in soleprint/, 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)
### 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
### 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
@@ -138,23 +147,12 @@ The build script at spr root handles both development and deployment builds:
```bash
# From spr/
python build.py --help
python build.py dev # Build with symlinks
python build.py dev # Build with symlinks (soleprint only)
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
```
### Modelgen (Generic Tool)
Modelgen is a generic model generation tool in `station/tools/modelgen/`:
```bash
# 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
```bash
cd spr/
@@ -163,50 +161,48 @@ 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
.venv/bin/python run.py # Single-port bare-metal dev server
# or
.venv/bin/python main.py # Multi-port (production-like)
```
### 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
```bash
cd spr/
python build.py deploy --output ../deploy/soleprint/
python build.py deploy --output ../deploy/soleprint/ --cfg amar
# Then deploy:
rsync -av ../deploy/soleprint/ server:/app/soleprint/
ssh server 'cd /app/soleprint && ./run.sh'
ssh server 'cd /app/soleprint && ./start.sh'
# Or use mainroom ctrl scripts:
cd mainroom/soleprint/ctrl/local
./deploy.sh
```
### Regenerating Models Only (rare)
```bash
cd spr/
python build.py models
```
### Orchestrating with Managed Room
```bash
cd spr/mainroom/ctrl
./start.sh # Sets env vars, starts soleprint + link services
./start.sh # Sets env vars, starts soleprint + managed room services
```
### Worktrees
Feature development in: `/home/mariano/wdir/wts/spr/<branch>`
Planned:
- `databrowse` - Data browser tool (separate CLAUDE.md)
- `databrowse` - Data browser tool (uses modelgen extract)
- `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
@@ -215,7 +211,6 @@ Planned:
| 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 |
@@ -223,7 +218,7 @@ Planned:
| Service | Port |
|---------|------|
| Hub (soleprint) | 12000 |
| Soleprint | 12000 |
| Artery | 12001 |
| Atlas | 12002 |
| Station | 12003 |
@@ -233,13 +228,14 @@ Planned:
**Done:**
- [x] Project structure finalized
- [x] Schema.json in place
- [x] Generator moved to station/tools/
- [x] Hub/gen separation with symlinks
- [x] Mainroom structure from core_nest
- [x] Docker configs updated to soleprint naming
- [x] Tools consolidated from pawprint
- [x] Build tool with dev/deploy modes
- [x] gen/ runs correctly
- [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
**Next:**
1. [ ] Test mainroom/soleprint/ctrl scripts
@@ -260,15 +256,19 @@ Planned:
```bash
# Build for dev (from spr/)
python build.py dev
python build.py dev --cfg amar # With amar room config
# Start dev server
# Start dev server (bare-metal, single-port)
cd gen && .venv/bin/python run.py
# Start production-like (multi-port)
cd gen && .venv/bin/python main.py
# Health check
curl localhost:12000/health
# Build for deployment
python build.py deploy --output /path/to/deploy/
python build.py deploy --output /path/to/deploy/ --cfg amar
# Deploy via ctrl scripts
cd mainroom/soleprint/ctrl/local && ./deploy.sh
@@ -277,5 +277,5 @@ cd mainroom/soleprint/ctrl/local && ./deploy.sh
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/
python -m station.tools.modelgen from-config -c cfg/soleprint.config.json -o gen/models/
```