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 to a **modular architecture** optimized for Claude Code development with hot-reloadable modules.

**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-modulaire.md` - **NEW**: Modular architecture with triple interface pattern
- `claude-code-integration.md` - **NEW**: Claude Code development optimization
- `architecture-technique.md` - Multi-server architecture, 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
- `transport-economic-system.md` - **NEW**: Transport hierarchy and economic optimization
- `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

### Modular Architecture (NEW)
- **Triple Interface Pattern**: IEngine, IModuleSystem, IModule(`process()`, `initialize()`, `shutdown()`), IIO
- **Autonomous Modules**: Small (200-300 lines) hot-reloadable modules (.so files)
- **Claude Code Optimized**: Each module is a micro-context for AI development
- **Performance Targets**: V1 Client 30+ fps, V2 Client 60+ fps, V1 Server 10+ players, V2 Server 100+ players (Points 98-103)
- **Implementation Status**: Transitioning from 10 engines to modular system

### 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**: **Architecture Migration** - Transitioning from 10 engines to modular architecture
- **Build System**: Module-based CMake with autonomous builds per module
- **Development Ready**: Hot-reload modules, 5-second iteration cycles
- **Next Steps**: Module implementations (TankModule, EconomyModule, FactoryModule)
- **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

## Module Constraints (CRITICAL)
- **NEVER** `#include "../"` ou cmake ..
- **JSON only** communication entre modules
- **Build autonome** : `cd modules/X/ && cmake .`
- **Exception ProductionModule** : Belt+Inserter+Factory MUST cohabiter (500-800 lignes acceptées)
- **ISocket Overhead** : >1ms INACCEPTABLE pour ProductionModule (Point 104)

### Important Files for Context
- Start with `architecture-modulaire.md` for new modular architecture
- Read `claude-code-integration.md` for AI-optimized development
- Reference `vue-ensemble.md` for project vision
- Check `coherence-problem.md` for resolved design challenges
- Use `questions-ouvertes.md` for known open issues

## Build System and Development

### Build Commands
```bash
# CRITICAL: Module autonome uniquement (Point 87)
cd modules/tank/ && cmake .    # NEVER cmake ..
make tank-module               # Builds tank.so
./build/tank-module           # Test standalone

# Core system
cmake . && make warfactory-core # Build core engine

# All modules
make warfactory-modules         # Build all modules
```

### Project Structure
```
├── modules/                    # Autonomous hot-reloadable modules
│   ├── tank/                   # Tank behavior module (200 lines)
│   ├── economy/                # Market simulation module
│   ├── factory/                # Production module
│   ├── transport/              # Transport optimization module
│   └── [each with CLAUDE.md, CMakeLists.txt, src/]
├── core/                       # Core engine with IEngine, IModuleSystem
│   ├── interfaces/             # IModule, IIO definitions
│   └── loaders/                # Module hot-reload system
├── 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. **Module isolation**: Work in `modules/*/` with autonomous builds
2. **Hot-reload**: Edit module → Save → Instant reload with state preservation
3. **Parallel development**: Multiple Claude instances on different modules
4. **Config-driven**: Most gameplay tweaks via JSON configs
5. **5-second iteration**: Edit → cmake . → make → test
6. **Testing**: `#ifdef TESTING` validation autonome, standalone testing

## Claude Code Development Practices (Points 351-390)

### Context Management (CRITICAL)
- **Small Modules**: Compact modules for focused development (micro-contexts)
- **Context Optimization**: Massive context reduction through modular design
- **Iteration Speed**: 5-10 min → 5 sec (60-120x faster)
- **Development Velocity**: 10x improvement through module isolation

### Parallel Development Patterns
- **Multiple Instances**: 3+ Claude Code instances simultaneous development
- **Zero Conflicts**: Independent module development without merge conflicts
- **Git-Friendly**: Isolated commits per module
- **Non-Blocking**: Developers work on different modules without coordination

### Build Constraints (NEVER/ALWAYS Rules)
- **NEVER `cd ..`**: Jamais référence directories parent modules
- **ALWAYS `cmake .`**: Builds autonomes par module (NEVER cmake ..)
- **NEVER `#include "../"`**: Isolation modules stricte
- **ONLY JSON Communication**: Communication entre modules via JSON uniquement
- **ZERO Infrastructure Code**: Aucun code infrastructure dans contexts modules

### Testing Strategy (AI-Optimized)
- **Simple Tests**: Tests unitaires légers, pas infrastructure complexe
- **Standalone Testing**: Test modules sans engine complet
- **`#ifdef TESTING`**: Validation autonome intégrée modules
- **Quick Feedback**: Tests rapides pour iteration loops Claude Code

### 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