soleprint/mainroom/CLAUDE.md

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.

./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:

{
  "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