Operation: Black Swan

8. Operational Considerations

Error Handling & Fault Tolerance

Client-Side Error Handling: Game logic includes validation to prevent invalid state transitions. Invalid actions are caught before state updates occur.

State Recovery: Game state is automatically saved to localStorage after each turn. Players can resume from the last saved state if the browser crashes or is closed.

Data Validation: All game state changes are validated before persistence. Corrupted state can be detected and reset to a valid state.

Observability

Client-Side Logging: Game events and state transitions can be logged to browser console for debugging. No server-side logging required for MVP.

State Inspection: Zustand DevTools enable real-time state inspection during development. Game state structure is transparent and debuggable.

Performance Monitoring: Browser DevTools provide performance metrics. Bundle size and load times are optimized for fast initial load.

Security

Client-Side Validation: All game logic runs client-side. For single-player gameplay, client-side validation is sufficient.

State Integrity: Game state stored in localStorage is device-specific. No cross-device synchronization or server-side validation required for MVP.

HTTPS Enforcement: CloudFront enforces SSL/TLS for all connections, ensuring secure data transmission.

Deployment & Hosting

Static Site Generation: Next.js generates static HTML, CSS, and JavaScript files. No server-side rendering or build-time dependencies required.

CDN Distribution: CloudFront CDN provides global edge caching, delivering content from the nearest edge location for optimal performance.

Version Control: S3 versioning enables rollback capability. Previous versions can be restored if needed.

Cache Invalidation: CloudFront cache can be invalidated for instant updates after deployment, or allowed to expire naturally.

Future Evolution

The current client-side architecture provides a solid foundation that can evolve to support server-side features when needed:

• Authoritative Game Logic: Server-side validation for multiplayer or competitive play
• Analytics & Telemetry: Track player behavior, game completion rates, difficulty balancing
• Multiplayer Features: Competitive play, leaderboards, shared challenges
• Persistence Across Devices: Save games to cloud, resume on any device
• Anti-Cheat: Validate player actions, detect exploits

Migration Path: Architecture designed for incremental migration. Game logic can be extracted to shared utilities that run client or server-side. Client-side state management remains for UI responsiveness while server validates critical operations.

9. Player Experience

Game Flow

Players experience a turn-based strategy game where each decision matters:

• Strategic Planning: Budget constraints force prioritization and long-term thinking
• Uncertainty Management: Randomized build times and events create adaptive challenges
• Network Design: Players balance direct connections and site-to-site capacity sharing strategies
• Resilience Testing: Events test whether players built truly resilient architectures

Difficulty Progression

Four difficulty modes provide clear progression paths:

• Easy Mode: Learn basic mechanics with smaller scope (3 sites, 20 turns)
• Standard Mode: Balanced challenge for first-time players (5 sites, 25 turns)
• Expert Mode: Maximum challenge with budget delays and no safety nets (10 sites, 0 tokens)
• Custom Mode: Fine-tune parameters to create unique challenges

Feedback & Learning

The game provides clear feedback to help players learn and improve:

• Mission Points: Immediate feedback on performance each turn
• Requirement Tracking: Visual indicators show which sites meet throughput requirements
• Budget Visibility: Clear budget tracking helps players plan spending
• Event Notifications: Players understand what went wrong and can plan countermeasures
• Win/Loss Conditions: Clear goals and failure states guide strategic decisions

Replayability

Multiple factors contribute to high replay value:

• Randomization: Build times, event timing, and event durations vary each playthrough
• Strategic Variety: Multiple valid approaches (direct connections, site-to-site networks, hybrid strategies)
• Difficulty Modes: Four distinct difficulty levels plus custom configuration
• Optimization Challenges: Players can try to beat their best scores or minimize spending
• Different Network Topologies: Star, mesh, or hybrid network designs each have trade-offs

10. Conclusion

Operation: Black Swan's architecture demonstrates how a client-first approach can deliver a sophisticated interactive experience with minimal infrastructure. The phased architecture allows rapid MVP development while maintaining a clear path to server-side features when needed.

Future Enhancements:

• Server-side validation for authoritative game logic
• Analytics and telemetry for player behavior tracking
• Multiplayer features (competitive play, leaderboards)
• Cloud persistence for cross-device gameplay
• Advanced event generation and dynamic difficulty adjustment
• AI opponents and procedural content generation

The architecture continues to evolve as new requirements emerge, but the core principles—client-first simplicity, serverless scalability, and incremental enhancement—remain the foundation for everything we build.