Bast AI Platform Architecture¶
Document Purpose¶
This document defines the complete platform architecture for Bast AI, covering the service hierarchy from Environment to Organization to CAT, including infrastructure setup, UI integration, and operational workflows.
Table of Contents¶
- Service Hierarchy Overview
- Environment Layer (ENV)
- Organization Layer (ORG)
- CAT Layer
- User Roles and Access
- Infrastructure on DuploCloud/AWS
- Data Architecture (HIPAA/SOC2)
- UI Integration Flows
- Service Creation Workflows
- Monitoring and Observability
- Compliance Requirements
Service Hierarchy Overview¶
Three-Tier Service Model¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ENVIRONMENT (ENV) │
│ One deployment environment (dev, demo, prod) │
│ Contains: Shared infrastructure, UI services, platform services │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
│ │ ORGANIZATION (ORG/Tenant) │ │
│ │ One per customer/organization │ │
│ │ Contains: org-services, org data, org configurations │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ CAT │ │ │
│ │ │ One per use case within an org │ │ │
│ │ │ Contains: cat-runtime, CAT OS, Knowledge Domains, Agent Pool │ │ │
│ │ │ │ │ │
│ │ │ Components: │ │ │
│ │ │ - 1 CAT OS (execution ontology) │ │ │
│ │ │ - N Knowledge Domains │ │ │
│ │ │ - 1 Agent Pool │ │ │
│ │ └──────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Cardinality Summary¶
| Parent | Child | Relationship |
|---|---|---|
| ENV | ORG | 1 : N (one env has many orgs) |
| ORG | CAT | 1 : N (one org has many CATs) |
| ORG | CAT OS | 1 : N (one org has many CAT OSs) |
| ORG | Knowledge Domain | 1 : N (one org has many knowledge domains) |
| ORG | Agent Pool | 1 : N (one org has many agent pools) |
| CAT | CAT OS | 1 : 1 (one CAT uses one CAT OS) |
| CAT | Knowledge Domain | 1 : N (one CAT uses many knowledge domains) |
| CAT | Agent Pool | 1 : 1 (one CAT uses one agent pool) |
Environment Layer (ENV)¶
Definition¶
An Environment is a complete deployment of the Bast AI platform, isolated from other environments. Each environment contains shared infrastructure and services that support multiple organizations.
Environment Types¶
| Environment | Purpose | Branch | Stability | Infrastructure |
|---|---|---|---|---|
| dev | Development, testing | dev |
May be unstable | dev-shared |
| demo | Customer demos, UAT | main |
Should be stable | demo-shared |
| prod | Production workloads | main (tagged) |
Must be stable | prod-shared |
DuploCloud Tenant Structure¶
Each environment has a shared tenant for platform services and org-specific tenants for organization services:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DUPLOCLOUD TENANT STRUCTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ DEV ENVIRONMENT (Infrastructure: dev-shared) │
│ ──────────────────────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SHARED TENANT: dev-shared │ │
│ │ │ │
│ │ Services: │ │
│ │ - dev-admin-ui (Platform Admin, CAT Builder UI) │ │
│ │ - dev-chat-ui (End User Chat UI) │ │
│ │ - dev-bff (Backend-for-Frontend) │ │
│ │ - platform-api (Platform management + Authentication) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ ORG TENANT: │ │ ORG TENANT: │ │ ORG TENANT: │ │
│ │ dev-bastai │ │ dev-craigh │ │ dev-{org} │ │
│ │ │ │ │ │ │ │
│ │ - org-services │ │ - org-services │ │ - org-services │ │
│ │ - cat-runtime-* │ │ - cat-runtime-* │ │ - cat-runtime-* │ │
│ │ - monitoring │ │ - monitoring │ │ - monitoring │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ DEMO ENVIRONMENT (Infrastructure: demo-shared) │
│ ─────────────────────────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SHARED TENANT: demo-shared │ │
│ │ │ │
│ │ Services: │ │
│ │ - demo-admin-ui, demo-chat-ui, demo-bff │ │
│ │ - platform-api (includes auth) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ demo-bastai │ │ demo-craigh │ │ demo-{org} │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ PROD ENVIRONMENT (Infrastructure: prod-shared) │
│ ─────────────────────────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SHARED TENANT: prod-shared │ │
│ │ │ │
│ │ Services: │ │
│ │ - admin-ui, chat-ui, bff │ │
│ │ - platform-api (includes auth) │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ prod-bastai │ │ prod-craigh │ │ prod-{org} │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Naming Convention¶
| Component | Pattern | Dev Example | Demo Example | Prod Example |
|---|---|---|---|---|
| Infrastructure | {env}-shared | dev-shared | demo-shared | prod-shared |
| Shared Tenant | {env}-shared | dev-shared | demo-shared | prod-shared |
| Org Tenant | {env}-{org} | dev-bastai | demo-bastai | prod-bastai |
| UI Services | {env}-{service} | dev-admin-ui | demo-admin-ui | admin-ui |
Services Per Environment¶
1. Infrastructure Services (AWS)¶
| Service | Purpose | Scope | Count |
|---|---|---|---|
| MongoDB Atlas | Primary database | See Data Architecture | Per org (prod) / Shared (dev) |
| Redis/ElastiCache | Caching, sessions | Per environment | 1 cluster |
| S3 Buckets | Object storage | Per org | 1 per org |
| ECR | Container registry | Per environment | 1 |
| ALB/Ingress | Load balancing | Per tenant | 1+ per tenant |
| Route53 | DNS | Global | 1 hosted zone |
| Secrets Manager | Secrets storage | Per environment | 1 |
Note: MongoDB Atlas architecture follows HIPAA/SOC2 compliance requirements with separate clusters per production org. See Data Architecture for details.
2. Shared Tenant Services ({env}-shared)¶
These services run in the shared tenant and serve all organizations:
| Service | Port | Purpose | Dev Name | Demo Name | Prod Name |
|---|---|---|---|---|---|
| admin-ui | 9090 | Org management, CAT Builder | dev-admin-ui | demo-admin-ui | admin-ui |
| chat-ui | 9090 | End-user chat interface | dev-chat-ui | demo-chat-ui | chat-ui |
| bff | 4000 | Backend-for-Frontend, API gateway | dev-bff | demo-bff | bff |
| platform-api | 8080 | Platform management, org provisioning, authentication | platform-api | platform-api | platform-api |
3. Org Tenant Services ({env}-{org})¶
These services run in each org's dedicated tenant:
| Service | Port | Purpose | Count per Org |
|---|---|---|---|
| org-services | 8080 | Org-level APIs (CAT Builder, Security, Analytics) | 1 |
| cat-runtime-{type} | 9090 | CAT execution runtime | 1 per CAT |
| monitoring | 9100 | Prometheus, Grafana (org-scoped metrics) | 1 |
Environment Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DEMO ENVIRONMENT (Infrastructure: demo-shared) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ INFRASTRUCTURE SERVICES (AWS) ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
│ │ │ MongoDB │ │ Redis │ │ S3 │ │ ECR │ │ Route53 │ ││
│ │ │ (Atlas) │ │(Elasti- │ │ Buckets │ │ Registry │ │ DNS │ ││
│ │ │ │ │ Cache) │ │ │ │ │ │ │ ││
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ SHARED TENANT: demo-shared ││
│ │ ││
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────────────────┐││
│ │ │demo-admin- │ │demo-chat- │ │ demo-bff │ │ platform-api │││
│ │ │ ui │ │ ui │ │ │ │ (org mgmt + auth) │││
│ │ │ :9090 │ │ :9090 │ │ :4000 │ │ :8080 │││
│ │ └────────────┘ └────────────┘ └────────────┘ └─────────────────────────┘││
│ │ ││
│ │ Routes requests to org tenants based on JWT/org_id ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌──────────────────────────────┼──────────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ ORG TENANT: │ │ ORG TENANT: │ │ ORG TENANT: │ │
│ │ demo-bastai │ │ demo-craigh │ │ demo-{org} │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │
│ │ │ org-services │ │ │ │ org-services │ │ │ │ org-services │ │ │
│ │ │ :8080 │ │ │ │ :8080 │ │ │ │ :8080 │ │ │
│ │ └─────────────────┘ │ │ └─────────────────┘ │ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │
│ │ │cat-runtime- │ │ │ │cat-runtime- │ │ │ │cat-runtime- │ │ │
│ │ │ advisor :9090 │ │ │ │ helper :9090 │ │ │ │ {cat} :9090 │ │ │
│ │ │cat-runtime- │ │ │ │ │ │ │ │ │ │ │
│ │ │ support :9090 │ │ │ │ │ │ │ │ │ │ │
│ │ └─────────────────┘ │ │ └─────────────────┘ │ │ └─────────────────┘ │ │
│ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │
│ │ │ monitoring │ │ │ │ monitoring │ │ │ │ monitoring │ │ │
│ │ │ :9100 │ │ │ │ :9100 │ │ │ │ :9100 │ │ │
│ │ └─────────────────┘ │ │ └─────────────────┘ │ │ └─────────────────┘ │ │
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Organization Layer (ORG)¶
Definition¶
An Organization (also called Tenant) represents a customer or business unit within an environment. Each organization has isolated data and configurations but shares platform infrastructure.
Services Per Organization¶
| Service | Port | Purpose | Count |
|---|---|---|---|
| org-services | 8080 | Org-level APIs (CAT Builder, Security, Analytics) | 1 per org |
Organization Data Entities¶
| Entity | Description | Storage |
|---|---|---|
| Organization Config | Org settings, branding, features | MongoDB |
| Users | Org users, roles, permissions | MongoDB + Platform API (Auth) |
| CAT OS Configs | Execution ontology definitions | MongoDB |
| Knowledge Domains | Knowledge base configurations | MongoDB + Vector DB |
| Agent Pools | Agent configurations and pools | MongoDB |
| Themes | Visual appearance and branding configurations | MongoDB |
| CATs | CAT configurations | MongoDB |
Organization Infrastructure Model¶
The Platform API stores deployment tracking information for each organization:
OrganizationInDB
└── infrastructure: InfrastructureConfig
├── tenant: DuploCloudTenantConfig
│ ├── tenant_name: str # e.g., "dev-acme-corp"
│ ├── tenant_id: str # DuploCloud UUID
│ ├── infrastructure_name: str # e.g., "nonprod" (same as dev-shared)
│ ├── plan_id: str # e.g., "dev-shared"
│ └── status: DeploymentStatus # pending, deploying, running, etc.
│
├── mongodb: MongoDBConfig
│ ├── database_name: str # e.g., "acme-corp_data"
│ └── mongodb_uri: str # Connection string
│
├── org_services: ServiceDeployment # One per org
│ ├── service_name: str # DuploCloud service name
│ ├── image: str # Docker image
│ ├── image_tag: str # Version tag
│ ├── status: DeploymentStatus
│ ├── replicas: int
│ ├── internal_endpoint: str # Internal URL
│ └── env_vars: dict # Non-sensitive env vars
│
└── cat_runtimes: List[CATRuntimeDeployment] # Multiple per org
├── cat_id: str # CAT ID
├── cat_uuid: str # e.g., "PREFIX-ABC123"
├── service_name: str # DuploCloud service name
├── image: str # CAT runtime image
├── status: DeploymentStatus
├── replicas: int
└── internal_endpoint: str
Environment Variables for Platform API:
| Variable | Description | Example |
|---|---|---|
PLATFORM_MONGODB_URI |
MongoDB connection string for Platform API | See below |
PORT |
API port (optional, default: 8080) | 8080 |
DUPLO_HOST |
DuploCloud host URL | https://<duplocloud-host> |
DUPLO_TOKEN |
DuploCloud API token | <token> |
Platform MongoDB Connection Strings:
| Environment | Connection String |
|---|---|
| Local Dev | mongodb+srv://<user>:<password>@<cluster>.mongodb.net/bast_platform?retryWrites=true&w=majority |
| Dev | mongodb+srv://<user>:<password>@<cluster>.mongodb.net/bast_platform?retryWrites=true&w=majority |
Note: Database name for Platform API is always
bast_platform.
Environment Variables for org-services:
| Variable | Description | Example |
|---|---|---|
ORG_ID |
Organization ID (MongoDB ObjectId) | 678e5903c5e17b32d40d1234 |
ORG_SLUG |
Organization slug (for DB naming) | acme-corp |
ORG_MONGODB_URI |
MongoDB connection string | mongodb+srv://<user>:<password>@<cluster>.mongodb.net/ |
Database Naming Convention:
| Environment | Database Name | Example |
|---|---|---|
| Dev | {org_slug}_data |
acme-corp_data |
| Demo | {org_slug}_data |
acme-corp_data |
| Prod | {org_slug}_data |
acme-corp_data |
Collections within each org database: cats, cat_os, knowledge_domains, agent_pools, themes
Organization Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ORGANIZATION: bastai │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ ORG SERVICES ││
│ │ ┌─────────────────────────────────────────────────────────────────────┐ ││
│ │ │ org-services │ ││
│ │ │ (ORG_NAME=bastai) │ ││
│ │ │ Port: 8080 │ ││
│ │ │ │ ││
│ │ │ APIs: │ ││
│ │ │ - /api/v1/cat-builder/* (CAT OS, Knowledge, Agent Pools, CATs) │ ││
│ │ │ - /api/v1/security/* (AuthZ, permissions) │ ││
│ │ │ - /api/v1/analytics/* (usage, metrics) │ ││
│ │ │ - /api/v1/org/* (org settings, users) │ ││
│ │ └─────────────────────────────────────────────────────────────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ ORG CONFIGURATIONS (MongoDB) ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││
│ │ │ CAT OS │ │ Knowledge │ │ Agent │ │ CATs │ ││
│ │ │ Configs │ │ Domains │ │ Pools │ │ │ ││
│ │ │ │ │ │ │ │ │ │ ││
│ │ │ - advisor-os│ │ - products │ │ - gpt4-pool │ │ - advisor │ ││
│ │ │ - support-os│ │ - policies │ │ - claude- │ │ - support │ ││
│ │ │ - sales-os │ │ - faqs │ │ pool │ │ - sales │ ││
│ │ │ │ │ - manuals │ │ │ │ │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ CAT RUNTIME SERVICES ││
│ │ ││
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││
│ │ │ cat-runtime- │ │ cat-runtime- │ │ cat-runtime- │ ││
│ │ │ advisor │ │ support │ │ sales │ ││
│ │ │ │ │ │ │ │ ││
│ │ │ CAT_TYPE=advisor│ │ CAT_TYPE=support│ │ CAT_TYPE=sales │ ││
│ │ │ Port: 9090 │ │ Port: 9090 │ │ Port: 9090 │ ││
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ MONITORING (Per-Org) ││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────┐ ││
│ │ │ Prometheus + Grafana │ ││
│ │ │ Port: 9100 │ ││
│ │ │ │ ││
│ │ │ Metrics: │ ││
│ │ │ - CAT runtime performance │ ││
│ │ │ - org-services API latency │ ││
│ │ │ - Knowledge retrieval metrics │ ││
│ │ │ - Agent pool utilization │ ││
│ │ └─────────────────────────────────────────────────────────────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
CAT Layer¶
Definition¶
A CAT (Conversational AI Thing) is a specific AI assistant configuration within an organization. Each CAT has its own runtime service and is composed of reusable components (CAT OS, Knowledge Domains, Agent Pool).
CAT Components¶
| Component | Relationship | Purpose |
|---|---|---|
| CAT OS | 1:1 | Execution ontology - defines how the CAT behaves |
| Knowledge Domains | 1:N | Knowledge bases the CAT can access |
| Agent Pool | 1:1 | LLM and agent configurations |
| Theme | 1:1 (optional) | Visual appearance and branding configuration |
CAT Runtime Service¶
Each CAT gets its own cat-runtime service instance:
| Service | Port | Environment Variables |
|---|---|---|
cat-runtime-{cat_type} |
9090 | ORG_NAME, CAT_TYPE, MONGODB_URI, OPENAI_API_KEY, DVC_REGISTRY_URL |
CAT Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CAT: advisor │
│ ORG: bastai │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ cat-runtime-advisor ││
│ │ (Kubernetes Service) ││
│ │ ││
│ │ Environment: ││
│ │ - ORG_NAME=bastai ││
│ │ - CAT_TYPE=advisor ││
│ │ - MONGODB_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/ ││
│ │ - OPENAI_API_KEY=sk-... ││
│ │ - DVC_REGISTRY_URL=s3://... ││
│ │ ││
│ │ Endpoints: ││
│ │ - POST /api/v1/cat/chat ││
│ │ - GET /api/v1/cat/chat/history ││
│ │ - GET /api/v1/cat/chat/conversations ││
│ │ - POST /api/v1/feedback/send ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ Loads configuration at startup │
│ │ │
│ ┌──────────────────────────────────────┼──────────────────────────────────────┐│
│ │ ▼ ││
│ │ ┌─────────────────┐ ┌─────────────────────────────┐ ┌─────────────────┐ ││
│ │ │ CAT OS │ │ Knowledge Domains │ │ Agent Pool │ ││
│ │ │ (1:1) │ │ (1:N) │ │ (1:1) │ ││
│ │ │ │ │ │ │ │ ││
│ │ │ advisor-os │ │ - products (hybrid search) │ │ gpt4-pool │ ││
│ │ │ │ │ - policies (vector) │ │ │ ││
│ │ │ Defines: │ │ - faqs (text search) │ │ Defines: │ ││
│ │ │ - Intents │ │ │ │ - Model (GPT-4) │ ││
│ │ │ - Workflows │ │ Each domain has: │ │ - Temperature │ ││
│ │ │ - Behaviors │ │ - Document store │ │ - Max tokens │ ││
│ │ │ - Guardrails │ │ - Vector embeddings │ │ - Fallbacks │ ││
│ │ │ │ │ - Search config │ │ │ ││
│ │ └─────────────────┘ └─────────────────────────────┘ └─────────────────┘ ││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ ││
│ │ │ Theme (1:1 optional) │ ││
│ │ │ │ ││
│ │ │ advisor-theme │ ││
│ │ │ │ ││
│ │ │ Defines: │ ││
│ │ │ - Colors (primary, secondary, accent, background, text, etc.) │ ││
│ │ │ - Typography (font family) │ ││
│ │ │ - Radius (corner roundness) │ ││
│ │ │ - Shadow depth │ ││
│ │ │ - Button style (filled/outline/ghost) │ ││
│ │ │ - Background style (flat/gradient) │ ││
│ │ │ - CAT avatar │ ││
│ │ │ - Logo URL │ ││
│ │ │ - Brand text │ ││
│ │ └─────────────────────────────────────────────────────────────────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
User Roles and Access¶
Role Hierarchy¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ USER ROLES │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PLATFORM LEVEL ││
│ │ ┌─────────────────┐ ││
│ │ │ Platform Admin │ - Manage environments ││
│ │ │ │ - Create/delete organizations ││
│ │ │ │ - Platform-wide settings ││
│ │ │ │ - View all orgs ││
│ │ └─────────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ ORGANIZATION LEVEL ││
│ │ ┌─────────────────┐ ┌─────────────────┐ ││
│ │ │ Org Admin │ │ CAT Builder │ ││
│ │ │ (Super-user) │ │ (Super-user) │ ││
│ │ │ │ │ │ ││
│ │ │ - Manage org │ │ - Create CAT OS │ ││
│ │ │ - Manage users │ │ - Create KDs │ ││
│ │ │ - View analytics│ │ - Create Agents │ ││
│ │ │ - All CAT access│ │ - Create CATs │ ││
│ │ └─────────────────┘ └─────────────────┘ ││
│ │ ││
│ │ UI: admin-ui (https://admin.bast.ai) ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ CAT LEVEL ││
│ │ ┌─────────────────┐ ││
│ │ │ End User │ ││
│ │ │ (Normal user) │ ││
│ │ │ │ ││
│ │ │ - Chat with CAT │ ││
│ │ │ - View history │ ││
│ │ │ - Send feedback │ ││
│ │ └─────────────────┘ ││
│ │ ││
│ │ UI: chat-ui (https://chat.bast.ai) ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
UI to Role Mapping¶
| UI | Target Users | Capabilities |
|---|---|---|
| admin-ui | Platform Admin, Org Admin, CAT Builder | Org management, CAT configuration, analytics |
| chat-ui | End Users | Chat with CATs, view history, feedback |
Infrastructure on DuploCloud/AWS¶
DuploCloud Architecture¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DUPLOCLOUD / AWS │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ AWS ACCOUNT ││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────────┐││
│ │ │ DUPLOCLOUD INFRASTRUCTURES │││
│ │ │ │││
│ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │││
│ │ │ │ dev-shared │ │ demo-shared │ │ prod-shared │ │││
│ │ │ │ (Dev) │ │ (Demo) │ │ (Prod) │ │││
│ │ │ │ │ │ │ │ │ │││
│ │ │ │ - VPC │ │ - VPC │ │ - VPC │ │││
│ │ │ │ - EKS Cluster │ │ - EKS Cluster │ │ - EKS Cluster │ │││
│ │ │ │ - ALB/Ingress │ │ - ALB/Ingress │ │ - ALB/Ingress │ │││
│ │ │ │ - IAM/IRSA │ │ - IAM/IRSA │ │ - IAM/IRSA │ │││
│ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │││
│ │ │ │││
│ │ └─────────────────────────────────────────────────────────────────────────┘││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────────┐││
│ │ │ DEV TENANTS (dev-shared) │││
│ │ │ │││
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │││
│ │ │ │ dev-shared │ │ dev-bastai │ │ dev-craigh │ │││
│ │ │ │ (shared svc)│ │ (org svc) │ │ (org svc) │ │││
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │││
│ │ │ │││
│ │ └─────────────────────────────────────────────────────────────────────────┘││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────────┐││
│ │ │ DEMO TENANTS (demo-shared) │││
│ │ │ │││
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │││
│ │ │ │ demo-shared │ │ demo-bastai │ │ demo-craigh │ │││
│ │ │ │ (shared svc)│ │ (org svc) │ │ (org svc) │ │││
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │││
│ │ │ │││
│ │ └─────────────────────────────────────────────────────────────────────────┘││
│ │ ││
│ │ ┌─────────────────────────────────────────────────────────────────────────┐││
│ │ │ PROD TENANTS (prod-shared) │││
│ │ │ │││
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │││
│ │ │ │ prod-shared │ │ prod-bastai │ │ prod-craigh │ │││
│ │ │ │ (shared svc)│ │ (org svc) │ │ (org svc) │ │││
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │││
│ │ │ │││
│ │ └─────────────────────────────────────────────────────────────────────────┘││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ EXTERNAL SERVICES ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││
│ │ │ MongoDB │ │ OpenAI │ │ WorkOS │ │ S3/DVC │ ││
│ │ │ Atlas │ │ API │ │ Auth │ │ Registry │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
DuploCloud Infrastructure & Tenant Strategy¶
| Infrastructure | Environment | Purpose |
|---|---|---|
| dev-shared | Dev | Development infrastructure |
| demo-shared | Demo | Demo/UAT infrastructure |
| prod-shared | Prod | Production infrastructure (us-east-1) |
| Tenant | Infrastructure | Type | Services |
|---|---|---|---|
| dev-shared | dev-shared | Shared | UI services, platform services |
| dev-bastai | dev-shared | Org | org-services, cat-runtime-* |
| dev-craigh | dev-shared | Org | org-services, cat-runtime-* |
| demo-shared | demo-shared | Shared | UI services, platform services |
| demo-bastai | demo-shared | Org | org-services, cat-runtime-* |
| demo-craigh | demo-shared | Org | org-services, cat-runtime-* |
| prod-shared | prod-shared | Shared | UI services, platform services |
| prod-bastai | prod-shared | Org | org-services, cat-runtime-* |
| prod-craigh | prod-shared | Org | org-services, cat-runtime-* |
AWS Resources per Environment¶
| Resource | Dev (dev-shared) | Demo (demo-shared) | Prod (prod-shared) |
|---|---|---|---|
| EKS Cluster | 1 | 1 | 1 |
| ECR Repositories | Shared across all | Shared across all | Shared across all |
| S3 Buckets | 1 per org | 1 per org | 1 per org |
| MongoDB Cluster | 1 shared (bast-nonprod) | 1 shared (bast-demo) | 1 per org (prod-{org}) |
| Redis/ElastiCache | 1 shared | 1 shared | 1 per org |
| ALB/Ingress | 1 per tenant | 1 per tenant | 1 per tenant |
| Secrets Manager | 1 | 1 | 1 |
Data Architecture (HIPAA/SOC2)¶
Overview¶
To meet HIPAA and SOC2 compliance requirements, the platform uses a hybrid MongoDB architecture: - Non-Production: Shared cluster (no PHI/PII) - Production: Dedicated cluster per organization (PHI/PII isolation)
MongoDB Atlas Architecture¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ MONGODB ATLAS ARCHITECTURE │
│ (HIPAA/SOC2 Compliant) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ DEV ENVIRONMENT (No PHI/PII) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Shared Cluster: bast-nonprod │ │ │
│ │ │ Tier: M10 (development) │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ DB: np_bastai│ │ DB: np_craigh│ │ DB: dev_{org}│ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ Requirements: │ │ │
│ │ │ - NO PHI/PII data │ │ │
│ │ │ - Synthetic/anonymized data only │ │ │
│ │ │ - VPC peering to dev-shared infrastructure │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ DEMO ENVIRONMENT (No PHI/PII) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Shared Cluster: bast-demo │ │ │
│ │ │ Tier: M10/M30 (demo) │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ │DB: demo_bastai│ │DB: demo_craigh│ │DB: demo_{org}│ │ │ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ Requirements: │ │ │
│ │ │ - NO PHI/PII data (use synthetic data for demos) │ │ │
│ │ │ - Customer-facing demos │ │ │
│ │ │ - VPC peering to demo-shared infrastructure │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ PROD ENVIRONMENT (PHI/PII - HIPAA Compliant) │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Cluster: │ │ Cluster: │ │ Cluster: │ │ │
│ │ │ prod-bastai │ │ prod-craigh │ │ prod-{org} │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Tier: M30+ │ │ Tier: M30+ │ │ Tier: M30+ │ │ │
│ │ │ (HIPAA eligible)│ │ (HIPAA eligible)│ │ (HIPAA eligible)│ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Features: │ │ Features: │ │ Features: │ │ │
│ │ │ - Dedicated │ │ - Dedicated │ │ - Dedicated │ │ │
│ │ │ - BAA signed │ │ - BAA signed │ │ - BAA signed │ │ │
│ │ │ - Encryption │ │ - Encryption │ │ - Encryption │ │ │
│ │ │ - Audit logs │ │ - Audit logs │ │ - Audit logs │ │ │
│ │ │ - BYOK option │ │ - BYOK option │ │ - BYOK option │ │ │
│ │ │ - VPC peering │ │ - VPC peering │ │ - VPC peering │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │
│ │ Each production cluster has: │ │
│ │ - Dedicated resources (no noisy neighbor) │ │
│ │ - Isolated network (VPC peering to prod-shared infrastructure) │ │
│ │ - Independent backup/restore │ │
│ │ - Org-specific connection string │ │
│ │ - Audit logging enabled │ │
│ │ - BAA signed with MongoDB Atlas │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
MongoDB Cluster Requirements by Environment¶
| Environment | Cluster Name | Cluster Type | Tier | PHI/PII | BAA Required | Encryption |
|---|---|---|---|---|---|---|
| Dev | bast-nonprod | Shared (all orgs) | M10 | No | No | TLS + At-rest |
| Demo | bast-demo | Shared (all orgs) | M10/M30 | No (synthetic) | No | TLS + At-rest |
| Prod | prod-{org} | Dedicated per Org | M30+ | Yes | Yes | TLS + At-rest + BYOK |
Connection String Management¶
Each environment/org has its own MongoDB connection string stored in AWS Secrets Manager:
| Secret Name | Description | Used By |
|---|---|---|
bast/dev/mongodb/shared |
Shared dev cluster (bast-nonprod) | dev-{org} services |
bast/demo/mongodb/shared |
Shared demo cluster (bast-demo) | demo-{org} services |
bast/prod/mongodb/{org} |
Org-specific prod cluster | prod-{org} services |
Examples:
# Dev Environment (shared cluster, separate databases)
bast/dev/mongodb/shared → mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
# Demo Environment (shared cluster, separate databases)
bast/demo/mongodb/shared → mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
# Prod Environment (dedicated cluster per org)
bast/prod/mongodb/bastai → mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
bast/prod/mongodb/craigh → mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
Database Selection:
- Dev: Services connect to bast-nonprod cluster, use database dev_{org} (e.g., np_bastai)
- Demo: Services connect to bast-demo cluster, use database demo_{org} (e.g., demo_bastai)
- Prod: Services connect to dedicated prod-{org} cluster, use default database
Data Isolation per Org (Production)¶
Each production org cluster contains these collections:
| Collection | Description |
|---|---|
organizations |
Org configuration |
users |
Org users and roles |
cats |
CAT configurations |
cat_os |
CAT OS definitions |
knowledge_domains |
Knowledge domain configs |
agent_pools |
Agent pool configurations |
themes |
Theme/branding configurations |
conversations |
Chat conversations (PHI) |
feedback |
User feedback |
analytics |
Usage analytics |
audit_logs |
Security audit trail |
UI Integration Flows¶
Flow 1: Organization Creation (Platform Admin)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ORGANIZATION CREATION FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Platform │ │ admin- │ │platform- │ │ DuploCloud│ │
│ │ Admin │ │ ui │ │ api │ │ API │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ │ 1. Login │ │ │ │
│ │───────────────>│ │ │ │
│ │ │ 2. Create Org │ │ │
│ │ │ Request │ │ │
│ │ │───────────────>│ │ │
│ │ │ │ │ │
│ │ │ │ 3. Provision │ │
│ │ │ │ Resources │ │
│ │ │ │───────────────>│ │
│ │ │ │ │ │
│ │ │ │ 3a. Create │ │
│ │ │ │ K8s Service │ │
│ │ │ │ (org-svc) │ │
│ │ │ │<───────────────│ │
│ │ │ │ │ │
│ │ │ 4. Create DB │ │ │
│ │ │ Collections │ │ │
│ │ │ (MongoDB) │ │ │
│ │ │ │ │ │
│ │ │ 5. Create S3 │ │ │
│ │ │ Bucket │ │ │
│ │ │ │ │ │
│ │ │ 6. Return │ │ │
│ │ 7. Success │ Success │ │ │
│ │<───────────────│<───────────────│ │ │
│ │ │ │ │ │
│ │
│ RESULT: │
│ - org-services deployed (ORG_NAME=new-org) │
│ - MongoDB collections: organizations, users, cats, cat_os, etc. │
│ - S3 bucket: s3://bast-{env}-{org}-data │
│ - Org admin user created │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Flow 2: CAT OS / Knowledge Domain / Agent Pool Creation (CAT Builder)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CAT COMPONENT CREATION FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CAT │ │ admin- │ │ bff │ │ org- │ │
│ │ Builder │ │ ui │ │ │ │ services │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ │ 1. Login │ │ │ │
│ │ (org context) │ │ │ │
│ │───────────────>│ │ │ │
│ │ │ │ │ │
│ │ 2a. Create │ 3. tRPC Call │ 4. API Call │ │
│ │ CAT OS │───────────────>│───────────────>│ │
│ │───────────────>│ │ │ │
│ │ │ │ 5. Save to │ │
│ │ │ │ MongoDB │ │
│ │ │ │ (cat_os │ │
│ │ │ │ collection) │ │
│ │ │ │ │ │
│ │ 2b. Create │ │ │ │
│ │ Knowledge │───────────────>│───────────────>│ │
│ │ Domain │ │ │ │
│ │───────────────>│ │ 6. Save to │ │
│ │ │ │ MongoDB + │ │
│ │ │ │ Init Vector │ │
│ │ │ │ Index │ │
│ │ │ │ │ │
│ │ 2c. Create │ │ │ │
│ │ Agent Pool │───────────────>│───────────────>│ │
│ │───────────────>│ │ │ │
│ │ │ │ 7. Save to │ │
│ │ │ │ MongoDB │ │
│ │ │ │ (agent_pools │ │
│ │ │ │ collection) │ │
│ │ │ │ │ │
│ │
│ NOTE: These are configuration-only operations. │
│ No new services are deployed at this stage. │
│ Configurations are stored in MongoDB and used when CAT is created. │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Flow 3: CAT Creation (CAT Builder)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CAT CREATION FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CAT │ │ admin- │ │ bff │ │ org- │ │ DuploCloud│ │
│ │ Builder │ │ ui │ │ │ │ services │ │ API │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
│ │ 1. Create │ │ │ │ │
│ │ CAT Form │ │ │ │ │
│ │─────────────>│ │ │ │ │
│ │ │ │ │ │ │
│ │ Select: │ │ │ │ │
│ │ - CAT OS │ │ │ │ │
│ │ - Knowledge │ │ │ │ │
│ │ Domains │ │ │ │ │
│ │ - Agent Pool │ │ │ │ │
│ │ │ │ │ │ │
│ │ 2. Submit │ 3. tRPC │ 4. Create │ │ │
│ │─────────────>│─────────────>│─────────────>│ │ │
│ │ │ │ │ │ │
│ │ │ │ 5. Save CAT │ │ │
│ │ │ │ config to │ │ │
│ │ │ │ MongoDB │ │ │
│ │ │ │ │ │ │
│ │ │ │ 6. Trigger │ │ │
│ │ │ │ Service │ │ │
│ │ │ │ Creation │ │ │
│ │ │ │─────────────>│─────────────>│ │
│ │ │ │ │ │ │
│ │ │ │ │ 7. Create │ │
│ │ │ │ │ cat-runtime- │ │
│ │ │ │ │ {cat_type} │ │
│ │ │ │ │ │ │
│ │ │ │ │ Env vars: │ │
│ │ │ │ │ - ORG_NAME │ │
│ │ │ │ │ - CAT_TYPE │ │
│ │ │ │ │ - MONGODB_URI│ │
│ │ │ │ │ - OPENAI_KEY │ │
│ │ │ │ │ │ │
│ │ │ │ 8. Wait for │ │ │
│ │ │ │ healthy │ │ │
│ │ │ │<─────────────│<─────────────│ │
│ │ │ │ │ │ │
│ │ 9. Success │ │ │ │ │
│ │<─────────────│<─────────────│<─────────────│ │ │
│ │ │ │ │ │ │
│ │
│ RESULT: │
│ - CAT configuration saved to MongoDB │
│ - cat-runtime-{cat_type} service deployed │
│ - Service is ready to handle chat requests │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Flow 4: End User Chat (Normal User)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ END USER CHAT FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ End │ │ chat- │ │ bff │ │ cat- │ │ MongoDB │ │
│ │ User │ │ ui │ │ │ │ runtime │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
│ │ 1. Access │ │ │ │ │
│ │ chat.bast.ai │ │ │ │ │
│ │─────────────>│ │ │ │ │
│ │ │ │ │ │ │
│ │ 2. Login │ 3. Auth │ │ │ │
│ │ (org/CAT │ (WorkOS/ │ │ │ │
│ │ context) │ Google/MS) │ │ │ │
│ │─────────────>│─────────────>│ │ │ │
│ │ │ │ │ │ │
│ │ 4. Send │ 5. tRPC │ 6. Route to │ │ │
│ │ Message │ chat.send │ cat-runtime │ │ │
│ │─────────────>│─────────────>│─────────────>│ │ │
│ │ │ │ │ │ │
│ │ │ │ │ 7. Load CAT │ │
│ │ │ │ │ config │ │
│ │ │ │ │─────────────>│ │
│ │ │ │ │ │ │
│ │ │ │ │ 8. Process │ │
│ │ │ │ │ with: │ │
│ │ │ │ │ - CAT OS │ │
│ │ │ │ │ - Knowledge │ │
│ │ │ │ │ - Agents │ │
│ │ │ │ │ │ │
│ │ │ │ │ 9. Save │ │
│ │ │ │ │ conversation │ │
│ │ │ │ │─────────────>│ │
│ │ │ │ │ │ │
│ │ 10. Stream │ │ │ │ │
│ │ Response │<─────────────│<─────────────│ │ │
│ │<─────────────│ │ │ │ │
│ │ │ │ │ │ │
│ │
│ BFF ROUTING LOGIC: │
│ - Extract org_id and cat_type from JWT or request │
│ - Route to: cat-runtime-{cat_type} service │
│ - Each cat-runtime knows its ORG_NAME and CAT_TYPE from env vars │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Deployment Methods¶
Overview¶
The platform uses three deployment methods depending on the resource type:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DEPLOYMENT METHODS BY RESOURCE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ TERRAFORM (Infrastructure) CI/CD PIPELINE (Code Deployments) │
│ ───────────────────────────── ───────────────────────────────── │
│ • DuploCloud Infrastructure • cat-runtime image updates │
│ • Shared Tenants (dev-shared) • org-services image updates │
│ • AWS Services (S3, Secrets) • UI services (admin-ui, chat-ui, bff) │
│ • ECR Repositories • Rollbacks │
│ • Initial service templates • Triggered by: git merge/tag │
│ • Triggered by: manual CLI │
│ │
│ ADMIN UI (Self-Service) BOTH PATHS AVAILABLE │
│ ─────────────────────── ──────────────────── │
│ • Create Organization → deploys • Organization: Admin UI (standard) │
│ tenant + org-services or Terraform (custom) │
│ • Create CAT → deploys cat-runtime • Org Tenant: Admin UI or Terraform │
│ • CAT OS (config only) • CAT Runtime: Admin UI │
│ • Knowledge Domains (config only) │
│ • Agent Pools (config only) │
│ • User management │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Method Summary Table¶
| Resource | Admin UI | Terraform | CI/CD Pipeline | Notes |
|---|---|---|---|---|
| Infrastructure | - | Yes | - | One-time setup |
| Shared Tenant | - | Yes | - | {env}-shared |
| Organization | Yes | Yes | - | Admin UI recommended |
| Org Tenant | Auto | Yes | - | Created with org |
| org-services | Auto | Yes | Yes | Auto-deployed with org |
| CAT | Yes | - | - | Admin UI only |
| cat-runtime | Auto | - | Yes | Auto-deployed with CAT |
| CAT OS | Yes | - | - | Config only |
| Knowledge Domain | Yes | - | - | Config only |
| Agent Pool | Yes | - | - | Config only |
| UI Services | - | Yes | Yes | Pipeline for updates |
When to Use Each Method¶
| Scenario | Recommended Method |
|---|---|
| New environment setup | Terraform |
| Standard org onboarding | Admin UI |
| Custom org config (HIPAA/SOC2) | Terraform + Admin UI |
| Bulk org creation | Terraform |
| New CAT deployment | Admin UI |
| Code deployment/update | CI/CD Pipeline |
| Emergency rollback | Terraform or DuploCloud Console |
| Infrastructure scaling | Terraform |
Service Creation Workflows¶
Workflow 1: Environment Setup (One-time)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ENVIRONMENT SETUP CHECKLIST │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. AWS/DuploCloud Infrastructure │
│ [ ] Create DuploCloud infrastructure (bast-infra) │
│ [ ] Configure EKS cluster │
│ [ ] Set up VPC, subnets, security groups │
│ [ ] Create ECR repositories (bastai-cat, bast-org-services, bast-cat-runtime)│
│ [ ] Configure IAM roles and IRSA │
│ │
│ 2. DuploCloud Tenant (per environment) │
│ [ ] Create tenant (dev-bastai for dev, prod-bastai for demo/prod) │
│ [ ] Configure tenant network policies │
│ [ ] Set up ingress/ALB │
│ │
│ 3. External Services │
│ [ ] MongoDB Atlas cluster setup │
│ [ ] Create databases and initial collections │
│ [ ] Configure network peering (VPC to Atlas) │
│ [ ] Set up connection strings as secrets │
│ │
│ 4. Platform Services │
│ [ ] Deploy platform-api (includes auth endpoints) │
│ [ ] Configure external auth provider (WorkOS) if needed │
│ │
│ 5. UI Services (Shared) │
│ [ ] Deploy admin-ui (dev-admin-ui, demo-admin-ui) │
│ [ ] Deploy chat-ui (dev-chat-ui, demo-chat-ui) │
│ [ ] Deploy bff (dev-bff, demo-bff) │
│ [ ] Configure ingress routes │
│ │
│ 6. Bitbucket Pipeline Configuration │
│ [ ] Set repository variables (ECR, AWS, DUPLO, etc.) │
│ [ ] Test dev branch pipeline │
│ [ ] Test main branch pipeline │
│ │
│ 7. DNS and Certificates │
│ [ ] Configure Route53 records │
│ [ ] Set up SSL certificates (ACM) │
│ [ ] Verify HTTPS access to all services │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Workflow 2: User Registration, Login & Organization Access¶
This workflow defines how users register, authenticate, and gain access to organizations.
Implementation Status: ✅ Full Stack Complete
| Component | Status | Location |
|---|---|---|
| User DTOs | ✅ Complete | src/apis/platform/bast_platform_api/dto/user.py |
| Auth Service (JWT) | ✅ Complete | src/apis/platform/bast_platform_api/svc/auth_service.py |
| User Service | ✅ Complete | src/apis/platform/bast_platform_api/svc/user_service.py |
| Auth Router | ✅ Complete | src/apis/platform/bast_platform_api/bp/auth.py |
| OAuth Router (Google/Microsoft) | ✅ Complete | src/apis/platform/bast_platform_api/bp/oauth.py |
| BFF Auth Router | ✅ Complete | bast-admin-ui/apps/bff/src/trpc/auth.ts |
| Admin UI Auth Types | ✅ Complete | bast-admin-ui/apps/admin-ui/src/types/auth.ts |
| Admin UI Auth Context | ✅ Complete | bast-admin-ui/apps/admin-ui/src/lib/auth-context.tsx |
| Admin UI Login Screen | ✅ Complete | bast-admin-ui/apps/admin-ui/src/components/auth/LoginScreen.tsx |
| Admin UI Register Screen | ✅ Complete | bast-admin-ui/apps/admin-ui/src/components/auth/RegisterScreen.tsx |
| Admin UI Auth Callback | ✅ Complete | bast-admin-ui/apps/admin-ui/src/components/auth/AuthCallback.tsx |
Implemented Endpoints:
| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/v1/platform/auth/register | POST | Register new user (with optional invite_token) |
| /api/v1/platform/auth/login | POST | Login, returns JWT access + refresh tokens |
| /api/v1/platform/auth/refresh | POST | Refresh access token |
| /api/v1/platform/auth/me | GET | Get current user info (requires Bearer token) |
| /api/v1/platform/auth/password/change | POST | Change password |
| /api/v1/platform/auth/invitations/{token} | GET | Get invitation details |
| /api/v1/platform/auth/invitations/{token}/accept | POST | Accept invitation |
OAuth Endpoints (Sign in with Google/Microsoft):
| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/v1/platform/auth/oauth/google/auth | GET | Initiate Google OAuth flow (redirects to Google) |
| /api/v1/platform/auth/oauth/google/callback | GET | Google OAuth callback (creates user, redirects to frontend) |
| /api/v1/platform/auth/oauth/microsoft/auth | GET | Initiate Microsoft OAuth flow (redirects to Microsoft) |
| /api/v1/platform/auth/oauth/microsoft/callback | GET | Microsoft OAuth callback (creates user, redirects to frontend) |
| /api/v1/platform/auth/oauth/exchange-token | POST | Exchange OAuth session token for JWT tokens |
OAuth Flow:
1. Frontend redirects user to /auth/oauth/google/auth or /auth/oauth/microsoft/auth
2. User authenticates with OAuth provider
3. Provider redirects to callback URL with authorization code
4. Platform API creates/updates user, generates session token
5. Redirects to frontend /auth/callback?session_token=<token>
6. Frontend calls /auth/oauth/exchange-token with session token
7. Returns JWT tokens + user info (same format as login)
JWT Token Configuration: - Access Token: 15 minutes expiry - Refresh Token: 7 days expiry - Algorithm: HS256 - Claims: sub (user_id), email, name, orgs, current_org
BFF Auth Router (tRPC):
The BFF provides a tRPC router that proxies auth requests to the Platform API:
| Procedure | Type | Description |
|---|---|---|
auth.register |
Mutation | Register new user (proxies to Platform API) |
auth.login |
Mutation | Email/password login |
auth.refresh |
Mutation | Refresh JWT access token |
auth.me |
Query | Get current user info |
auth.changePassword |
Mutation | Change user password |
auth.getInvitation |
Query | Get invitation details by token |
auth.acceptInvitation |
Mutation | Accept organization invitation |
auth.getGoogleAuthUrl |
Query | Get Google OAuth redirect URL |
auth.getMicrosoftAuthUrl |
Query | Get Microsoft OAuth redirect URL |
auth.exchangeOAuthToken |
Mutation | Exchange OAuth session token for JWT |
Admin UI Auth Architecture:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ADMIN UI AUTH ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ main.tsx │
│ ───────── │
│ <TRPCProvider> │
│ <AuthProvider> ← Auth context wraps entire app │
│ <App /> │
│ </AuthProvider> │
│ </TRPCProvider> │
│ │
│ AuthProvider (lib/auth-context.tsx) │
│ ─────────────────────────────────── │
│ - Manages auth state (user, tokens, currentOrg, isAuthenticated) │
│ - Persists tokens/user to localStorage │
│ - Provides methods: login, register, logout, loginWithGoogle, │
│ loginWithMicrosoft, exchangeOAuthToken, │
│ setCurrentOrg, refreshTokens │
│ │
│ Auth Screens (components/auth/) │
│ ─────────────────────────────── │
│ - LoginScreen.tsx Email/password + Google/Microsoft OAuth buttons │
│ - RegisterScreen.tsx Account creation with password validation │
│ - AuthCallback.tsx OAuth callback handler (exchanges session token) │
│ │
│ Auth Types (types/auth.ts) │
│ ───────────────────────── │
│ - User, TokenPair, OrgMembership │
│ - AuthState, AuthContextType │
│ - LoginInput, RegisterInput │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Auth State Flow:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ AUTH STATE FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. App Start │
│ ───────── │
│ AuthProvider checks localStorage for existing tokens/user │
│ If valid → isAuthenticated = true, show dashboard │
│ If invalid → isAuthenticated = false, show LoginScreen │
│ │
│ 2. Email/Password Login │
│ ───────────────────── │
│ LoginScreen → useAuth().login() → BFF auth.login → Platform API │
│ On success: store tokens + user in localStorage, set isAuthenticated │
│ │
│ 3. OAuth Login │
│ ─────────── │
│ a) User clicks "Continue with Google/Microsoft" │
│ b) loginWithGoogle/Microsoft() redirects to Platform API OAuth endpoint │
│ c) Platform API redirects to provider (Google/Microsoft) │
│ d) User authenticates, provider redirects to callback │
│ e) Platform API creates user, generates session token │
│ f) Redirects to Admin UI /auth/callback?session_token=xxx │
│ g) AuthCallback component calls exchangeOAuthToken() │
│ h) BFF auth.exchangeOAuthToken → Platform API │
│ i) On success: store tokens, set isAuthenticated │
│ │
│ 4. Token Storage │
│ ───────────── │
│ localStorage keys: │
│ - bast_auth_tokens: { access_token, refresh_token, token_type, expires_in }│
│ - bast_auth_user: { id, email, name, status, organizations, ... } │
│ │
│ 5. Logout │
│ ────── │
│ useAuth().logout() → clear localStorage → set isAuthenticated = false │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ USER REGISTRATION & AUTHENTICATION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 1: New User Registration ││
│ │ ───────────────────────────── ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Admin UI │────>│ BFF │────>│ Platform API │ ││
│ │ │ /register │ │ │ │ POST /auth/register │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Input: │ ││
│ │ • email ▼ ││
│ │ • password ┌─────────────────┐ ││
│ │ • name │ MongoDB │ ││
│ │ │ users (status: │ ││
│ │ Process: │ "pending" or │ ││
│ │ 1. Validate email uniqueness │ "active") │ ││
│ │ 2. Hash password (bcrypt) └─────────────────┘ ││
│ │ 3. Create user with status="active" ││
│ │ 4. Generate JWT tokens ││
│ │ 5. User has NO organizations yet ││
│ │ ││
│ │ Result: ││
│ │ • User logged in but with empty organizations[] ││
│ │ • Redirect to "Create Organization" screen ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 2: User Login ││
│ │ ───────────────── ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Admin UI │────>│ BFF │────>│ Platform API │ ││
│ │ │ /login │ │ │ │ POST /auth/login │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Input: │ ││
│ │ • email ▼ ││
│ │ • password ┌─────────────────┐ ││
│ │ │ Validate creds │ ││
│ │ Process: │ Generate JWT │ ││
│ │ 1. Validate credentials │ Update last_ │ ││
│ │ 2. Generate access + refresh tokens │ login │ ││
│ │ 3. Check user.organizations[] └─────────────────┘ ││
│ │ ││
│ │ Routing based on organizations: ││
│ │ ││
│ │ ┌──────────────────────────────────────────────────────────────────────┐ ││
│ │ │ IF organizations.length == 0: │ ││
│ │ │ → Redirect to "Create Organization" screen │ ││
│ │ │ → User CANNOT access any other features until org created │ ││
│ │ │ │ ││
│ │ │ IF organizations.length == 1: │ ││
│ │ │ → Auto-select that organization │ ││
│ │ │ → Redirect to Dashboard │ ││
│ │ │ │ ││
│ │ │ IF organizations.length > 1: │ ││
│ │ │ → Show "Select Organization" screen │ ││
│ │ │ → User picks org, then redirect to Dashboard │ ││
│ │ └──────────────────────────────────────────────────────────────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 3: First Organization Creation (User becomes Owner) ││
│ │ ──────────────────────────────────────────────────────── ││
│ │ ││
│ │ Trigger: User with 0 organizations clicks "Create Organization" ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Admin UI │────>│ BFF │────>│ Platform API │ ││
│ │ │ Create Org │ │ │ │ POST /organizations │ ││
│ │ │ Form │ │ │ │ (with user_id from JWT) │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Input: │ ││
│ │ • org name ▼ ││
│ │ • org slug ┌─────────────────┐ ││
│ │ • environment (dev/demo/prod) │ Platform API │ ││
│ │ • (user_id from JWT automatically) │ Operations: │ ││
│ │ │ │ ││
│ │ Process: │ 1. Create org │ ││
│ │ 1. Create organization record │ 2. Add user as │ ││
│ │ 2. Add creating user as "owner" │ owner │ ││
│ │ 3. Trigger provisioning if auto_prov │ 3. Provision │ ││
│ │ 4. Update user.organizations[] │ (optional) │ ││
│ │ 5. Issue new JWT with org access └─────────────────┘ ││
│ │ ││
│ │ User Document Update: ││
│ │ ```json ││
│ │ { ││
│ │ "organizations": [ ││
│ │ { ││
│ │ "org_id": "<new_org_id>", ││
│ │ "role": "owner", ││
│ │ "permissions": ["*"], // Full access ││
│ │ "joined_at": "<timestamp>" ││
│ │ } ││
│ │ ] ││
│ │ } ││
│ │ ``` ││
│ │ ││
│ │ Result: User now has org access → Redirect to Dashboard ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TEAM MEMBER INVITATION WORKFLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 4: Invite Team Member ││
│ │ ───────────────────────────── ││
│ │ ││
│ │ Trigger: Org owner/admin invites a user by email ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Admin UI │────>│ BFF │────>│ Platform API │ ││
│ │ │ Team Page │ │ │ │ POST /orgs/{id}/invitations│ ││
│ │ │ "Invite" │ │ │ │ │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Input: │ ││
│ │ • invitee_email ▼ ││
│ │ • role (admin/member/viewer) ┌─────────────────┐ ││
│ │ │ Check if user │ ││
│ │ │ exists │ ││
│ │ └────────┬────────┘ ││
│ │ │ ││
│ │ ┌──────────────────────────────┴──────────────────────┐ ││
│ │ ▼ ▼ ││
│ │ ┌─────────────────┐ ┌─────────────┐ ││
│ │ │ User EXISTS │ │User NOT │ ││
│ │ │ │ │EXISTS │ ││
│ │ └────────┬────────┘ └──────┬──────┘ ││
│ │ │ │ ││
│ │ ▼ ▼ ││
│ │ ┌─────────────────┐ ┌─────────────┐ ││
│ │ │ Create │ │Create │ ││
│ │ │ invitation │ │invitation │ ││
│ │ │ (status: │ │(status: │ ││
│ │ │ pending) │ │ pending) │ ││
│ │ └────────┬────────┘ └──────┬──────┘ ││
│ │ │ │ ││
│ │ ▼ ▼ ││
│ │ ┌─────────────────┐ ┌─────────────┐ ││
│ │ │ Send email: │ │Send email: │ ││
│ │ │ "You've been │ │"You've been │ ││
│ │ │ invited to │ │invited to │ ││
│ │ │ {org}. Login │ │{org}. │ ││
│ │ │ to accept." │ │Register to │ ││
│ │ │ │ │join." │ ││
│ │ │ Link: /login │ │Link: │ ││
│ │ │ ?invite={token} │ │/register │ ││
│ │ │ │ │?invite= │ ││
│ │ │ │ │{token} │ ││
│ │ └─────────────────┘ └─────────────┘ ││
│ │ ││
│ │ Invitation Document (MongoDB: invitations): ││
│ │ ```json ││
│ │ { ││
│ │ "_id": ObjectId, ││
│ │ "org_id": ObjectId, ││
│ │ "email": "invitee@example.com", ││
│ │ "role": "member", ││
│ │ "token": "<secure_random_token>", ││
│ │ "status": "pending", // pending | accepted | expired | revoked ││
│ │ "invited_by": ObjectId, // user who sent invite ││
│ │ "created_at": datetime, ││
│ │ "expires_at": datetime, // 7 days from creation ││
│ │ "accepted_at": datetime // null until accepted ││
│ │ } ││
│ │ ``` ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 5a: Accept Invitation (Existing User) ││
│ │ ─────────────────────────────────────────── ││
│ │ ││
│ │ ┌───────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Email Link │────>│ Admin UI │────>│ Platform API │ ││
│ │ │ /login?invite │ │ (Login) │ │ POST /invitations/{token}/ │ ││
│ │ │ ={token} │ │ │ │ accept │ ││
│ │ └───────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Process: │ ││
│ │ 1. User logs in normally ▼ ││
│ │ 2. Detect ?invite={token} param ┌─────────────────┐ ││
│ │ 3. Validate token (not expired) │ 1. Validate │ ││
│ │ 4. Show "Accept invitation" prompt │ token │ ││
│ │ 5. On accept: │ 2. Add org to │ ││
│ │ - Add org to user.organizations[] │ user │ ││
│ │ - Mark invitation as accepted │ 3. Update │ ││
│ │ - Issue new JWT with org access │ invitation │ ││
│ │ └─────────────────┘ ││
│ │ ││
│ │ User Document Update: ││
│ │ ```json ││
│ │ { ││
│ │ "organizations": [ ││
│ │ { "org_id": "existing_org", "role": "owner" }, ││
│ │ { "org_id": "invited_org", "role": "member", "joined_at": "..." } ││
│ │ ] ││
│ │ } ││
│ │ ``` ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ FLOW 5b: Accept Invitation (New User - Register First) ││
│ │ ────────────────────────────────────────────────────── ││
│ │ ││
│ │ ┌───────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ ││
│ │ │ Email Link │────>│ Admin UI │────>│ Platform API │ ││
│ │ │/register? │ │ (Register) │ │ POST /auth/register │ ││
│ │ │invite={token} │ │ │ │ (with invite_token) │ ││
│ │ └───────────────┘ └─────────────┘ └─────────────────────────────┘ ││
│ │ │ ││
│ │ Process: │ ││
│ │ 1. User fills registration form ▼ ││
│ │ 2. Email pre-filled from invitation ┌─────────────────┐ ││
│ │ 3. Submit with invite_token │ 1. Create user │ ││
│ │ 4. Create user account │ 2. Auto-accept │ ││
│ │ 5. Auto-accept invitation │ invitation │ ││
│ │ 6. Add org to user.organizations[] │ 3. Add org │ ││
│ │ 7. Issue JWT with org access │ 4. Issue JWT │ ││
│ │ └─────────────────┘ ││
│ │ ││
│ │ New User Document: ││
│ │ ```json ││
│ │ { ││
│ │ "email": "invitee@example.com", ││
│ │ "name": "New User", ││
│ │ "status": "active", ││
│ │ "organizations": [ ││
│ │ { "org_id": "invited_org", "role": "member", "joined_at": "..." } ││
│ │ ] ││
│ │ } ││
│ │ ``` ││
│ │ ││
│ │ Result: New user directly lands in Dashboard (has org access) ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ACCESS CONTROL SUMMARY │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ User State Transitions: │
│ ───────────────────────── │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Guest │───>│ Registered │───>│ Has Org │───>│ Active │ │
│ │ (No Auth) │ │ (No Org) │ │ Access │ │ User │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │ │
│ │ │ │ │ │
│ Can only: Can only: Can access: Full access: │
│ - Register - Create org - Dashboard - All features │
│ - Login - Accept invite - Org settings - Team mgmt │
│ - View "no org" - CAT Builder - Billing │
│ screen │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ Roles & Permissions (per Organization) ││
│ │ ────────────────────────────────────── ││
│ │ ││
│ │ ┌────────────┬─────────────────────────────────────────────────────────┐ ││
│ │ │ Role │ Permissions │ ││
│ │ ├────────────┼─────────────────────────────────────────────────────────┤ ││
│ │ │ owner │ All permissions + delete org + transfer ownership │ ││
│ │ │ admin │ Team management + CAT CRUD + settings │ ││
│ │ │ member │ CAT read/write + knowledge management │ ││
│ │ │ viewer │ Read-only access to CATs and analytics │ ││
│ │ └────────────┴─────────────────────────────────────────────────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ Protected Routes (Admin UI): │
│ ──────────────────────────── │
│ │
│ Public (no auth): Auth Required: Org Required: │
│ - /login - /create-org - /dashboard │
│ - /register - /select-org - /cat-builder/* │
│ - /forgot-password - /invitations - /team │
│ - /reset-password - /settings │
│ - /analytics │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Workflow 3: New Organization Onboarding¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ NEW ORGANIZATION ONBOARDING │
│ (HIPAA/SOC2 Compliant) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Trigger: Platform Admin creates org via admin-ui │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PHASE 1: MongoDB Cluster Provisioning (Production Only) ││
│ │ ─────────────────────────────────────────────────────── ││
│ │ ││
│ │ 1. [ ] Create MongoDB Atlas cluster: prod-{org} ││
│ │ - Tier: M30 or higher (HIPAA eligible) ││
│ │ - Region: Same as DuploCloud tenant ││
│ │ - Encryption: At-rest enabled ││
│ │ ││
│ │ 2. [ ] Configure cluster security: ││
│ │ - [ ] Enable audit logging ││
│ │ - [ ] Configure IP allowlist (VPC peering) ││
│ │ - [ ] Create database user with least privilege ││
│ │ - [ ] Enable TLS 1.2+ enforcement ││
│ │ ││
│ │ 3. [ ] Sign BAA (Business Associate Agreement): ││
│ │ - [ ] MongoDB Atlas BAA for cluster ││
│ │ - [ ] Document BAA reference in org record ││
│ │ ││
│ │ 4. [ ] Set up VPC peering: ││
│ │ - [ ] Peer Atlas cluster to DuploCloud VPC ││
│ │ - [ ] Configure security groups ││
│ │ ││
│ │ 5. [ ] Store connection string: ││
│ │ - [ ] AWS Secrets Manager: bast/prod/mongodb/{org} ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PHASE 2: Database Setup ││
│ │ ────────────────────── ││
│ │ ││
│ │ 1. [ ] Create database collections: ││
│ │ - organizations ││
│ │ - users ││
│ │ - cats ││
│ │ - cat_os ││
│ │ - knowledge_domains ││
│ │ - agent_pools ││
│ │ - themes ││
│ │ - conversations ││
│ │ - feedback ││
│ │ - analytics ││
│ │ - audit_logs ││
│ │ ││
│ │ 2. [ ] Create indexes for performance ││
│ │ ││
│ │ 3. [ ] Initialize org record with: ││
│ │ - org_id, org_name ││
│ │ - baa_signed: true, baa_date: <date> ││
│ │ - compliance: ["HIPAA", "SOC2"] ││
│ │ - created_at, created_by ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PHASE 3: AWS Resources ││
│ │ ──────────────────── ││
│ │ ││
│ │ 1. [ ] Create S3 bucket: s3://bast-prod-{org}-data ││
│ │ - [ ] Enable encryption (SSE-S3 or SSE-KMS) ││
│ │ - [ ] Enable versioning ││
│ │ - [ ] Configure lifecycle policies ││
│ │ - [ ] Block public access ││
│ │ ││
│ │ 2. [ ] Create DuploCloud tenant: prod-{org} ││
│ │ - [ ] Configure namespace ││
│ │ - [ ] Set up ingress/ALB ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PHASE 4: Service Deployment ││
│ │ ────────────────────────── ││
│ │ ││
│ │ 1. [ ] Deploy org-services: ││
│ │ - Service name: org-services ││
│ │ - Env: ORG_ID={org_id} (MongoDB ObjectId) ││
│ │ - Env: ORG_SLUG={org_slug} (e.g., "acme-corp") ││
│ │ - Env: ORG_MONGODB_URI=<from secrets manager> ││
│ │ - Database: {org_slug}_data (e.g., "acme-corp_data") ││
│ │ ││
│ │ 2. [ ] Update org infrastructure record: ││
│ │ - Set tenant info (tenant_name, tenant_id, infrastructure_name) ││
│ │ - Set org_services deployment info ││
│ │ - Set mongodb_uri in infrastructure.mongodb ││
│ │ ││
│ │ 3. [ ] Verify deployment: ││
│ │ - [ ] Health check: /health returns 200 ││
│ │ - [ ] Info check: /info returns org_id, org_slug, databases ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ PHASE 5: User Setup ││
│ │ ───────────────── ││
│ │ ││
│ │ 1. [ ] Create org admin user: ││
│ │ - [ ] Add to auth service (WorkOS/Google/MS) ││
│ │ - [ ] Assign Org Admin role ││
│ │ - [ ] Add to org's users collection ││
│ │ ││
│ │ 2. [ ] Send welcome email: ││
│ │ - [ ] Login URL ││
│ │ - [ ] Initial setup instructions ││
│ │ - [ ] Security best practices ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ Verification Checklist: │
│ ─────────────────────── │
│ [ ] MongoDB cluster healthy and accessible │
│ [ ] BAA documentation complete │
│ [ ] org-services /health returns healthy │
│ [ ] Org admin can login to admin-ui │
│ [ ] Org admin sees empty CAT Builder dashboard │
│ [ ] Audit logging captures login event │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Workflow 2b: Non-Production Organization Setup¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ NON-PRODUCTION ORG SETUP (Dev/Demo) │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ For dev/demo environments - uses shared MongoDB cluster │
│ │
│ Steps: │
│ ────── │
│ 1. [ ] Create database in shared cluster: {org_slug}_data │
│ - Example: "acme-corp_data" for org slug "acme-corp" │
│ - Collections: cats, cat_os, knowledge_domains, agent_pools, themes │
│ │
│ 2. [ ] Create DuploCloud tenant: {env}-{org_slug} │
│ - Example: "dev-acme-corp" within nonprod infrastructure │
│ │
│ 3. [ ] Deploy org-services to org tenant: │
│ - Env: ORG_ID={org_id} │
│ - Env: ORG_SLUG={org_slug} │
│ - Env: ORG_MONGODB_URI=mongodb://shared-cluster/... │
│ │
│ 4. [ ] Update org infrastructure record in Platform API │
│ │
│ 5. [ ] Create test users │
│ │
│ IMPORTANT: │
│ - NO PHI/PII data in non-production │
│ - Use synthetic/anonymized data only │
│ - No BAA required │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Workflow 3: New CAT Deployment¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ NEW CAT DEPLOYMENT │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Trigger: CAT Builder creates CAT via admin-ui │
│ │
│ Prerequisites: │
│ ────────────── │
│ [ ] At least one CAT OS created │
│ [ ] At least one Knowledge Domain created (optional but recommended) │
│ [ ] At least one Agent Pool created │
│ │
│ Automated Steps: │
│ ───────────────── │
│ 1. [ ] Validate CAT configuration │
│ - CAT OS exists and is valid │
│ - Knowledge Domains exist (if specified) │
│ - Agent Pool exists │
│ 2. [ ] Save CAT config to MongoDB (cats collection) │
│ 3. [ ] Trigger cat-runtime service creation: │
│ - Service name: cat-runtime-{cat_type} │
│ - Image: bast-cat-runtime:latest │
│ - Env: ORG_NAME, CAT_TYPE, MONGODB_URI, OPENAI_API_KEY │
│ 4. [ ] Wait for service to be healthy │
│ 5. [ ] Update CAT status to "active" │
│ 6. [ ] Configure BFF routing (if dynamic) │
│ │
│ Service Creation (DuploCloud): │
│ ─────────────────────────────── │
│ ```bash │
│ cat <<'EOF' | duploctl service create --tenant {tenant} --file - │
│ { │
│ "Name": "cat-runtime-{cat_type}", │
│ "DockerImage": "{ecr}/bast-cat-runtime:latest", │
│ "AgentPlatform": 7, │
│ "Replicas": 1, │
│ "OtherDockerConfig": { │
│ "Env": [ │
│ {"Name": "ORG_NAME", "Value": "{org}"}, │
│ {"Name": "CAT_TYPE", "Value": "{cat_type}"}, │
│ {"Name": "MONGODB_URI", "Value": "..."}, │
│ {"Name": "OPENAI_API_KEY", "Value": "..."} │
│ ] │
│ } │
│ } │
│ EOF │
│ ``` │
│ │
│ Verification: │
│ ───────────── │
│ [ ] cat-runtime-{cat_type} /health returns healthy │
│ [ ] CAT appears in admin-ui CAT list │
│ [ ] End user can access CAT via chat-ui │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Monitoring and Observability¶
Monitoring Architecture¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ MONITORING ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ METRICS COLLECTION ││
│ │ ││
│ │ Services expose: ││
│ │ - /metrics (Prometheus format) ││
│ │ - /health (liveness) ││
│ │ - /ready (readiness) ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││
│ │ │ org-services│ │cat-runtime-*│ │ admin-ui │ │ chat-ui │ ││
│ │ │ :8080 │ │ :9090 │ │ :9090 │ │ :9090 │ ││
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ ││
│ │ │ │ │ │ ││
│ │ └────────────────┴────────────────┴────────────────┘ ││
│ │ │ ││
│ │ ▼ ││
│ │ ┌─────────────────┐ ││
│ │ │ Prometheus │ ││
│ │ │ (scraping) │ ││
│ │ └────────┬────────┘ ││
│ │ │ ││
│ │ ▼ ││
│ │ ┌─────────────────┐ ││
│ │ │ Grafana │ ││
│ │ │ (dashboards) │ ││
│ │ └─────────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ LOGGING ││
│ │ ││
│ │ All services log to stdout (JSON format) ││
│ │ ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││
│ │ │ CloudWatch │ or │ Datadog │ or │ ELK │ ││
│ │ │ Logs │ │ │ │ Stack │ ││
│ │ └─────────────┘ └─────────────┘ └─────────────┘ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐│
│ │ ALERTING ││
│ │ ││
│ │ Alert Rules: ││
│ │ - Service down (health check fails) ││
│ │ - High error rate (> 5% 5xx) ││
│ │ - High latency (p99 > 5s) ││
│ │ - Resource exhaustion (CPU > 80%, Memory > 80%) ││
│ │ ││
│ │ Channels: ││
│ │ - Slack ││
│ │ - PagerDuty ││
│ │ - Email ││
│ │ ││
│ └─────────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Key Metrics per Service¶
| Service | Key Metrics |
|---|---|
| org-services | Request rate, error rate, latency, DB connection pool |
| cat-runtime | Chat messages/sec, LLM latency, knowledge retrieval time |
| admin-ui | Page load time, API call latency, error rate |
| chat-ui | Message send latency, WebSocket connections, stream errors |
| bff | Request routing latency, upstream errors, connection pool |
Summary: Service Count Formula¶
Per Environment¶
| Component | Count |
|---|---|
| Shared Infrastructure | Fixed (MongoDB, Redis, S3, ECR, ALB) |
| Platform Services | 1 (platform-api with auth) |
| UI Services | 3 (admin-ui, chat-ui, bff) |
| Total Shared | ~6-8 services |
Per Organization¶
| Component | Count |
|---|---|
| org-services | 1 |
| monitoring | 1 (Prometheus + Grafana) |
| Total per Org | 2 services + cat-runtimes |
Per CAT¶
| Component | Count |
|---|---|
| cat-runtime-{type} | 1 |
| Total per CAT | 1 service |
Example: 3 Orgs with varying CATs¶
| Org | org-services | CAT Runtimes | Total |
|---|---|---|---|
| bastai | 1 | 3 (advisor, support, sales) | 4 |
| lurie | 1 | 2 (patient, scheduling) | 3 |
| acme | 1 | 1 (demo) | 2 |
| Org Total | 3 | 6 | 9 |
Grand Total: 8 shared + 9 org/CAT = 17 services
Compliance Requirements¶
HIPAA Compliance Checklist¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ HIPAA COMPLIANCE CHECKLIST │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Technical Safeguards: │
│ ───────────────────── │
│ [ ] Access Control │
│ - [ ] Unique user identification (user IDs) │
│ - [ ] Automatic logoff (session timeout) │
│ - [ ] Encryption at rest (MongoDB, S3) │
│ - [ ] Encryption in transit (TLS 1.2+) │
│ │
│ [ ] Audit Controls │
│ - [ ] MongoDB audit logging enabled │
│ - [ ] Application-level audit logs │
│ - [ ] CloudWatch/logging aggregation │
│ - [ ] Log retention (6+ years) │
│ │
│ [ ] Integrity Controls │
│ - [ ] Data validation on input │
│ - [ ] Checksums for data transfer │
│ │
│ [ ] Transmission Security │
│ - [ ] TLS 1.2+ for all connections │
│ - [ ] VPC peering (no public internet for DB) │
│ - [ ] API authentication (JWT/OAuth) │
│ │
│ Administrative Safeguards: │
│ ────────────────────────── │
│ [ ] BAA signed with: │
│ - [ ] MongoDB Atlas (per production cluster) │
│ - [ ] AWS │
│ - [ ] DuploCloud │
│ - [ ] OpenAI (if using for PHI) │
│ │
│ [ ] Workforce training documentation │
│ [ ] Security incident procedures │
│ [ ] Data backup and disaster recovery plan │
│ │
│ Physical Safeguards: │
│ ──────────────────── │
│ [ ] Cloud provider certifications (AWS, MongoDB Atlas) │
│ [ ] No on-premise PHI storage │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
SOC2 Compliance Checklist¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SOC2 COMPLIANCE CHECKLIST │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Security (Common Criteria): │
│ ─────────────────────────── │
│ [ ] Access control policies │
│ [ ] Network security (firewalls, VPC) │
│ [ ] Vulnerability management │
│ [ ] Security monitoring and alerting │
│ [ ] Incident response procedures │
│ │
│ Availability: │
│ ───────────── │
│ [ ] Uptime SLA defined (99.9%) │
│ [ ] Disaster recovery plan │
│ [ ] Backup procedures (daily, tested) │
│ [ ] Multi-AZ deployment │
│ │
│ Confidentiality: │
│ ──────────────── │
│ [ ] Data classification │
│ [ ] Encryption at rest and in transit │
│ [ ] Data retention policies │
│ [ ] Secure data disposal │
│ │
│ Processing Integrity: │
│ ───────────────────── │
│ [ ] Input validation │
│ [ ] Error handling │
│ [ ] Quality assurance processes │
│ │
│ Privacy: │
│ ──────── │
│ [ ] Privacy notice │
│ [ ] Consent management │
│ [ ] Data subject rights (access, deletion) │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
BAA Tracking¶
| Vendor | BAA Required | BAA Signed | Date | Reference |
|---|---|---|---|---|
| AWS | Yes | [ ] | - | - |
| MongoDB Atlas | Yes (per cluster) | [ ] | - | - |
| DuploCloud | Yes | [ ] | - | - |
| OpenAI | Conditional* | [ ] | - | - |
| WorkOS | Yes | [ ] | - | - |
*OpenAI BAA required only if PHI is sent to OpenAI APIs. Consider using Azure OpenAI with BAA for healthcare use cases.
Per-Organization Compliance Record¶
Each production org should have documentation for:
| Item | Description | Location |
|---|---|---|
| BAA Record | MongoDB Atlas BAA for org's cluster | org.baa_reference |
| Encryption Keys | KMS key ARN (if BYOK) | AWS Secrets Manager |
| Data Classification | PHI/PII data inventory | org.data_classification |
| Access Log | Who has access to org data | org.access_log |
| Audit Trail | Security events | audit_logs collection |
Document History¶
| Date | Author | Changes |
|---|---|---|
| 2026-01-10 | Claude | Initial architecture document |
| 2026-01-10 | Claude | Added HIPAA/SOC2 compliant MongoDB architecture (separate cluster per prod org) |
| 2026-01-10 | Claude | Updated org onboarding workflow with BAA and compliance phases |
| 2026-01-10 | Claude | Added Compliance Requirements section with HIPAA/SOC2 checklists |
| 2026-01-10 | Claude | Updated environment structure: dev-shared/demo-shared/prod-shared infrastructures |
| 2026-01-10 | Claude | Added shared tenant per env ({env}-shared) + org tenants ({env}-{org}) |
| 2026-01-10 | Claude | Updated MongoDB: bast-nonprod (dev), bast-demo (demo), prod-{org} (prod) |
| 2026-01-10 | Claude | Replaced np-poc with dev-shared infrastructure; standardized naming to {env}-shared pattern |
| 2026-01-10 | Claude | Added Deployment Methods section clarifying Terraform vs CI/CD vs Admin UI deployment paths |
| 2026-01-10 | Claude | Implemented Platform API Authentication: user DTOs, auth service (JWT/bcrypt), user service (CRUD, memberships, invitations), auth router with register/login/refresh/me endpoints |
| 2026-01-10 | Claude | Added OAuth support (Google/Microsoft Sign-In) to Platform API with oauth.py router, session token exchange flow |
| 2026-01-10 | Claude | Implemented Admin UI Authentication: BFF auth tRPC router (auth.ts), auth context (auth-context.tsx), auth types (auth.ts), LoginScreen with OAuth buttons, RegisterScreen with password validation, AuthCallback for OAuth flow handling |
| 2026-01-26 | Claude | Added Theme management to CAT model: Theme entity (1:N with Org, 1:1 optional with CAT), themes collection, theme_id field in CAT, ThemeConfig properties (colors, typography, radius, shadow, button_style, etc.) |