migrated core_nest to mainroom

2025-12-24 06:23:31 -03:00
parent 329c401ff5
commit d62337e7ba
50 changed files with 5503 additions and 73 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -18,18 +18,20 @@ spr/
 ├── config/                # Framework configurations
 │   └── soleprint.config.json
 │
-├── artery/                # ACTUAL source - Vital connections
+├── 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/                 # ACTUAL source - Documentation system
+├── atlas/                 # VERSIONED - Documentation system
 │   ├── templates/         # Gherkin, BDD patterns
 │   ├── books/             # Composed: Template + Depot
 │   └── depots/            # Data storage
 │
-├── station/               # ACTUAL source - Tools & execution
+├── station/               # VERSIONED - Tools & execution
 │   ├── tools/             # Utilities, generators, runners
 │   │   ├── generator/     # Model/framework generator
 │   │   ├── datagen/       # Test data generation
@@ -39,17 +41,34 @@ spr/
 │   ├── rooms/             # Environment configs
 │   └── depots/            # Data storage
 │
-├── data/                  # Site content as JSON files
+├── data/                  # JSON content files (versioned)
 │
-└── gen/                   # RUNNABLE instance (run from here)
-    ├── main.py            # Hub entry point
-    ├── index.html         # Landing page
-    ├── requirements.txt
-    ├── models/            # Generated Pydantic models
-    ├── data/              # Symlink → ../data/
-    ├── artery/            # Symlink → ../artery/
-    ├── atlas/             # Symlink → ../atlas/
-    └── station/           # Symlink → ../station/
+├── 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
@@ -79,42 +98,54 @@ Composed:        Pulse (artery), Book (atlas), Desk (station)
 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
- **core_room** is special: orchestrates soleprint + managed sites (Docker lives outside soleprint)
+- 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 for running soleprint services
+- `ctrl/` - Commands for orchestration (sets env vars, starts services)
+
+### 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. Model generation is **infrequent** - only when schema changes
-
-**Bootstrap:** Generator runs standalone (no model dependencies), generates models, then station can use them.
-
-### Development Symlinks
-For development, `gen/` contains symlinks back to source:
- `gen/artery/` → `../artery/`
- `gen/atlas/` → `../atlas/`
- `gen/station/` → `../station/`
- `gen/data/` → `../data/`
-
-This means: edit in `spr/artery/`, run from `spr/gen/`, no regeneration needed.
-
-**Production:** Copy everything (resolve symlinks).
+3. Generation is **one-time per client** (like install)
+4. Runs standalone (no model dependencies) for bootstrap

 ### Naming Flexibility
-Code inside soleprint components should NOT have imports too tied to "artery", "atlas", "station" names. At some point these could be swapped for different naming schemes (for teams with different domain language).
+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

 ### Running Locally
 ```bash
 cd spr/gen
+pip install -r requirements.txt
 python main.py  # Hub on :12000
 ```

-### Regenerating Models (infrequent)
+### Regenerating Models (one-time / rare)
 ```bash
 cd spr/station/tools/generator
-python -m generators.orchestrator --config ../../../config/soleprint.config.json --output ../../../gen
+python -m generators.orchestrator \
+    --config ../../../config/soleprint.config.json \
+    --output ../../../gen
+```
+
+### Orchestrating with Managed Room
+```bash
+cd spr/mainroom/ctrl
+./start.sh  # Sets env vars, starts soleprint + link services
 ```

 ### Worktrees
@@ -122,28 +153,27 @@ Feature development in: `/home/mariano/wdir/wts/spr/<branch>`

 Planned:
 - `databrowse` - Data browser tool (separate CLAUDE.md)
- `sbwrapper` - Sidebar wrapper UI for core_room (separate CLAUDE.md)
+- `sbwrapper` - Sidebar wrapper development

-## External Dependencies
+## External References

 | What | Location | Notes |
 |------|----------|-------|
-| Core Room | `core_nest/` | Orchestration + Docker (outside spr) |
-| Amar Backend | `ama/amar_django_back` | Test subject |
-| Amar Frontend | `ama/amar_frontend` | Test subject |
-| Pawprint | `ama/pawprint` | Legacy - migrate tools then deprecate |
+| 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 | Source | Status | Notes |
-|------|--------|--------|-------|
-| generator | fails/02/generators | Move to station/tools/ | Refactor file IO |
-| datagen | pawprint/ward/tools | Consolidate | Merge with tester/generate_test_data |
-| tester | pawprint/ward/tools | Advanced | Full BDD/playwright |
-| databrowse | - | WIP | Separate worktree |
-| hub | pawprint/ward/tools | Idea | Port management |
-| infra | pawprint/ward/tools | Idea | Cloud deploy scripts |
-| graphgen | pawprint/ward/tools | Idea | Graph generation |
+| Tool | Location | Status | Notes |
+|------|----------|--------|-------|
+| generator | station/tools/generator | Working | Refactor file IO pending |
+| 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

@@ -157,25 +187,28 @@ Planned:
 ## Current State

 **Done:**
- [x] Model schema defined (pawprint/models/schema.json)
- [x] Generator working (fails/02/generators/)
- [x] Generated instance in gen/
+- [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

-**Next (in order):**
-1. [ ] Create folder structure (artery/, atlas/, station/, config/)
-2. [ ] Move schema.json to spr/
-3. [ ] Move generator to station/tools/generator/
-4. [ ] Move config to spr/config/
-5. [ ] Set up symlinks in gen/
-6. [ ] Consolidate tools from pawprint/ward/tools/
-7. [ ] Integrate core_room (sbwrapper)
-8. [ ] Worktrees for databrowse, sbwrapper
+**Next:**
+1. [ ] Test gen/ runs correctly
+2. [ ] Create spr/ctrl/ scripts
+3. [ ] Complete mainroom/ctrl/ orchestration scripts
+4. [ ] Worktree for databrowse
+5. [ ] Worktree for sbwrapper

 ## Files Ignored (gitignore)

 - `fails/` - Previous attempts, reference only
- `gen/` - Generated/runnable, not source (except models/)
 - `def/` - Definition drafts
+- `gen/` - Runnable instance (except gen/models/)
+- `__pycache__/`, `*.pyc`
+- `venv/`, `.venv/`

 ## Quick Reference

@@ -186,6 +219,9 @@ cd gen && python main.py
 # Health check
 curl localhost:12000/health

-# View systems
+# View landing
 open http://localhost:12000
+
+# Docker (via mainroom)
+cd mainroom/soleprint && docker compose up -d
 ```