Project Genesis - Sandbox Engine

Architecture Philosophy

Contract-Driven, Zero-Trust, High-Concurrency Development.

Every module is a black box behind a strict interface. 100 SWE sub-agents can work in parallel because:

1. Interfaces are read-only contracts (immutable once published).
2. Each agent owns exactly one module directory.
3. Tests are the source of truth, not the implementation.

Directory Layout

genesis/
├── interfaces/           # IMMUTABLE CONTRACTS (read-only for all agents)
│   ├── headers/          # C++ headers (.h) - pure virtual / abstract classes
│   └── traits/           # Rust traits (future expansion)
├── schemas/              # JSON Schemas for task tickets, configs
├── src/                  # IMPLEMENTATION (each subdir = one agent's workspace)
│   ├── core_tick/        # Fixed-timestep game loop, delta time, tick scheduling
│   ├── memory_pool/      # Custom allocators, pool/arena/stack allocators
│   ├── event_bus/        # Pub/sub event system, signal/slot, deferred events
│   ├── agent_math/       # Vectors, matrices, quaternions, noise functions
│   ├── ecs/              # Entity-Component-System data structures & scheduler
│   ├── physics/          # Broadphase, narrowphase, integrator, constraints
│   ├── render_graph/     # Render pass DAG, resource barriers, draw submission
│   ├── resource_manager/ # Asset loading, caching, hot-reload, streaming
│   └── scripting/        # Lua/JS VM bindings, coroutine scheduler
├── tests/
│   ├── unit/             # Per-module unit tests (mirror src/ structure)
│   ├── integration/      # Cross-module contract tests
│   └── contracts/        # Interface compliance tests (compile-only)
├── tasks/
│   ├── inbox/            # Pending task tickets (JSON files)
│   └── completed/        # Archived completed tickets
├── build/
│   └── cmake/            # CMake toolchain files
└── docs/
    └── architecture/     # ADRs (Architecture Decision Records)

Module Dependency Rules

core_tick       ← (no deps, foundational)
memory_pool     ← (no deps, foundational)
event_bus       ← depends on: memory_pool
agent_math      ← (no deps, pure math)
ecs             ← depends on: memory_pool, event_bus
physics         ← depends on: agent_math, ecs
render_graph    ← depends on: memory_pool, ecs
resource_manager← depends on: memory_pool, event_bus
scripting       ← depends on: event_bus, ecs

Dependency arrows flow one way. Circular dependencies are forbidden at the interface level.