BERT Application Overview

Base Environment for Re-tooled Technology

BERT is Path2Response’s unified backend and frontend application platform. It’s a TypeScript monorepo containing AWS CDK infrastructure, a React frontend, and an API generation layer that maintains synchronized contracts between frontend and backend.

Origin & Naming

Named: August 2023 Submitted by: Wells Selection: Executive team vote following company-wide naming contest

Name Inspiration

1. Albert Einstein — Championed the pursuit of a unified field theory, merging “seemingly un-mergable knowledge of the universe into a new paradigm, facilitating all kinds of good new pursuits/iterations and breakthroughs.”

2. Sesame Street — Bert (short for Albert) enables a naming convention for related tools: Ernie, Big Bird, Oscar, etc.

Purpose

BERT serves as the consolidation target for legacy systems and provides:

• Job Management - 25+ job types for data processing workflows
• Model Runs - Data science model execution and monitoring
• Order Fulfillment - End-to-end order processing workflows
• Jira Integration - Bidirectional sync with Jira for operations
• Reporting & Dashboards - Business intelligence and metrics
• Data Management - Client, title, and audience management

Target Users: Data Scientists, Operations, Developers, Stakeholders

Migration Status

BERT incorporates and will incorporate the following internal applications:

Order App Migration

Order App functionality has been migrated to BERT. The legacy orders deployment remains operational while final functionality is ported:

Architecture

Monorepo Structure

/bert/
├── api-generation/        # API contract generation engine (TypeScript)
├── cdk/                   # AWS CDK infrastructure & Lambda functions
├── react-frontend/        # React SPA frontend
├── scripts/               # Deployment & utility scripts
├── common-shared/         # Shared types (symlinked to react-frontend)
└── package.json           # Root workspace orchestration

Version: 335.0.0-SNAPSHOT Node Requirements: Node ~24, npm ~11

Technology Stack

Core Components

1. CDK Backend (/cdk/)

AWS CDK infrastructure-as-code containing Lambda functions and serverless orchestration.

Entry Point: bin/bert-app.ts

Two CDK Stacks:

• BertAppStack - Application infrastructure
• BertAppCodePipelineStack - CI/CD pipeline

Primary Constructs:

API Endpoints: 38+ namespaces in /cdk/api/proxy-mongo-backed-readonly/endpoints/:

2. React Frontend (/react-frontend/)

Single Page Application built with React and Material-UI.

Entry Point: src/index.tsx

Application Providers:

• Redux store
• AWS configuration
• Cognito authentication
• User preferences
• Alerts & notifications
• Dark mode theming

44 Page Routes including:

• Dashboards, Queue, Scheduler
• Orders, Fulfillments, Shipments
• Digital Audiences, Title Management
• Recency Analysis, Model Runs
• Admin, Preferences, Alerts
• API Debug (developers)
• Jira Sync Status

Component Organization:

3. API Generation (/api-generation/)

Maintains single source of truth for API contracts, preventing frontend/backend type mismatches.

Workflow:

1. Define - API contract in react-frontend/src/common-shared/api/definitions/
2. Generate - Run npm run generate from root
3. Generated Artifacts:
   • common-shared/api/gen/ - Shared types & validation
   • react-frontend/src/lib/api/gen/ - Frontend API client
   • cdk/api/proxy-mongo-backed-readonly/gen/ - Backend routing
4. Implement - Lambda handler at cdk/api/.../endpoints/{namespace}/{function}/handler.ts

Infrastructure

Authentication

• Cognito User Pool with Google OIDC social login
• JWT tokens for API authorization
• Cognito App Client tied to CloudFront

Networking

• CloudFront - CDN for frontend (OAI-protected S3)
• API Gateway - REST API with Cognito authorizer
• WAF - Web Application Firewall (VPN CIDR restricted)
• VPC - Private Lambda subnets whitelisted on MongoDB Atlas

Data Storage

• MongoDB Atlas - Primary database (external)
• EFS - Elastic File System for Lambda file processing
• S3 - Frontend hosting + caching

Async Processing

• SQS FIFO Queues - Background job processing
• EventBridge - Scheduled tasks (cron)
• Step Functions - Workflow orchestration

Monitoring

• CloudWatch Logs - API and Lambda execution
• CloudWatch Alarms - Operational alerts
• Slack Integration - Pipeline notifications

Server Deployments

Development Workflows

Build & Deploy (Full)

npm run reinstall-full    # Full reinstall + lint + build
npm run build             # Build all layers
npm run test              # Run all tests
npm run synth             # Generate CloudFormation
npm run deploy            # Build and deploy to AWS

Local Frontend Development

npm run deploy-local-dev  # Gets aws_config.json from deployed stack
cd react-frontend/
npm start                 # Dev server on localhost:3000

Frontend connects to deployed backend - fast UI iteration without CDK deploy.

Adding a New API

1. Define contract in react-frontend/src/common-shared/api/definitions/{namespace}/{fn}.ts
2. Run npm run generate from root
3. Implement handler at cdk/api/.../endpoints/{namespace}/{fn}/handler.ts
4. Frontend uses: import { fn } from "@lib/api/gen/..."

Branch-Based Deployment

Each Git branch deploys as a separate CloudFormation stack:

• Push to feature-xyz → deploys BertAppStack-feature-xyz
• Separate URL, separate resources
• Clean up via cdk destroy when done

Configuration

AWS Secrets (Secrets Manager)

Frontend Config (aws_config.json)

Injected at deployment with stack outputs:

{
  "DEPLOY_STACK_ID": "...",
  "MAINTENANCE_MODE": false,
  "COGNITO_AUTH_BASE_URL": "...",
  "API_BASE_URL": "https://...execute-api.../prod/",
  "BRANCH_NAME": "...",
  "CLOUDFRONT_URL": "..."
}

Key Integrations

Related Documentation

• Dashboards Overview - Legacy system with migration plan
• Data Tools Overview - Legacy data processing
• Project Inventory - Complete P2R codebase inventory
• Tools and Systems - Overview of all P2R tools
• Path2Acquisition Flow - How BERT modules fit in the data flow

Important Notes

• Type Safety - Full end-to-end TypeScript from API definitions through Lambda implementations
• Branch Isolation - Each branch deploys as separate stack (clean up unused branches to control costs)
• MongoDB Atlas - Requires VPN/whitelisted IPs for Lambda access
• Memory Requirements - TypeScript compilation needs 4GB allocation
• Test Coverage - 90% threshold enforced
• Shiny → DRAX - Legacy Shiny Reports have been ported to DRAX reports

Source: /Users/mpelikan/Documents/code/p2r/bert (README.md, cdk/README.md, react-frontend/README.md, api-generation/README.md, .amazonq/rules/memory-bank/) Documentation created: 2026-01-24