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 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
Adding New Features
Full Stack Feature
- Add API endpoint in
admin_lambda: - Create/update route in
routes/ - Add models in
models/ - Add service logic in
services/ -
Write tests
-
Add UI in
admin_worker: - Create/update route in
routes/ - Add components in
components/ - Add GatewayClient method if needed
-
Write tests
-
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