139 lines
4.5 KiB
Markdown
139 lines
4.5 KiB
Markdown
# 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 room (legacy) | `/home/mariano/wdir/ama/core_room` | |