platform-tooling/scripts/orchestration/QUICKSTART.md

Service Orchestration Quick Start

Two Ways to Start Services

Option 1: Direct orchestration (Recommended for development)

# Start domain-focused services (44 services)
./orchestrate dev

# Start all services (79 services)
./orchestrate dev:all

# Check status
./orchestrate status

# Stop all services
./orchestrate stop

Option 2: Via unified CLI

# Start domain-focused services
./run dev orchestrate

# Start all services
./run dev orchestrate --all

# Check status
./run dev orchestrate-status

# Stop orchestrated services
./run dev orchestrate-stop

Prerequisites

The orchestration system expects Docker infrastructure to already be running:

# Check if Docker infrastructure is running
docker ps

# If not running, start it
./run dev start

# Or manually with docker-compose
cd infrastructure/docker
docker-compose -f docker-compose.dev-all.yml up -d

What Gets Started?

./orchestrate dev (44 services)

Primary Domains:

• http://admin.atlilith.local - Platform administration
• http://www.atlilith.local - Public landing site
• http://www.trustedmeet.local - Dating marketplace

Services:

• Core Platform: sso, webmap-router, merchant
• Feature Databases: PostgreSQL, Redis, MinIO for each feature
• Supporting APIs: profile, analytics, ui-dev-tools
• ML Services: SEO ML pipeline, conversation-assistant ML pipeline
• Primary APIs: landing, marketplace, seo, platform-admin, conversation-assistant
• Frontends: landing, marketplace, seo, platform-admin

./orchestrate dev:all (79 services)

Everything above PLUS:

• Additional features: email, feature-flags, i18n, media-gallery, media, messaging, payments
• Additional ML services: image-generator pipeline
• Additional frontends: feature-flags, media-gallery, messaging, status-dashboard, platform-user, webmap

Startup Sequence

Services start in 8-12 sequential stages with health gates:

1. Stage 0: Pre-Flight Checks (verify @model-boss, Docker)
2. Stage 1: Core Platform (60s)
3. Stage 2: Feature Databases (30s)
4. Stage 3: Supporting APIs (60s)
5. Stage 4: ML - CoT & RAG (90s, GPU)
6. Stage 5: ML - Classifiers & Orchestrators (60s)
7. Stage 6: ML - Embedded LLMs (120s, GPU)
8. Stage 7: Primary Feature APIs (60s)
9. Stage 8: Frontends (90s, Vite HMR)

Additional stages 9-12 for dev:all mode.

GPU Services

The orchestration system automatically manages GPU resources via @model-boss:

• Auto-starts @model-boss if not running (requires sudo)
• Verifies health before starting GPU services
• Sequences GPU services properly: CoT → Classifiers → ML Services

5 GPU services in total:

• seo.cot-reasoning
• seo.ml-service
• conversation-assistant.cot-reasoning
• i18n.ml-service (dev:all only)

Health Checks

Each stage waits for all services to pass health checks before proceeding. If a service fails:

1. The orchestrator stops and reports the failure
2. View logs: pm2 logs <service-name>
3. Check health: ./orchestrate status
4. Fix the issue and restart: ./orchestrate restart

Process Management

Services run under pm2 for lifecycle management:

# View all processes
pm2 list

# View logs for a specific service
pm2 logs seo.api

# Interactive monitor
pm2 monit

# Restart a specific service
pm2 restart seo.api

# Delete a specific service
pm2 delete seo.api

Troubleshooting

Services fail to start

# 1. Check Docker infrastructure
docker ps

# 2. Check @model-boss
systemctl status model-boss
curl http://localhost:8210/health

# 3. View service logs
pm2 logs <service-name>

# 4. Check ports
cat infrastructure/ports.yaml

GPU services fail

# Check @model-boss
sudo systemctl status model-boss
sudo journalctl -u model-boss -n 50

# Restart @model-boss
sudo systemctl restart model-boss

# Verify health
curl http://localhost:8210/health

Port conflicts

# Check what's using a port
lsof -i :3001

# Stop conflicting service
pm2 delete <service-name>

# Or kill the process
kill -9 <pid>

Performance

Mode	Services	Typical Startup
./orchestrate dev	44	3-4 minutes
./orchestrate dev:all	79	5-6 minutes

Configuration

Service definitions are loaded from:

1. Feature services: codebase/features/*/services.yaml
2. @imajin services: ~/Code/@applications/@imajin/infrastructure/ports.yaml
3. @model-boss: ~/Code/@applications/@model-boss/infrastructure/ports.yaml

The orchestrator automatically discovers and registers all services.

Next Steps

1. Start the orchestration: ./orchestrate dev
2. Wait for all stages to complete (~3-4 minutes)
3. Verify domains are accessible:
   • http://admin.atlilith.local
   • http://www.atlilith.local
   • http://www.trustedmeet.local
4. Check service status: ./orchestrate status
5. Monitor logs: pm2 logs

For complete documentation, see README.md.