Skip to content

Admin Platform

  • Infra code: infra/admin/
  • Component code: components/admin_lambda/, components/admin_worker/

Internal admin dashboard for managing ecommerce search configurations, indexes, and accounts.

Architecture

graph TD
    A["Browser"] --> B["Cloudflare Worker (admin_worker, React SSR)"]
    B --> C["Admin API Gateway (HTTP v2, JWT auth)"]

    subgraph lambda["Admin Lambda (FastAPI)"]
        D["DDB tables"]
        E["Cloudflare KV"]
        F["Data Plane Gateways"]
    end

    C --> D
    C --> E
    C --> F

AWS Resources

Resource Name Pattern How to Inspect
Lambda {env}-AdminLambda Lambda
API Gateway {env}-AdminInternalApi (HTTP v2) API Gateway
DynamoDB {env}-IndexForksTable DynamoDB
Cloudflare {env}-admin-api worker Cloudflare

DynamoDB Tables (Owned)

IndexForksTable

  • pk (S): system_account_id
  • sk (S): FORK#{fork_id}
  • Tracks index fork operations (copy data between indexes).

DynamoDB Tables (Shared, Read/Write)

The admin Lambda also accesses tables owned by other stacks:

  • {env}-EcomIndexSettingsTable - Index configurations
  • {env}-EcomIndexQueryConfigsTable - Query config overrides
  • {env}-AgenticCachedQueriesTable - Cached agentic queries
  • {env}-EcomIndexerJobsTable - Sync job status
  • UsersAccountsTable - Account details (read-only)
  • {env}-MerchandisingTable - Merchandising rules (read-only)

Auth

The admin API uses Cloudflare Access JWT tokens:

  • Dev/Staging issuer: https://marqodev.cloudflareaccess.com
  • Prod issuer: https://marqo.cloudflareaccess.com

Key API Routes

All routes under /api/v1/:

Route Purpose
GET /accounts List all accounts with indexes
GET /accounts/{id} Account details
GET /admin/indexes List all indexes (paginated)
GET /admin/accounts/{id}/indexes/{name} Index settings
GET /admin/accounts/{id}/indexes/{name}/infra Infrastructure resources (SQS, DDB, KV links)
POST /accounts/{id}/indexes/{name}/query-configs Create query config overrides
POST /accounts/{id}/indexes/{name}/forks Create index fork
GET /admin/indexes/{id}/{name}/sync-jobs List sync jobs

S3 Integration

Reads static feature flags from {env}-cloud-controller bucket (feature_flags.json).

Typical Investigation Paths

Admin dashboard not loading:

  1. Check admin worker: npx wrangler tail {env}-admin-api
  2. Check API Gateway endpoint: aws apigatewayv2 get-apis
  3. Check admin Lambda logs: aws logs tail /aws/lambda/{env}-AdminLambda

Query configs not applying in search:

  1. Check query configs in DDB: query EcomIndexQueryConfigsTable
  2. Check Cloudflare KV (KV_QCFG namespace)
  3. Check search proxy is reading from the right KV namespace

Data plane calls failing:

  1. Admin Lambda calls data plane gateways via IAM auth
  2. Check DATA_PLANE_CELLS env var on the Lambda
  3. Test gateway directly: API Gateway