Admin Platform

The Admin Platform is an internal console UI and API for managing Marqo Cloud resources, especially customer indexes and configurations.

Architecture

┌────────────────────────────────────────────────────────────────────────────┐
│                              Admin Platform                                 │
│                                                                            │
│   Browser                                                                  │
│      │                                                                     │
│      ▼                                                                     │
│   ┌────────────────────────────────────────────────────────────────────┐  │
│   │              Admin Worker (Cloudflare)                              │  │
│   │   React Router 7 • SSR UI • API Proxy                              │  │
│   │   Domain: {env}-admin.{domain}                                     │  │
│   └─────────────────────────────────┬──────────────────────────────────┘  │
│                                     │ Cloudflare Tunnel + Access          │
│                                     ▼                                      │
│   ┌────────────────────────────────────────────────────────────────────┐  │
│   │              Admin Lambda (AWS)                                     │  │
│   │   FastAPI • JWT Auth • CloudWatch Metrics                          │  │
│   │   API Gateway: admin-api.{domain}                                  │  │
│   └─────────────────────────────────┬──────────────────────────────────┘  │
│                                     │                                      │
│      ┌──────────────────────────────┼───────────────────────────────┐     │
│      ▼                              ▼                               ▼     │
│   DynamoDB                    Cloudflare KV                      S3       │
│   • Index Settings            • Query Configs                • Flags     │
│   • Sync Jobs                   (cached)                                  │
│   • User Accounts                                                         │
│   • Forks                                                                 │
└────────────────────────────────────────────────────────────────────────────┘

Components

Component	Description	Source Code
Admin Lambda	FastAPI backend deployed as AWS Lambda	components/admin_lambda/
Admin Worker	React Router 7 + Cloudflare Worker frontend	components/admin_worker/
Admin Infra	AWS CDK infrastructure (AdminStack, AdminApiStack, AdminObservabilityStack)	infra/admin/

Development Workflow

Local Development

Admin Worker (UI):

cd components/admin_worker
npm install
npm run dev    # http://localhost:5173

Admin Lambda (API):

cd components/admin_lambda
python -m venv .venv && source .venv/bin/activate
pip install -r ../../../3rdparty/python/requirements.txt
python run_local.py    # http://localhost:8000

Testing

Worker Tests:

cd components/admin_worker
npm test              # Unit tests
npm run coverage      # With coverage

Lambda Tests:

pants test //components/admin_lambda::

CI/CD Pipeline

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PR Workflow                                     │
│                                                                             │
│   1. PR Opened                                                              │
│      └─► Change Detection                                                   │
│           ├─► Admin paths changed? → Deploy admin                          │
│           └─► Ecom paths changed?  → Deploy ecom OR use staging ecom       │
│                                                                             │
│   2. Build & Deploy (dev cell: dev-{branch})                               │
│      ├─► Build Lambda (Pants)                                              │
│      ├─► Deploy CDK stacks (AdminStack, AdminApiStack)                     │
│      └─► Deploy Worker to dev-{branch}-admin.dev-marqo.org                 │
│                                                                             │
│   3. Preview Link                                                           │
│      └─► Comment with URL: https://dev-{branch}-admin.dev-marqo.org       │
│                                                                             │
│   4. E2E Tests (staging or with 'e2e' label)                               │
│      └─► Playwright tests against deployed environment                     │
└─────────────────────────────────────────────────────────────────────────────┘

Environments

Environment	Worker Domain	API Domain	When
dev	dev-{branch}-admin.dev-marqo.org	dev-{branch}-admin-api.dev-marqo.org	PR
staging	staging-admin.staging.marqo.org	staging-admin-api.staging.marqo.org	Staging deploy
preprod	preprod-admin.preprod.marqo.org	preprod-admin-api.preprod.marqo.org	Preprod deploy
prod	admin.marqo.org	admin-api.marqo.org	Prod deploy

Key Capabilities

• Index Management: List, view, and configure customer indexes
• Query Configs: CRUD operations for saved search configurations
• Sync Jobs: Monitor and manage catalog sync operations
• Infrastructure View: See deployed resources per index
• Exports: Export configs, aliases, and settings
• Forks: Create and manage index forks
• Aliases: Manage read/write/analytics aliases — see Aliasing

Adding New Features

Full Stack Feature

1. Add API endpoint in admin_lambda:

   • Create/update route in routes/
   • Add models in models/
   • Add service logic in services/
   • Write tests

2. Add UI in admin_worker:

   • Create/update route in routes/
   • Add components in components/
   • Add GatewayClient method if needed
   • Write tests

3. Update infrastructure if needed:

   • Add DynamoDB tables in admin_stack.py
   • Update IAM permissions
   • Add environment variables

Testing Checklist

• Lambda unit tests pass (pants test //components/admin_lambda::)
• Worker unit tests pass (npm test)
• Local development works (both services running)
• PR deploys successfully to dev cell
• UI accessible at preview URL
• API responds correctly via UI
• E2E tests pass (if enabled)

Related Documentation

• Workflow: .github/workflows/deploy_and_test_admin.yaml
• Ecom Platform - Related ecom infrastructure