📋 EPIC — Everyday Peak In Charge - Obsidian Developer Docs

Deep Technical Report & Architecture Documentation

Prepared for: Internship Reference
Date: May 2026
Codebase: Amazon Internal — Brazil Workspace Package

What is EPIC?
High-Level Architecture
System Components (5 Packages)
Data Models & Domain Objects
Database Architecture
REST API Reference
Event Readiness Workflow (Milestones)
Trigger System (Java Lambdas)
Notification & Messaging System
Infrastructure (CDK Stacks)
Frontend Architecture (React)
Traffic & Throttling System
Deployment Pipeline
Key Business Concepts Glossary
Developer Setup Cheatsheet

1. What is EPIC?

EPIC (Everyday Peak In Charge) is an Amazon-internal tool that helps engineering teams plan, manage, and execute capacity scaling for peak traffic events — like Prime Day, Black Friday, Holiday season, and BAU (Business As Usual) scaling.

Core Problem It Solves

Amazon services need to handle massive traffic spikes during events. Without coordination:

Services under-order hardware → crash during peak
Services over-order hardware → wasteful costs
Upstream/downstream service teams don’t communicate TPM (traffic) needs
No single view of readiness across hundreds of services

What EPIC Does

Without EPIC                          With EPIC
─────────────────────────────         ──────────────────────────────────────
❌ Manual spreadsheets                ✅ Central database of all fleets
❌ Email chains for TPM numbers       ✅ Automated gather/communicate TPM
❌ No hardware order tracking         ✅ Milestone tracking with deadlines
❌ Manual throttling updates          ✅ Automated throttle config push
❌ No readiness dashboard             ✅ Leadership dashboards + HOTW
❌ Services forget about descaling    ✅ Descale milestones & automation

Key Events EPIC Manages (Examples from Code)

Event ID	Event Name	Type
`PrimeDay21`	Prime Day 2021	Peak
`NewYearSale2025`	New Year Sale 2025	Peak
`NewYearSale2026`	New Year Sale 2026	Peak
`SPRINGSALE26`	Spring Sale 2026	Peak
`EUSPRINGSALE24`	EU Spring Sale 2024	Peak
`BAU`	Business As Usual	BAU

2. High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         EPIC SYSTEM ARCHITECTURE                            │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────┐
  │        SERVICE OWNER / USER     │ (Browser)
  └────────────────┬────────────────┘
                   │  HTTPS
                   ▼
  ┌─────────────────────────────────┐
  │         EPICFrontend            │  React.js + AWS CloudScape UI
  │    Hosted on Amazon Harmony     │  (Beta/Gamma/Prod via CodePipeline)
  │    https://console.harmony.     │
  │    a2z.com/epic/                │
  └────────────────┬────────────────┘
                   │  REST API (IAM Auth via Harmony)
                   ▼
  ┌─────────────────────────────────┐
  │       AWS API Gateway           │  REST API
  │  (EPICApiStack — CDK deployed)  │  ~60+ routes across 12 domains
  └────────────────┬────────────────┘
                   │  Lambda Proxy Integration
                   ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │                    EPICBackend — Node.js Lambda Functions               │
  │                                                                         │
  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────┐  │
  │  │ Fleet   │ │ Service │ │  Event  │ │EventPlan │ │  Projection   │  │
  │  │ Lambda  │ │ Lambda  │ │ Lambda  │ │  Lambda  │ │    Lambda     │  │
  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘ └───────┬───────┘  │
  │       │           │           │            │                │          │
  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────┐  │
  │  │Throttle │ │Exception│ │  HOTW   │ │  Ticket  │ │  BulkJobs     │  │
  │  │ Lambda  │ │ Lambda  │ │ Lambda  │ │  Lambda  │ │    Lambda     │  │
  │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬─────┘ └───────────────┘  │
  │       │           │           │            │                           │
  └───────┼───────────┼───────────┼────────────┼───────────────────────────┘
          │           │           │            │
          ▼           ▼           ▼            ▼
  ┌────────────────────────────────────────────────┐
  │              AWS DynamoDB Tables               │
  │  FleetTable  ServiceTable  EventTable          │
  │  EventPlanTable  ProjectionsTable  SchemaTable │
  │  ExceptionTable  ThrottlingTable  HOTWTable    │
  └───────────────┬────────────────────────────────┘
                  │ DynamoDB Streams
                  ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │               EPICBackendTriggers — Java Lambda Functions               │
  │                                                                         │
  │  ApolloHandler  AxonHandler  ThrottlingExecutor  BAUScalingHandler     │
  │  FloTriggerHandler  ConsensusHandler  MilestoneWorkflowHandler         │
  │  ScalingPlannerHandler  PmetHandler  VarianceExceededHandler           │
  └──────────┬──────────────┬────────────────┬────────────────┬────────────┘
             │              │                │                │
             ▼              ▼                ▼                ▼
     ┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
     │    Apollo    │ │   Axon   │ │ SDC / Gizmo  │ │   SIM / FLO  │
     │(config push) │ │(traffic) │ │ (throttling) │ │  (ticketing) │
     └──────────────┘ └──────────┘ └──────────────┘ └──────────────┘

  ┌─────────────────────────────────────────────────────────────────────────┐
  │                    MESSAGING & NOTIFICATIONS                            │
  │                                                                         │
  │  SNS (NotificationSNS) ──► SQS (emailQueue) ──► Email Lambda          │
  │  SQS (EventFleetCreation) ──► Fleet trigger Lambda                     │
  │  SQS (EventTicketCreation) ──► Ticket creation Lambda                  │
  └─────────────────────────────────────────────────────────────────────────┘

  ┌────────────────────────────┐
  │  AWS RDS (MySQL/Aurora)    │ — Ticketing, SQL analytics, HOTW data
  └────────────────────────────┘

3. System Components — 5 Packages

Package Map

EPIC/ (Brazil Workspace)
├── EPICFrontend/          ← React.js web application
│   ├── src/pages/         ← 25+ page views
│   ├── src/components/    ← Reusable UI components
│   ├── src/client/        ← API Gateway client
│   └── src/store/         ← Redux state management
│
├── EPICBackend/           ← Node.js Lambda business logic
│   ├── src/epiclambda/api/       ← 20+ domain API handlers
│   ├── src/epiclambda/operations/ ← DB operations layer
│   ├── src/epiclambda/common/    ← Constants & utilities
│   ├── src/epiclambda/notification/ ← SNS notifications
│   └── src/epiclambda/sqs/       ← SQS message sending
│
├── EPICBackendCDK/        ← TypeScript CDK infrastructure
│   ├── lib/apiStack.ts    ← DynamoDB tables, SQS, SNS
│   ├── lib/EPICApiStack.ts ← API Gateway routes
│   ├── lib/Fleet/         ← Fleet Lambda stack
│   ├── lib/Event/         ← Event Lambda stack
│   ├── lib/Service/       ← Service Lambda stack
│   ├── lib/HOTW/          ← HOTW Lambda stack
│   └── lib/rdsStack.ts    ← RDS MySQL cluster
│
├── EPICBackendTriggers/   ← Java Lambda event processors
│   └── src/com/amazon/epicbackendtriggers/lambda/
│       ├── handler/       ← 30+ trigger handlers
│       ├── apollo/        ← Apollo config integration
│       ├── throttling/    ← SDC/Gizmo throttle updates
│       ├── bau/           ← BAU scaling automation
│       ├── milestone/     ← Milestone workflows
│       └── scalingplanner/ ← Auto scaling planner
│
└── EPICBackendTriggersIntegrationTests/ ← Integration test suite

3.1 EPICFrontend — React Application

Attribute	Value
Framework	React.js
UI Library	AWS CloudScape (`@amzn/awsui-components-react`)
State Management	Redux Toolkit (`@reduxjs/toolkit`)
Hosting	Amazon Harmony
Node version	v16.0.0
API Auth	Harmony IAM Role (`HarmonyAPIGatewayAccessRole`)
Env configs	`.env.development` / `.env.production`

Pages Overview:

Page File	Description
`events.jsx`	Browse all peak events
`createEvent.jsx`	Create new peak/BAU event
`fleetConfigurations.jsx`	View & configure fleet scaling
`serviceDetails.jsx`	Per-service configuration detail
`service.jsx`	List all services
`serviceOnboarding.jsx`	Onboard a new service to EPIC
`serviceReadinessDashboard.jsx`	Readiness status per event
`serviceOwnerDashboardDetail.jsx`	Service owner’s view of milestones
`hotwDashboard.jsx`	Head of the Week run dashboard
`hotwRunHistory.jsx`	Historical HOTW run data
`hotwAsgRunDetails.jsx`	ASG (Auto Scaling Group) details
`actionDashboard.jsx`	All outstanding action items
`createException.jsx`	Submit a capacity exception
`approveException.jsx`	Review & approve exceptions
`serviceThrottling.jsx`	Throttle config per service
`descaleFleetConfigurations.jsx`	Post-event descale config
`descaleServiceThrottling.jsx`	Post-event descale throttling
`dimensionView.jsx`	Traffic dimension metrics view
`configureDimension.jsx`	Configure metric dimensions
`bauServiceOwnerDashboard.jsx`	BAU scaling dashboard
`hostMigration.jsx`	Host migration tracking
`syncSettings.jsx`	Configuration sync settings
`upstreamDetails.jsx`	Upstream service dependencies
`serviceDescaleReadinessDashboard.jsx`	Descale readiness view
`onboardingChecklist.jsx`	Service onboarding checklist

3.2 EPICBackend — Node.js Lambda Handlers

Each API handler is a class with static async methods:

Handler File	Responsibility
`Fleet.js`	CRUD for fleet objects, TPM updates, traffic config, approvals
`Service.js`	CRUD for services, upstream/downstream links, notifications
`Event.js`	CRUD for peak/BAU events, leadership dashboards
`EventPlan.js`	Milestone list management per fleet per event
`Projection.js`	Traffic projections for capacity planning
`Schema.js`	Fleet downstream schema (how traffic is counted)
`Throttling.js`	SDC/Gizmo throttle config data management
`Exception.js`	Capacity exception creation, approval, propagation
`Ticket.js`	Upstream↔Downstream coordination tickets (MySQL)
`HOTW.js`	Head of the Week run & execution details
`BulkJobs.js`	Async bulk job processing (bulk PMET upload etc.)
`Calendar.js`	Excluded dates management for events
`EventProfile.js`	Event profiles for configuration templates
`Organization.js`	Org-level grouping of services
`Philosophy.js`	Scaling philosophy rules per service
`CustomInputSF.js`	Custom input scaling factors
`CustomFormula.js`	Custom TPM computation formulas
`Employee.js`	Employee/user lookup for ownership
`Dimension.js`	Traffic dimension configurations
`Traffic.js`	Input/output traffic management
`BAUHostJob.js`	BAU host ordering job management
`Pmet.js`	PMET (Peak Metric) link management
`SIM.js`	SIM (Amazon ticketing) integration
`VarianceExceeded.js`	Variance detection & alerts

3.3 EPICBackendCDK — AWS Infrastructure

Written in TypeScript, deploys via AWS CDK through Brazil Build System.

Build commands:

brazil-build           # Compile TypeScript
brazil-build release   # Build for deployment
brazil-build cdk list  # List available stacks
brazil-build cdk deploy <StackName>

3.4 EPICBackendTriggers — Java Lambda Handlers

These are event-driven — triggered by DynamoDB Streams, SQS messages, or CloudWatch Events.

Key Handlers:

Handler	Trigger	What it does
`ApolloHandler.java`	Schedule/DDB Stream	Pushes capacity configs to Apollo (Amazon config system)
`ApolloTriggerHandler.java`	SQS	Executes Apollo config push for a fleet
`BAUScalingHandler.java`	Schedule	Runs BAU scaling recommendations
`ThrottlingExecutor.java`	DDB Stream	Pushes throttle changes to SDC/Gizmo systems
`FloTriggerHandler.java`	SQS	Runs FLO (Fleet Light Operations) one-box scaling
`FloExecutionHandler.java`	Schedule	Executes FLO scaling decisions
`MilestoneWorkflowHandler.java` (WorkflowHandler)	API/SQS	Updates milestone completion statuses
`ScalingPlannerHandler.java`	Schedule	Generates scaling plan recommendations
`ConsensusHandler.java`	Schedule	Runs consensus algorithm for host counts
`AxonHandler.java`	Schedule/Event	Integrates with Axon traffic management
`GatherEmailTriggerHandler.java`	SQS	Sends TPM gather request emails
`PmetHandler.java`	Schedule	Refreshes PMET (Peak Metric) links
`VarianceExceededHandler.java`	CloudWatch	Detects TPM variance and alerts
`HotwHandler.java`	Schedule	Runs HOTW automation (ASG management)
`OnboardingHandler.java`	DDB Stream	Processes new service onboarding steps
`DescaleHostsHandler.java`	Schedule	Automates post-event descaling
`EAPDetailsHandler.java`	Event	Updates EAP (Emergency Adjustment Process) details
`TicketServiceReadinessTriggerHandler.java`	DDB Stream	Creates tickets for service readiness
`TotalPeakProjectionHandler.java`	Schedule	Calculates total peak projection across services
`ValidateUserHandler.java`	API	Validates user permissions
`FmbiHandler.java`	S3	Processes FMBI (Fleet Management Business Intelligence) data
`CapacityInventoryHandler.java`	Schedule	Tracks hardware capacity inventory
`UpdateFleetTrafficHandler.java`	DDB Stream	Cascades traffic updates to downstream fleets

4. Data Models & Domain Objects

4.1 Service Object

{
  "ServiceId": "FORTRESSService",
  "ServiceIndexId": 42,
  "VersionId": 3,
  "Email": "fortress-dev@amazon.com",
  "Ldap": "fortress-dev",
  "Owner": "johndoe",
  "PointOfContact": "janedoe",
  "OrganizationId": 1,
  "ServiceType": "Registered",
  "Api": [{ "Name": "EvaluateInternalTransaction", "UsedForScaling": true }],
  "CTI": { "Category": "...", "Type": "...", "Item": "..." },
  "Upstreams": ["VCS-NA", "ARMService-NA"],
  "DownStreams": ["OrderService-NA"],
  "Fleet": ["FORTRESSService-X1-NA", "FORTRESSService-X2-EU"],
  "OnboardingStatus": {
    "FinalStatusComplete": false,
    "CustomerChecklist": {
      "ServiceDetailsVerified": false,
      "UpstreamsAudited": false,
      "DownstreamsAudited": false,
      "PermissionsGiven": false,
      "HostThroughputTPMUpdated": false,
      "PMETLinksGiven": false,
      "CloudTuneDriver": null,
      "CustomerChecklistSignOff": false
    }
  },
  "AuditMetadata": { "User": "johndoe", "Timestamp": "06/01/2024 12:00:00", "Message": "..." }
}

4.2 Fleet Object

{
  "FleetId": "FORTRESSService-X1-NA",
  "ServiceId": "FORTRESSService",
  "EventId": "PrimeDay26",
  "FleetIndexId": 123,
  "VersionId": 2,
  "FleetType": "Registered",
  "FleetConfiguration": {
    "ApolloName": "FORTRESSService/NA/X1/Prod",
    "Region": "us-east-1",
    "AzFactor": 1.125,
    "MaxHostCount": 500,
    "HostThroughputTPM": 570,
    "IsFLORunAutomated": true,
    "ApolloNameForFLO": "FORTRESSService/NA/X1/OneBox"
  },
  "InputTraffic": [
    {
      "Type": "Self",
      "ApiName": "EvaluateInternalTransaction",
      "FleetId": "FortressSILService-NA",
      "InputTPM": 100
    },
    {
      "Type": "Upstream",
      "ApiName": "ComputeRiskProfile",
      "FleetId": "VCS-NA",
      "ScalingFactor": 1.2,
      "ScalingProperties": { "BufferFactor": 0.3 }
    },
    {
      "Type": "CloudTune",
      "ApiName": "EvaluateInternalTransaction",
      "FleetId": "ARMService-NA",
      "CloudTuneProjection": { "ProjectionId": "Physical-Order-Rate-NA", "VersionId": 1 }
    }
  ],
  "OutputTraffic": [
    { "Type": "Auto", "ApiName": "ComputeRiskProfile", "FleetId": "VCS-NA", "ScalingFactor": 1.2 }
  ],
  "HostOrderStatuses": {
    "HostOrdersNeeded": 200,
    "HostsPendingDelivery": 50,
    "HostsPendingApproval": 10
  },
  "ScalingStatus": "Completed",
  "BauMetadata": { ... },
  "AuditMetadata": { "User": "johndoe", "Timestamp": "...", "Message": "..." }
}

4.3 Event Object

{
  "EventId": "PrimeDay26",
  "EventName": "Prime Day 2026",
  "EventType": "Peak",
  "VersionId": 1,
  "LatestVersionId": 1,
  "RegionList": ["NA", "FE", "EU", "CN"],
  "EventStartDate": "07/14/2026 00:00:00",
  "EventEndDate": "07/15/2026 23:59:59",
  "EventInitialHardwareOrderDate": "02/01/2026 12:00:00",
  "EventHardwareReadinessDate": "06/01/2026 12:00:00",
  "BAUMonth": "06/2026",
  "CloudtunePeakFactor": { "NA": 2.1, "EU": 1.8, "FE": 1.6, "CN": 1.4 },
  "SPCOEventDatesByRegion": {
    "NA": { "SPCOEventStartDate": "07/01/2026 00:00:00", "SPCOEventEndDate": "07/31/2026 00:00:00" }
  },
  "AuditMetadata": { "User": "johndoe", "Timestamp": "...", "Message": "Creating PrimeDay26" }
}

4.4 EventPlan (Milestone Tracking)

{
  "EventPlanId": "PrimeDay26#FORTRESSService-X1-NA",
  "EventId": "PrimeDay26",
  "FleetId": "FORTRESSService-X1-NA",
  "ServiceId": "FORTRESSService",
  "VersionId": 3,
  "EventReadinessStatus": false,
  "EventMilestone": [
    {
      "MilestoneId": "GatherProjectionFromUpstream",
      "MilestoneCompletionStatus": "Completed",
      "ETA": "03/01/2026",
      "MilestoneMessage": "Projections gathered"
    },
    {
      "MilestoneId": "HardwareOrder",
      "MilestoneCompletionStatus": "Pending",
      "SubMilestones": [
        { "MilestoneId": "PlaceHardwareOrder", "MilestoneCompletionStatus": "Completed" },
        { "MilestoneId": "HardwareOrderApproval", "MilestoneCompletionStatus": "Pending" }
      ]
    },
    { "MilestoneId": "HardwareFulfillment", "MilestoneCompletionStatus": "NotStarted" },
    { "MilestoneId": "CommunicateTPMToDownstream", "MilestoneCompletionStatus": "NotStarted" },
    { "MilestoneId": "ThrottlingUpdateBeforeEvent", "MilestoneCompletionStatus": "NotStarted" }
  ],
  "EventDescaleMilestone": [
    { "MilestoneId": "DescaleCompletionMilestone" },
    { "MilestoneId": "GatherDescaleProjectionFromUpstream" },
    { "MilestoneId": "CommunicateDescaleTPMToDownstream" },
    { "MilestoneId": "DescaleThrottlingUpdate" }
  ]
}

4.5 Throttling Object

{
  "RecordId": "FORTRESSService-X1-NA#PrimeDay26",
  "FleetIndexId": 123,
  "ServiceIndexId": 42,
  "EventIndexId": 7,
  "Region": "us-east-1",
  "EPICUpstream": "VCS-NA",
  "Operation": "EvaluateInternalTransaction",
  "CurrentLimit": 5000,
  "UpscalingLimit": 10000,
  "DescalingLimit": 2000,
  "IsDisabled": false
}

5. Database Architecture

DynamoDB Tables

┌─────────────────────────────────────────────────────────────────────────┐
│                        DYNAMODB TABLE LAYOUT                            │
├─────────────────────────┬──────────────────┬────────────────────────────┤
│ Table Name              │ Primary Key      │ Purpose                    │
├─────────────────────────┼──────────────────┼────────────────────────────┤
│ FleetTable              │ FleetId + EventId│ All fleet scaling data     │
│ FleetIndexTable         │ FleetIndexId     │ Auto-increment fleet IDs   │
│ FleetLockTable          │ FleetId          │ Optimistic locking         │
│ ServiceTable            │ ServiceId        │ Service configurations     │
│ ServiceIndexTable       │ ServiceIndexId   │ Auto-increment service IDs │
│ EventTable              │ EventId + VersionId│ Peak event metadata     │
│ EventIndexTable         │ EventIndexId     │ Auto-increment event IDs   │
│ EventPlanTable          │ EventPlanId + VersionId│ Milestone tracking  │
│ ProjectionsTable        │ ProjectionId     │ Traffic projections        │
│ SchemaTable             │ FleetId          │ Fleet downstream schemas   │
│ EventProfileTable       │ EventProfileId   │ Event profile templates    │
│ ExceptionTable          │ ExceptionId      │ Capacity exceptions        │
│ JobDetailsTable         │ JobId            │ Async job status           │
│ ThrottlingTable         │ RecordId         │ Throttle data per fleet    │
│ ThrottlingConfigTable   │ ConfigId         │ Throttle config templates  │
│ BAUServiceDashboard     │ ServiceId        │ BAU scaling dashboard      │
└─────────────────────────┴──────────────────┴────────────────────────────┘

DynamoDB Key Design Pattern (Versioning)

EPIC uses a dual-table versioning pattern for most entities:

Main Table (FleetTable):        Stores ALL versions
  PK: FleetId + VersionId

Latest Version Index (GSI):     Quick lookup for current data
  GSI: FleetId-LatestVersionId-index

This allows:

Complete history of every change
Fast latest-version reads
Audit trail with AuditMetadata on every record

SQS Queues

Queue	Purpose	DLQ
`emailQueue`	Email notifications via SES	`emailDLQ`
`EventFleetCreationQueue`	Async fleet creation on event	`EventFleetCreationDLQ`
`EventTicketCreationQueue`	Auto-create coordination tickets	`EventTicketCreationDLQ`
`DetectFleetInconsistenciesQueue`	Background fleet validation	`DetectFleetInconsistenciesDLQ`
`PmetLinksRfrshQueue`	Refresh PMET links periodically	`PmetLinksRfrshDLQ`
`CustomFormulaRefreshQueue`	Refresh formula calculations	`CustomFormulaRefreshDLQ`

All DLQs retain messages for 14 days.

RDS (MySQL)

Used for:

Ticketing data (relational upstream↔downstream tickets)
SQL analytics (ExecuteSQL endpoint)
HOTW execution data (ASG run history)
Host ordering details (OrderDetails)

6. REST API Reference

Base URL: https://<api-gateway-id>.execute-api.<region>.amazonaws.com/Prod

Fleet APIs

Method	Path	Description
POST	`/fleet`	Create a new fleet
GET	`/fleet/{FleetId}/{EventId}`	Get fleet data
PUT	`/fleet/{FleetId}/{EventId}`	Update fleet
GET	`/fleet/{FleetId}/{EventId}/configuration`	Get fleet config
PUT	`/fleet/{FleetId}/{EventId}/configuration/host_throughput`	Update HostTPM
PUT	`/fleet/{FleetId}/{EventId}/configuration/apollo_properties`	Update Apollo config
PUT	`/fleet/{FleetId}/{EventId}/configuration/AZ_Factor`	Update AZ Factor
PUT	`/fleet/{FleetId}/{EventId}/configuration/custom_thresholds`	Update thresholds
PUT	`/fleet/{FleetId}/{EventId}/configuration/region`	Update region
GET	`/fleet/{FleetId}/{EventId}/Traffic`	Get traffic data
PUT	`/fleet/{FleetId}/{EventId}/Traffic`	Update traffic
PUT	`/fleet/{FleetId}/{EventId}/Traffic/disable`	Disable fleet traffic
PUT	`/fleet/{FleetId}/{EventId}/updateFleetTrigger`	Trigger scaling
PUT	`/fleet/{FleetId}/{EventId}/overrideTotalInputTPM`	Override input TPM
PUT	`/fleet/{FleetId}/{EventId}/updateOutputTpm`	Update output TPM
PUT	`/fleet/{FleetId}/{EventId}/updateBAUTPM`	Update BAU TPM
PUT	`/fleet/{FleetId}/{EventId}/updateDescaleTPM`	Update descale TPM
PUT	`/fleet/{FleetId}/{EventId}/hostOrderStatuses`	Update host orders
PUT	`/fleet/{FleetId}/{EventId}/approval`	Submit approval
GET	`/fleet/{FleetId}/{EventId}/fleetVersionList`	Get version history
GET	`/fleet/{FleetId}/{EventId}/inputTrafficSnapshot`	Input traffic snapshot
GET	`/fleet/{FleetId}/Version/{VersionId}`	Get specific version
GET	`/fleet/batch`	Get batch of fleet IDs

Service APIs

Method	Path	Description
POST	`/service`	Create service
GET	`/service`	List all services
GET	`/service/{ServiceId}`	Get service
PUT	`/service/{ServiceId}`	Update service
GET	`/service/{ServiceId}/upstreams/{EventId}`	Get upstream services
GET	`/service/{ServiceId}/downstreams/{EventId}`	Get downstream readiness
PUT	`/service/{ServiceId}/upstreams/{EventId}`	Send gather TPM email
PUT	`/service/{ServiceId}/throttling/config`	Update SDC throttle config
PUT	`/service/{ServiceId}/throttling/gizmo`	Update Gizmo config
PUT	`/service/{ServiceId}/throttling/fleetStatus`	Update fleet throttle status
GET	`/service/{ServiceId}/throttling/{EventId}`	Check throttle readiness
PUT	`/service/{ServiceId}/onboarding`	Update onboarding status
GET	`/service/{ServiceId}/preference`	Get service preferences
PUT	`/service/{ServiceId}/preference`	Update service preferences
GET	`/service/dashboard`	BAU service dashboard

Event APIs

Method	Path	Description
GET	`/event`	List all events
POST	`/event`	Create event
GET	`/event/{EventId}`	Get event
PUT	`/event/{EventId}`	Update event
GET	`/event/{EventId}/fleets`	Get all fleets for event
PUT	`/event/{EventId}/dashboard`	Leadership dashboard data
PUT	`/event/{EventId}/dashboard/descaling`	Descale dashboard data
GET	`/event/{EventId}/automatedMetricPercentage`	Metric automation %

EventPlan (Milestones) APIs

Method	Path	Description
POST	`/eventPlan`	Create event plan
GET	`/eventPlan/{EventId}/{FleetId}`	Get event plan
PUT	`/eventPlan/{EventId}/{FleetId}/eventMilestoneList`	Bulk update milestones
PUT	`/eventPlan/{EventId}/{FleetId}/eventMilestoneDetail`	Update milestone detail
PUT	`/eventPlan/{EventId}/{FleetId}/milestoneStatusUpdate`	Update milestone status
GET	`/eventPlan/{EventId}/{FleetId}/version/{VersionId}`	Get versioned plan

Other Domain APIs

Domain	Routes include
Projection	GET/POST `/projection`, GET/PUT `/projection/{ProjectionId}`
Schema	PUT `/fleet/{FleetId}/{EventId}/schema/downstream`, GET `/fleet/{FleetId}/schema`
Exception	POST/PUT `/exception`, GET `/exception/{ExceptionId}`
Ticket	POST `/ticket`, GET/PUT `/ticket/...`
HOTW	POST/PUT `/hotw/run`, POST `/hotw/execution`, POST/GET `/hotw/dashboard`
Calendar	GET/PUT `/calendar`
BulkJobs	POST/PUT/GET `/jobs`, GET `/jobs/{JobId}`

7. Event Readiness Workflow (Milestones)

This is the core operational workflow that EPIC manages for each fleet per peak event.

╔════════════════════════════════════════════════════════════════════════╗
║              PEAK EVENT READINESS WORKFLOW (Per Fleet)                ║
╚════════════════════════════════════════════════════════════════════════╝

  EVENT CREATED
       │
       ▼
  ┌──────────────────────────────────────────┐
  │ MILESTONE 1: Gather Projection From      │
  │             Upstream                     │
  │                                          │
  │  • Send email to all upstream services   │
  │  • Upstreams provide expected TPM        │
  │  • EPIC auto-calculates required hosts   │
  │  Status: NotStarted → Pending → Completed│
  └─────────────────┬────────────────────────┘
                    │
                    ▼
  ┌──────────────────────────────────────────┐
  │ MILESTONE 2: Hardware Order              │
  │  ┌─────────────────────────────────┐    │
  │  │ Sub-milestone 2a:               │    │
  │  │   Place Hardware Order          │    │
  │  │   (SPCO override submitted)     │    │
  │  └──────────────┬──────────────────┘    │
  │                 │                        │
  │  ┌──────────────▼──────────────────┐    │
  │  │ Sub-milestone 2b:               │    │
  │  │   Hardware Order Approval       │    │
  │  │   (Business/Regional/Financial) │    │
  │  └─────────────────────────────────┘    │
  └─────────────────┬────────────────────────┘
                    │
                    ▼
  ┌──────────────────────────────────────────┐
  │ MILESTONE 3: Hardware Fulfillment        │
  │                                          │
  │  • Hardware physically delivered         │
  │  • Hosts come online in datacenter       │
  │  • Fleet host count verified             │
  └─────────────────┬────────────────────────┘
                    │
                    ▼
  ┌──────────────────────────────────────────┐
  │ MILESTONE 4: Communicate TPM             │
  │             To Downstream                │
  │                                          │
  │  • Send peak TPM numbers to downstream   │
  │  • Downstream updates their scaling too  │
  │  • Tickets created for coordination      │
  └─────────────────┬────────────────────────┘
                    │
                    ▼
  ┌──────────────────────────────────────────┐
  │ MILESTONE 5: Throttling Update           │
  │             Before Event                 │
  │                                          │
  │  • SDC/Gizmo throttle limits pushed      │
  │  • Limits set to peak capacity           │
  │  • Throttling marked ready               │
  └─────────────────┬────────────────────────┘
                    │
                    ▼
         ✅ EVENT READINESS STATUS = TRUE
                    │
          ══════════════════════
             PEAK EVENT RUNS
          ══════════════════════
                    │
                    ▼
  ┌──────────────────────────────────────────┐
  │ DESCALE MILESTONE 1: Descale Completion  │
  │ DESCALE MILESTONE 2: Gather Descale TPM  │
  │ DESCALE MILESTONE 3: Communicate         │
  │              Descale TPM To Downstream   │
  │ DESCALE MILESTONE 4: Descale Throttling  │
  └──────────────────────────────────────────┘

Milestone Statuses: NotStarted → Pending → Completed
                    (Also: NotApplicable, NotAvailable)

8. Trigger System (Java Lambdas)

How Triggers Work

  DynamoDB FleetTable
       │ (Stream)
       ▼
  ┌─────────────────────────────────┐
  │   DynamoDB Stream Processor     │
  │   (EPICBackendTriggers)         │
  │                                 │
  │   INSERT/MODIFY/REMOVE event    │
  │   ──► Route to correct handler  │
  └────────────┬────────────────────┘
               │
       ┌───────┼────────────────┬─────────────────┐
       ▼       ▼                ▼                 ▼
  ┌─────────┐ ┌─────────────┐ ┌───────────────┐ ┌──────────────┐
  │ Apollo  │ │ Throttling  │ │  Milestone    │ │ Traffic      │
  │ Handler │ │ Executor    │ │  Workflow     │ │ Update       │
  │         │ │             │ │  Handler      │ │ Handler      │
  │ Pushes  │ │ SDC + Gizmo │ │               │ │              │
  │ config  │ │ throttle    │ │ Auto-complete │ │ Cascades TPM │
  │ to      │ │ limit       │ │ milestones    │ │ changes to   │
  │ Apollo  │ │ update      │ │               │ │ downstream   │
  └─────────┘ └─────────────┘ └───────────────┘ └──────────────┘

Amazon Internal Systems Integrated

System	What it is	EPIC’s Integration
Apollo	Amazon’s internal configuration deployment system	Pushes fleet capacity configs (SPCO overrides)
Axon	Amazon’s traffic management system	Reads/writes traffic shaping rules
SDC	Service Dependency Control (throttling)	Updates max TPM throttle limits
Gizmo	Another throttling framework	Alternative throttle config push
FLO	Fleet Light Operations (one-box scaling)	Automated one-box scale tests
SIM	Amazon internal ticketing system	Creates SIM tickets for fleet actions
CloudTune	Amazon’s ML-based capacity recommendation	Source of scaling factor projections
Conduit	Amazon’s credential management	AWS credential provisioning
Harmony	Amazon’s frontend app hosting	Hosts the EPIC web UI
Brazil	Amazon’s build/package management	Used to build and deploy all packages
PMET	Peak Metric tracking system	Links to metrics for each fleet
HOTW	Head of the Week	Weekly operational automation
FMBI	Fleet Management Business Intelligence	Fleet analytics data source
Superstar	Amazon’s CDK pipeline framework	Used for deploying CDK stacks

9. Notification & Messaging System

  Any Lambda (Fleet update, Service create, etc.)
       │
       │  publish(TopicArn: SNS_TOPIC_ARN)
       ▼
  ┌──────────────────────┐
  │    SNS Topic         │
  │  (notificationSNS)   │
  └──────────┬───────────┘
             │  SqsSubscription
             ▼
  ┌──────────────────────┐       ┌──────────────────────┐
  │   emailQueue (SQS)   │──────▶│   Email Lambda       │──▶ Amazon SES → Email
  └──────────────────────┘       └──────────────────────┘
             │
             │ maxReceiveCount: 2
             ▼
  ┌──────────────────────┐
  │      emailDLQ        │ (14-day retention)
  └──────────────────────┘

  Message Types (MessageAttributes → NotificationName):
  ┌──────────────────────────────────────────────────────┐
  │ • UPDATE         - Fleet/Service object updated      │
  │ • CREATE_SERVICE - New service created               │
  │ • GATHER_EMAIL   - Request TPM from upstream         │
  │ • PEAK_READINESS - Readiness status change           │
  └──────────────────────────────────────────────────────┘

10. Infrastructure (CDK Stacks)

Stack Dependency Tree

SuperStarPersonalBootstrap
└── VpcStack (Virtual Network)
    ├── ApiStack (DynamoDB + SQS + SNS + SecurityGroup)
    ├── FleetLambdaStack
    ├── ServiceLambdaStack
    ├── EventLambdaStack
    ├── EventPlanLambdaStack
    ├── ProjectionsLambdaStack
    ├── SchemaLambdaStack
    ├── EventProfileLambdaStack
    ├── ExceptionLambdaStack ◄─ uses ExceptionTable from ApiStack
    ├── BulkJobsLambdaStack
    ├── TicketLambdaStack
    ├── CalendarLambdaStack
    ├── HOTWLambdaStack
    ├── ThrottlingLambdaStack
    ├── CommonStack
    ├── OrganizationStack
    ├── PhilosophyStack
    ├── CustomInputSFStack
    ├── CustomFormulaStack
    ├── ExceptionStack
    ├── RdsStack (MySQL + Lambda integrations)
    ├── EPICApiStack (API Gateway — ALL routes)
    └── TriggersStack (CloudWatch / SNS triggers)

Optional:
    ├── SIMStack
    ├── MilestoneWorkflowStack
    ├── AxonStack
    ├── ApprovalStack
    ├── ScalingPlannerStack
    ├── PmetStack
    └── TicketingStack

Deployment Stages (CI/CD)

  Commit to mainline
       │
       ▼
  ┌─────────────────────────────────────────────────┐
  │           AWS CodePipeline (EPIC-Prod account)  │
  │                  us-west-2 region               │
  └──────────┬────────────────────────────────────  ┘
             │
     ┌───────▼────────┐
     │   Beta Stage   │ ◄── First deployment, automated tests
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │  Gamma Stage   │ ◄── Staging environment
     └───────┬────────┘
             │
     ┌───────▼────────┐
     │   Prod Stage   │ ◄── Live at console.harmony.a2z.com/epic/
     └────────────────┘

11. Frontend Architecture (React)

src/
├── Epic.js                    ← Root component, routing setup
├── index.js                   ← Entry point, Redux store setup
├── store/                     ← Redux Toolkit state slices
├── client/
│   └── getApigClient.js       ← API Gateway client factory
│                                 (uses aws-api-gateway-client)
├── pages/                     ← 25+ page components (see table above)
├── components/
│   ├── cards/                 ← Card layout components
│   ├── tables/                ← Data table components
│   ├── Tabs/                  ← Tab navigation
│   ├── Headers/               ← Page header components
│   ├── Flashbar/              ← Alert/notification bar
│   ├── Container/             ← Layout containers
│   ├── crumbs/                ← Breadcrumb navigation
│   ├── VersionHistory/        ← Version history viewer
│   ├── sideNav.jsx            ← Left navigation sidebar
│   ├── topNavigation.jsx      ← Top navigation bar
│   └── withEventTypeRoutes.jsx← HOC for event routing
├── common/                    ← Shared utilities
├── configuration/             ← App configuration
├── featureutils/              ← Feature flag utilities
├── styles/                    ← Global CSS
└── tutorials/                 ← Onboarding tutorials

Key Libraries:
  @amzn/awsui-components-react  ← AWS CloudScape Design System
  @reduxjs/toolkit              ← State management
  aws-api-gateway-client        ← API calls to backend
  moment                        ← Date formatting
  lodash                        ← Utility functions
  csv-string / json2csv         ← Export to CSV
  react-scripts                 ← Build tooling (CRA)

12. Traffic & Throttling System

TPM Flow — How Traffic Numbers Flow

  CloudTune (ML predictions)
       │  CloudTune Peak Factor
       ▼
  ┌────────────────────────────────────────────────────┐
  │              EPIC Projection                       │
  │   ProjectionId: "Physical-Order-Rate-NA"           │
  │   BAU TPM × CloudtunePeakFactor → Peak TPM         │
  └──────────────────────┬─────────────────────────────┘
                         │
                         ▼
  ┌────────────────────────────────────────────────────┐
  │              Fleet InputTraffic                    │
  │                                                    │
  │  Type: "Self"      → Direct traffic measurement    │
  │  Type: "Upstream"  → Driven by upstream fleet TPM  │
  │  Type: "CloudTune" → ML model driven traffic       │
  │                                                    │
  │  Total InputTPM = Σ(InputTraffic sources)          │
  │  Required Hosts = InputTPM / HostThroughputTPM     │
  │                 × AzFactor  (AZ redundancy)        │
  └──────────────────────┬─────────────────────────────┘
                         │
                         ▼
  ┌────────────────────────────────────────────────────┐
  │              Throttling Update                     │
  │                                                    │
  │  SDC Throttle Config:                              │
  │    CurrentLimit: BAU TPM                           │
  │    UpscalingLimit: Peak TPM                        │
  │    DescalingLimit: Post-peak TPM                   │
  │                                                    │
  │  Gizmo Throttle Config:                            │
  │    Alternative throttle system with revisions      │
  └────────────────────────────────────────────────────┘

  AZ Factor Values (by region):
  ┌──────────────────────────────┐
  │ us-east-1 (NA)  → 1.125     │ (need 12.5% extra for AZ redundancy)
  │ eu-west-1 (EU)  → 1.35      │
  │ eu-south-2      → 1.35      │
  │ us-west-2 (FE)  → 1.35      │
  │ cn-north-1 (CN) → 2.0       │
  │ eu-central-1    → 1.35      │
  └──────────────────────────────┘

13. Deployment Pipeline

Frontend Deployment (EPICFrontend)

# Local Development
npm install
npm start              # → localhost:3000

# Testing
npm run build_test     # build + test combined
npm test               # Jest tests only

# Deploy to Harmony
git push to mainline
# → CodePipeline auto-deploys: Beta → Gamma → Prod

Backend Deployment (EPICBackend + CDK)

# Step 1: Build backend packages
cd EPICBackend && brazil-build release
cd EPICBackendTriggers && brazil-build release
cd EPICBackendCDK && brazil-build release

# Step 2: Bootstrap CDK
brazil-build bootstrap

# Step 3: Deploy stacks
brazil-build cdk deploy Personal-ApiStack          # DynamoDB, SQS, SNS
brazil-build cdk deploy Personal-VpcStack          # VPC networking
brazil-build cdk deploy Personal-FleetLambdaStack  # Fleet Lambdas
brazil-build cdk deploy Personal-EPICApiStack      # API Gateway + all routes

# Quick Lambda code update (no full CloudFormation deploy)
bb cdk deploy --hotswap Personal-FleetLambdaStack

14. Key Business Concepts Glossary

Term	Definition
Fleet	A group of Amazon servers (hosts) running a specific service in a region (e.g., `FORTRESSService-X1-NA`)
TPM	Transactions Per Minute — the traffic volume metric used for all scaling decisions
HostThroughputTPM	How many TPM a single host can handle (e.g., 570 TPM/host)
Peak Event	A scheduled high-traffic period requiring extra capacity (Prime Day, Black Friday, etc.)
BAU	Business As Usual — normal (non-peak) operations, also managed in EPIC
EventPlan	The per-fleet milestone tracking plan for a peak event
Milestone	A specific readiness gate each fleet must pass before peak (hardware order, throttling, etc.)
AZ Factor	Availability Zone redundancy multiplier — how much extra capacity to add for multi-AZ redundancy
SPCO Override	Service Provider Capacity Override — a request to AWS to provision extra hardware
Throttling	Rate-limiting traffic to protect a service from overload
SDC	Service Dependency Control — Amazon’s internal throttling system
Gizmo	Another Amazon throttling framework
Apollo	Amazon’s internal configuration deployment system
CloudTune	Amazon’s ML-based capacity recommendation system
HOTW	Head of the Week — weekly operational run that automates scaling decisions
FLO	Fleet Light Operations — one-box (single host) automated scaling tests
Axon	Amazon’s traffic management/routing system
SIM	Amazon’s internal ticketing system (like Jira)
Upstream	A service that sends traffic TO the current service
Downstream	A service that receives traffic FROM the current service
Projection	An estimated traffic forecast for a future event
Exception	A request for capacity outside the normal scaling plan
Harmony	Amazon’s internal frontend app hosting platform
Brazil	Amazon’s internal build, package, and dependency management system
Bindle	Amazon’s resource ownership/permission tracking system
PMET	Peak Metric — a pre-defined performance metric used to validate scaling
FMBI	Fleet Management Business Intelligence — data source for fleet analytics

15. Developer Setup Cheatsheet

Prerequisites

✓ Amazon dev-desk (dev environment)
✓ Brazil CLI installed
✓ AWS credentials (mwinit)
✓ Node.js v16.0.0 + npm 8
✓ Java 11 (JDK)
✓ BATS CLI: toolbox install batscli
✓ Harmony CLI installed

Workspace Setup

# Create workspace and pull all packages
brazil ws create --name EPIC
cd EPIC
brazil ws use --versionset EPICBackend/development
brazil ws use --package EPICBackendCDK
brazil ws use --package EPICBackend
brazil ws use --package EPICBackendTriggers
brazil ws use --package EPICFrontend

Running Frontend Locally

cd src/EPICFrontend
npm install
npm start          # → localhost:3000 (connected to EPIC-Devo backend)

Running Backend Tests

cd src/EPICBackend
npm test           # Runs Jest tests with ≥70% coverage requirement

Common Troubleshooting

Error	Fix
`sh: react-scripts: command not found`	`rm -rf node_modules && npm install`
`harmony command not found`	Run `harmony npm` to point to Amazon npm registry
`Error: Integrity check failed`	`rm package-lock.json && harmony npm && npm install`
`NOT Found - GET https://registry.npmjs.org/@amzn`	Run `harmony npm` first
`CDK token expired`	Run `mwinit -o` or `ada credentials update ...`
`npm ERR! ERR_STRING_TOO_LONG`	`rm -rf aws_lambda.bundle.primary.*` then re-run
`JAVA_HOME not found`	`echo $JAVA_HOME` — install JDK and set PATH

Summary

┌─────────────────────────────────────────────────────────────────────┐
│                        EPIC AT A GLANCE                             │
├─────────────────────┬───────────────────────────────────────────────┤
│ Purpose             │ Amazon peak capacity planning & execution     │
│ Users               │ Service owners, EPIC team, leadership        │
│ Scale               │ Hundreds of services, thousands of fleets    │
│ Events Managed      │ Prime Day, Black Friday, Holiday, BAU        │
│ Frontend            │ React + CloudScape UI on Amazon Harmony      │
│ Backend             │ Node.js Lambda functions (~20 domains)       │
│ Infrastructure      │ AWS CDK TypeScript (~25 stacks)              │
│ Triggers            │ Java Lambdas (~30 handlers)                  │
│ Primary Database    │ DynamoDB (15+ tables with versioning)        │
│ Secondary Database  │ RDS MySQL (tickets, analytics)               │
│ Messaging           │ SNS → SQS (6 queues + DLQs)                 │
│ Auth                │ AWS IAM via Harmony proxy                    │
│ CI/CD               │ AWS CodePipeline: Beta → Gamma → Prod        │
│ Regions             │ NA (us-east-1), EU, FE (us-west-2), CN      │
│ Build System        │ Amazon Brazil                                │
└─────────────────────┴───────────────────────────────────────────────┘

Report generated from deep codebase analysis of EPIC/EPIC workspace.
Internal Amazon project — not for external distribution.