# 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` |