migrated core_nest to mainroom

mainroom/CLAUDE.md

@@ -0,0 +1,139 @@
+# Mainroom - Orchestration Layer
+
+## Purpose
+
+Mainroom orchestrates the interaction between **soleprint** and **managed rooms** (external projects like amar).
+
+Key principle: Connect soleprint to managed apps **without modifying either side**.
+
+## Structure
+
+```
+mainroom/
+├── CLAUDE.md              # You are here
+├── ctrl/                  # Orchestration commands
+│   ├── start.sh           # Start services (sets env vars)
+│   ├── stop.sh            # Stop services
+│   ├── build.sh           # Build images
+│   ├── logs.sh            # View logs
+│   ├── status.sh          # Show status
+│   ├── deploy.sh          # Deploy to server
+│   └── server/            # Server setup scripts
+│
+├── sbwrapper/             # Sidebar wrapper UI
+│   ├── index.html         # Wrapper shell
+│   ├── sidebar.css        # Styling
+│   ├── sidebar.js         # Logic
+│   └── config.json        # Per-room configuration
+│
+├── link/                  # Adapter layer
+│   ├── main.py            # FastAPI service
+│   ├── Dockerfile
+│   ├── docker-compose.yml
+│   └── adapters/          # Framework-specific adapters
+│       ├── __init__.py    # BaseAdapter interface
+│       └── django.py      # Django adapter (for amar)
+│
+└── soleprint/             # Docker configs for soleprint services
+    ├── docker-compose.yml
+    ├── docker-compose.nginx.yml
+    └── Dockerfile.fastapi
+```
+
+## Components
+
+### ctrl/ - Orchestration Commands
+Scripts that set env vars and start/stop services. The managed project works with its own defaults; ctrl sets overrides for orchestration.
+
+```bash
+./ctrl/start.sh              # Start soleprint + link
+./ctrl/start.sh --with-nginx # Start with nginx proxy
+./ctrl/stop.sh               # Stop all
+./ctrl/logs.sh               # View logs
+./ctrl/status.sh             # Show status
+```
+
+### sbwrapper/ - Sidebar Wrapper UI
+Collapsible sidebar overlay for ANY managed app. Provides dev tools without interfering with the managed application.
+
+**Features:**
+- Quick login panel (switch test users)
+- Jira ticket info panel
+- Environment info
+- Collapsible, resizable
+- Keyboard shortcut: `Ctrl+Shift+P`
+
+**Implementation:** HTML injection via nginx reverse proxy or iframe approach.
+
+### link/ - Adapter Layer
+Framework-agnostic data navigation between soleprint and managed apps.
+
+**Pattern:**
+```
+Managed App (DB) ←── link adapters ──→ Soleprint (Station tools)
+```
+
+**Endpoints:**
+- `GET /health` - Health check
+- `GET /api/queries` - List available queries
+- `GET /api/navigate?query=<name>` - Execute predefined query
+- `GET /api/navigate?entity=<type>&id=<id>` - Entity navigation
+
+**JSON Contract:**
+```json
+{
+  "nodes": [{"id": "User_123", "type": "User", "label": "john", "data": {...}}],
+  "edges": [{"from": "User_123", "to": "Pet_456", "label": "owns"}],
+  "summary": {"title": "User #123", "fields": {...}}
+}
+```
+
+### soleprint/ - Docker Configs
+Docker compose files for running soleprint services (hub, artery, atlas, station).
+
+**Environment Variables:**
+- `SOLEPRINT_BARE_PATH` - Path to soleprint source (gen/)
+- `DEPLOYMENT_NAME` - Container prefix
+- `NETWORK_NAME` - Docker network name
+- `SOLEPRINT_PORT`, `ARTERY_PORT`, `ATLAS_PORT`, `STATION_PORT`
+
+## How It Works
+
+1. **ctrl/** sets environment variables for orchestration
+2. **soleprint/** docker configs use those vars to mount code and expose ports
+3. **link/** connects to managed app's database via adapters
+4. **sbwrapper/** overlays UI on managed app via nginx injection
+
+The managed project is never modified - it runs with its own defaults, mainroom just provides the orchestration layer on top.
+
+## Ports
+
+| Service | Port |
+|---------|------|
+| Soleprint Hub | 12000 |
+| Artery | 12001 |
+| Atlas | 12002 |
+| Station | 12003 |
+| Link | 8100 |
+
+## Adding a New Managed Room
+
+1. Create adapter in `link/adapters/` (implement BaseAdapter)
+2. Configure `sbwrapper/config.json` with room-specific users, Jira ticket, etc.
+3. Set env vars in ctrl scripts pointing to managed app
+4. Run `./ctrl/start.sh`
+
+## Worktrees
+
+Feature development:
+- `/home/mariano/wdir/wts/spr/sbwrapper` - Sidebar wrapper development
+- `/home/mariano/wdir/wts/spr/databrowse` - Data browser tool
+
+## External References
+
+| What | Location |
+|------|----------|
+| Soleprint source | `../` (parent directory) |
+| Amar backend | `/home/mariano/wdir/ama/amar_django_back` |
+| Amar frontend | `/home/mariano/wdir/ama/amar_frontend` |
+| Core nest (legacy) | `/home/mariano/wdir/ama/core_nest` |