warfactoryracine/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Warfactory** is a Factorio-inspired industrial military simulation game combining factory management with strategic military doctrine. The project has evolved from design/documentation phase to **functional implementation** with a complete 10-engine architecture and comprehensive build system.

**Core Philosophy:**
- Factory assembly lines as gameplay foundation
- Player-driven military doctrine development
- Progression from PMC operations to conventional warfare
- Choice and complexity balanced with accessible presentation

## Documentation Architecture

The project uses a modular documentation system in `/docs/`:

### Core Design Documents
- `vue-ensemble.md` - Vision, philosophy, and design principles
- `architecture-technique.md` - Multi-server architecture, engines, performance specs
- `systemes-techniques.md` - Tile system, memory management, chunks
- `map-system.md` - Procedural generation with 218+ elements, budget system (-10 to +10)

### Gameplay Systems
- `gameplay-industriel.md` - Resource flow, production, factory optimization
- `systeme-militaire.md` - Vehicle design with grid-based component placement
- `economie-logistique.md` - Market simulation, supply chains, pricing
- `mecaniques-jeu.md` - Research systems, breakthrough mechanics, administration

### Advanced Systems
- `arbre-technologique.md` - 3000+ technology tree with prerequisites gating
- `metriques-joueur.md` - Comprehensive analytics (3.1GB per game, adaptive scaling)
- `coherence-problem.md` - Resolved design contradictions and technical challenges

## Key Technical Concepts

### Engine Architecture
- **Autonomous Engines**: 10 specialized engines (Designer, Economy, Event, Factory, Intelligence, Logistic, MacroEntity, Map, Operation, War)
- **Smart Client**: Request/response pattern, no streaming, FOW at chunk granularity
- **Performance Target**: 60fps with 1000+ AI companies, 1-2 vehicle designs/tick globally
- **Implementation Status**: All engines have functional stub implementations with threading and main loops

### Map System
- **Multi-scale**: World (diplomatic) → Regional (logistics) → Local (factory) → Detail (combat)
- **Procedural Generation**: 218 elements with budget scoring, millions of combinations
- **Chunk System**: 64x64 tiles, streaming on demand, persistent storage

### Military Design
- **Grid-based Vehicle Design**: Irregular chassis shapes with component placement
- **Interface**: Pick/place with A/E rotation, R for snap toggle, template support
- **Combat**: Multi-chunk battles, persistent frontlines, auto-battler with player oversight

## Development Context

### Resolved Issues
Most initial "coherence problems" (P1-P30) were invalidated through clarification:
- Architecture scales properly with smart resource management
- Interface complexity is standard for genre (comparable to Factorio, Tarkov inventory)
- Performance targets achievable with proper optimization
- Only P7 (engine responsibilities) requires further analysis

### Current Status
- **Phase**: **Implementation active** - All 10 engines functional with CMake build system
- **Build System**: Comprehensive CMake with defensive programming, sanitizers, and 16 C++ libraries
- **Development Ready**: Fast/full build presets, optimized workflow for daily iteration
- **Next Steps**: Engine logic expansion, inter-engine communication, gameplay features
- **Questions Open**: 11 items in `questions-ouvertes.md` for future resolution

## Working with This Project

### Documentation Updates
- Cross-reference systems when making changes (especially architecture ↔ gameplay)
- Maintain coherence between technical specs and game design
- Update `coherence-problem.md` if new conflicts emerge

### Key Design Constraints
- **Skip-ability**: All systems must be automatable for accessibility
- **Depth vs Accessibility**: Complex systems with simple interfaces
- **Performance**: Real-time constraints with large-scale simulation
- **Realism**: Military authenticity balanced with gameplay fun

### Important Files for Context
- Start with `vue-ensemble.md` for project vision
- Reference `architecture-technique.md` for technical decisions
- Check `coherence-problem.md` for resolved design challenges
- Use `questions-ouvertes.md` for known open issues

## Build System and Development

### Build Commands
```bash
# Fast development build (minimal sanitizers, ~30s)
cmake -DFAST_BUILD=ON .. && make claude-workflow-fast

# Full validation build (all sanitizers + static analysis)
cmake -DCMAKE_BUILD_TYPE=Debug .. && make

# Release build (optimized, stack protection)
cmake .. && make

# Single engine development
make economy-engine && ./bin/economy-engine
```

### Project Structure
```
├── engines/                    # 10 autonomous engines
│   ├── Designer-Engine/        # Vehicle design with AI assistance
│   ├── Economy-Engine/         # Market simulation, pricing
│   ├── Event-Engine/           # Breakthrough system, global events
│   ├── Factory-Engine/         # Factorio-like production
│   ├── Intelligence-Engine/    # Metrics collection, reconnaissance
│   ├── Logistic-Engine/        # Supply chains, transport
│   ├── MacroEntity-Engine/     # Companies, diplomacy, administration
│   ├── Map-Engine/             # Procedural generation, chunks, FOW
│   ├── Operation-Engine/       # Military strategy, AI generals
│   └── War-Engine/             # Combat simulation, frontlines
├── cmake/                      # Build system configuration
│   ├── WarfactoryDefenses.cmake    # Defensive programming
│   ├── WarfactoryAutomation.cmake  # 16 C++ libraries
│   └── WarfactoryAdvancedTools.cmake # Static analysis, testing
├── build/                      # Build artifacts (git ignored)
│   └── bin/                    # Final executables
└── docs/                       # Complete design documentation
```

### Development Workflow
1. **Fast iteration**: Use `FAST_BUILD=ON` for daily development
2. **Single engine**: `make economy-engine` for focused work
3. **Full validation**: Debug build with all sanitizers before commit
4. **Engine-specific development**: Work directly in `engines/*/` directories
5. **Incremental builds**: CMake rebuilds only modified files (~2-5s)

### Dependencies and Libraries
The project includes 16 C++ libraries via FetchContent:
- **Networking**: zeromq, cppzmq, redis-plus-plus, cpprestsdk
- **Logging**: spdlog, fmt
- **Memory**: Microsoft GSL, foonathan/memory
- **Testing**: Catch2, Google Test, Google Benchmark
- **Utilities**: nlohmann/json, fifo_map, junction+turf, pcg-cpp
- **Navigation**: recastnavigation, abseil-cpp
- **Graphics**: imgui, sqlite

### Defensive Programming Features
- **Sanitizers**: AddressSanitizer, UndefinedBehaviorSanitizer, LeakSanitizer
- **Static Analysis**: Clang Static Analyzer, Cppcheck, PVS-Studio integration
- **Contract Programming**: GSL contracts, custom assertion macros
- **Compiler Hardening**: Stack protection, frame pointers, maximum debug info
- **Memory Safety**: Smart pointers, RAII patterns, leak detection