Operation: Black Swan

Introduction

Operation: Black Swan is a simulation platform that explores how system design decisions compound into resilience—or fragility—under pressure. While presented as a turn-based strategy experience, it's fundamentally about understanding how constraints (time, budget), requirements (sites, throughput), and unexpected events (black swan events—both positive opportunities and negative disruptions) interact in real-world infrastructure design. The system challenges users to build systems that can effectively respond to uncertainty, teaching principles of resilience, redundancy, and adaptive design through hands-on experimentation.

1. Architecture Philosophy

Operation: Black Swan is built on a foundation of client-side first, serverless-ready architecture using AWS infrastructure. This design choice addresses the core challenges of delivering an interactive simulation that models complex system behavior: the need for rapid iteration during development, the ability to scale automatically when needed, and the flexibility to add multiplayer and analytics features without major architectural rewrites. The architecture supports both the simulation engine (modeling network behavior, constraints, and black swan events) and the learning experience (helping users understand how design decisions create or mitigate systemic risk).

Client-Side Architecture

The simulation runs entirely in the browser, with game logic executing client-side and state persisting to localStorage. This architecture delivers instant gameplay with zero server latency, eliminates backend complexity during development, and provides natural scalability through CloudFront's global CDN. Static hosting on S3 requires no server management, no per-request charges, and no database costs, making the platform sustainable indefinitely with minimal infrastructure overhead.

The client-side approach enables rapid iteration on game mechanics and simulation behavior without deploying backend changes. Modern React/Next.js tooling provides hot reloading, type safety with TypeScript, and component-based architecture that accelerates development velocity. For single-player session-based gameplay, localStorage provides sufficient persistence for save/resume functionality, with Zustand's persist middleware handling automatic state synchronization.

The architecture establishes a foundation for future server-side features. Game logic is structured in modular utilities that can run in either environment, allowing incremental migration when multiplayer, leaderboards, or analytics become priorities. Client-side state management remains for UI responsiveness while servers can validate critical operations, creating a hybrid architecture that preserves the benefits of both approaches.

2. System Overview

At its core, Operation: Black Swan follows a straightforward pattern: static assets served via CDN, game logic runs in browser, state persists locally, zero server infrastructure required for MVP.

┌─────────────────────────────────────────────────────────────────┐
│              OPERATION: BLACK SWAN SYSTEM                      │
│                                                                 │
│  ┌──────────────┐                                              │
│  │   Player     │                                              │
│  │   Browser    │                                              │
│  └──────┬───────┘                                              │
│         │                                                       │
│         │ HTTPS Request (Game URL)                             │
│         ▼                                                       │
│  ┌─────────────────┐                                           │
│  │  CloudFront CDN │                                           │
│  │  (Global Edge)  │                                           │
│  └──────┬──────────┘                                           │
│         │                                                       │
│         │ Cache Hit (Edge) or Origin Request                   │
│         ▼                                                       │
│  ┌─────────────────┐                                           │
│  │  S3 Bucket      │                                           │
│  │  (Static Files) │                                           │
│  └──────┬──────────┘                                           │
│         │                                                       │
│         │ Static Assets (HTML, JS, CSS, Images, Fonts)         │
│         ▼                                                       │
│  ┌─────────────────┐                                           │
│  │  Next.js App    │                                           │
│  │  (React + TS)   │                                           │
│  └──────┬──────────┘                                           │
│         │                                                       │
│         │ Game Logic (Client-Side Turn Processor)              │
│         ▼                                                       │
│  ┌─────────────────┐                                           │
│  │  Zustand Store  │                                           │
│  │  (Game State)   │                                           │
│  └──────┬──────────┘                                           │
│         │                                                       │
│         │ Auto-Save (Persist Middleware)                       │
│         ▼                                                       │
│  ┌─────────────────┐                                           │
│  │  localStorage   │                                           │
│  │  (Persistence)  │                                           │
│  └─────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘

Key Components

Frontend (Next.js Static Export)

• React 19.2.0 with TypeScript for type-safe game logic and component architecture
• Next.js 16.0.3 configured for static site generation (output: 'export')
• Tailwind CSS 4.1.9 for responsive, utility-first styling
• shadcn/ui components built on Radix UI primitives for consistent UX
• VT323 monospace font for terminal/cyberpunk aesthetic matching the game theme
• Recharts for data visualization (budget charts, throughput graphs, mission point trends)

State Management (Zustand)

• Lightweight state management library at 5KB gzipped
• Game state structure: turns, budget, connections, site-to-site links, events, mission points
• Automatic persistence to localStorage via Zustand persist middleware
• Resume capability: "Resume last game?" prompt on title screen if saved game exists
• State persists across page refreshes, browser restarts, and navigation

Hosting (AWS S3 + CloudFront)

• S3 Bucket: Static website hosting for HTML, JS, CSS, images, fonts
• CloudFront CDN: Global edge caching across 450+ points of presence, SSL/TLS termination, custom domain support
• Deployment: Simple aws s3 sync out/ s3://bucket-name --delete after build
• Auto-scaling: CloudFront automatically scales to handle any traffic volume without configuration

Game Logic (Client-Side Turn Processor)

• Turn-based game engine with configurable difficulty modes (Easy, Standard, Expert, Custom)
• Budget system with starting budgets, recurring budgets (every 5 turns), and optional budget delays
• Connection building mechanics (Dedicated, Hosted, IP Tunnel) with randomized build times
• Site-to-site capacity sharing with bidirectional links and hub limits (max 4 per site)
• Event system (outages, delays) with probability-based triggers and duration randomization
• Two-phase throughput calculation algorithm (direct connections → site-to-site sharing)
• Mission points tracking with win/loss conditions and event-based bonuses
• Resiliency token system (Operational Excellence protection from connection loss)

Persistence (localStorage)

• Automatic save on every state change via Zustand persist middleware
• Single game session with resume capability (no multi-save slots in MVP)
• No server-side persistence required—game state lives entirely in browser
• State structure includes: turn, budget, connections[], siteToSiteConnections[], events[], missionPoints, settings