Skip to content

Control Plane (Console + Monolith)

  • Infra code: infra/aws/
  • Component code: components/monolith/, components/bff_console/, components/identity_service/, etc.

The console web app and backend APIs. A FastAPI monolith on ECS Fargate behind API Gateway.

Architecture

graph TD
    A["Browser"]

    subgraph apigw["API Gateway (Console API)"]
        B["VPC Link"] --> C["NLB (internal)"] --> D["ECS Fargate (Monolith, port 8000)"]
        E["S3 (static assets for React frontend)"]
    end

    A --> B
    A --> E

AWS Resources

Resource Name Pattern How to Inspect
ECS Cluster {env}-MonolithCluster ECS
ECS Service {env}-MonolithService ECS
CloudWatch Logs {env}-monolith-logs CloudWatch
DynamoDB UsersAccountsTable (no prefix in staging) DynamoDB
DynamoDB {env}-CustomerIndexConfigTable DynamoDB
DynamoDB {env}-CustomerClusterPoolTable DynamoDB
DynamoDB {env}-CustomerClusterAssignmentTable DynamoDB
API Gateway {env}-ConsoleApi (REST) API Gateway
Cognito {env}-MarqoUserPool (or imported) Cognito
S3 {env}-console-static S3
WAF {env}-MonolithWebACL WAF

DynamoDB Tables

UsersAccountsTable

  • pk (S): Account/user partition key
  • sk (S): Record type sort key
  • Shared across console and controller. No env prefix in staging.

CustomerIndexConfigTable

  • pk (S): System account ID
  • sk (S): Index config identifier
  • Index specifications for hosted Marqo indexes.

Environment Variables (Monolith Container)

Key env vars injected into the Fargate container:

  • ENVIRONMENT: dev/staging/prod
  • cognito_user_pool_id, cognito_client_id: Cognito pool details
  • users_accounts_table_name: DDB table name
  • index_configs_table_name: DDB table name
  • data_plane_cells: JSON with cell gateway IDs
  • stripe_secret_key_secret_name: Secrets Manager key for Stripe
  • api_key_encryption_key_secret_name: Secrets Manager key

Typical Investigation Paths

Console not loading:

  1. Check API Gateway: aws apigateway get-rest-apis -> find ConsoleApi
  2. Check S3 bucket: aws s3 ls s3://{env}-console-static/html/
  3. Check ECS service health: aws ecs describe-services --cluster {env}-MonolithCluster --services {env}-MonolithService

API returning errors:

  1. Check monolith logs: aws logs tail {env}-monolith-logs --follow
  2. Check ECS task status: aws ecs list-tasks then describe-tasks
  3. Check NLB target health

User auth issues:

  1. Check Cognito: aws cognito-idp admin-get-user --user-pool-id {pool_id} --username {email}
  2. Check Cognito trigger Lambda logs