# YAZE Dependency Architecture & Build Optimization **Author**: Claude (Anthropic AI Assistant) **Date**: 2025-10-13 **Status**: Reference Document **Related Docs**: [C4-z3ed-refactoring.md](C4-z3ed-refactoring.md), [B6-zelda3-library-refactoring.md](B6-zelda3-library-refactoring.md), [A2-test-dashboard-refactoring.md](A2-test-dashboard-refactoring.md) --- ## Executive Summary This document provides a comprehensive analysis of YAZE's dependency architecture, identifies optimization opportunities, and proposes a roadmap for reducing build times and improving maintainability. ### Key Findings - **Current State**: 25+ static libraries with complex interdependencies - **Main Issues**: Circular dependencies, over-linking, misplaced components - **Build Impact**: Changes to foundation libraries trigger rebuilds of 10-15+ dependent libraries - **Opportunity**: 40-60% faster incremental builds through proposed refactorings ### Quick Stats | Metric | Current | After Refactoring | |--------|---------|-------------------| | Total Libraries | 28 | 35 (more granular) | | Circular Dependencies | 2 | 0 | | Average Link Depth | 5-7 layers | 3-4 layers | | Incremental Build Time | Baseline | **40-60% faster** | | Test Isolation | Poor | Excellent | --- ## 1. Complete Dependency Graph ### 1.1 Foundation Layer ``` ┌─────────────────────────────────────────────────────────────────┐ │ External Dependencies │ │ • SDL2 (graphics, input, audio) │ │ • ImGui (UI framework) │ │ • Abseil (utilities, status, flags) │ │ • GoogleTest/GoogleMock (testing) │ │ • gRPC (optional - networking) │ │ • nlohmann_json (optional - JSON) │ │ • yaml-cpp (configuration) │ │ • FTXUI (terminal UI) │ │ • Asar (65816 assembler) │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ yaze_common │ │ • Common platform definitions │ │ • No dependencies │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ yaze_util │ │ • Logging, file I/O, SDL utilities │ │ • Depends on: yaze_common, absl, SDL2 │ └─────────────────────────────────────────────────────────────────┘ ``` ### 1.2 Graphics Tier (Refactored) ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_gfx (INTERFACE - aggregates all gfx sub-libraries) │ └────────────────────────┬────────────────────────────────────────┘ │ ┌──────────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────────┐ ┌─────────────┐ │ gfx_debug│─────│ gfx_render │ │ gfx_util │ └──────────┘ └──────┬───────┘ └─────┬───────┘ │ │ └─────────┬─────────┘ ▼ ┌──────────────┐ │ gfx_core │ │ (Bitmap) │ └──────┬───────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌──────────┐ ┌──────────┐ │ gfx_types │ │gfx_resource│ │gfx_backend│ │ (SNES data)│ │ (Arena) │ │ (SDL2) │ └────────────┘ └──────────┘ └──────────┘ Dependencies: • gfx_types → (none - foundation) • gfx_backend → SDL2 • gfx_resource → gfx_backend • gfx_core → gfx_types + gfx_resource • gfx_render → gfx_core + gfx_backend • gfx_util → gfx_core • gfx_debug → gfx_util + gfx_render ``` **Note**: `gfx_resource` (Arena) depends on `gfx_render` (BackgroundBuffer) but this is acceptable as both are low-level resource management. Not circular because gfx_render doesn't depend back on gfx_resource. ### 1.3 GUI Tier (Refactored) ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_gui (INTERFACE - aggregates all gui sub-libraries) │ └────────────────────────┬────────────────────────────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌────────────┐ ┌────────────┐ │ gui_app │ │gui_automation│ │gui_widgets │ └────┬─────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ └──────────────┼───────────────┘ ▼ ┌──────────────────┐ │ gui_canvas │ └─────────┬────────┘ ▼ ┌──────────────────┐ │ gui_core │ │ (Theme, Input) │ └──────────────────┘ Dependencies: • gui_core → yaze_util + ImGui + nlohmann_json • gui_canvas → gui_core + yaze_gfx • gui_widgets → gui_core + yaze_gfx • gui_automation → gui_core • gui_app → gui_core + gui_widgets + gui_automation ``` ### 1.4 Zelda3 Library (Current - Monolithic) ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_zelda3 (MONOLITHIC - needs refactoring per B6) │ │ • Overworld (maps, tiles, warps) │ │ • Dungeon (rooms, objects, layouts) │ │ • Sprites (entities, overlords) │ │ • Screens (title, inventory, dungeon map) │ │ • Music (tracker - legacy Hyrule Magic code) │ │ • Labels & constants │ │ │ │ Depends on: yaze_gfx, yaze_util, yaze_common, absl │ └─────────────────────────────────────────────────────────────────┘ Warning: ISSUE: Located at src/app/zelda3/ but used by both app AND cli Warning: ISSUE: Monolithic - any change rebuilds entire library ``` ### 1.5 Zelda3 Library (Proposed - Tiered) ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_zelda3 (INTERFACE - aggregates sub-libraries) │ └────────────────────────┬────────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │zelda3_screen│───│zelda3_dungeon│──│zelda3_overworld│ └────────────┘ └──────┬─────┘ └──────┬──────┘ │ │ ┌─────────────────┼─────────────────┘ │ │ ▼ ▼ ┌────────────┐ ┌────────────┐ │zelda3_music│ │zelda3_sprite│ └──────┬─────┘ └──────┬─────┘ │ │ └────────┬────────┘ ▼ ┌───────────────┐ │ zelda3_core │ │ (Labels, │ │ constants) │ └───────────────┘ Benefits: Location: src/zelda3/ (proper top-level shared lib) Granular: Change dungeon logic → only rebuilds dungeon + dependents Clear boundaries: Separate overworld/dungeon/sprite concerns Legacy isolation: Music tracker separated from modern code ``` ### 1.6 Core Libraries ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_core_lib (Warning: CIRCULAR DEPENDENCY RISK) │ │ • ROM management (rom.cc) │ │ • Window/input (window.cc) │ │ • Asar wrapper (asar_wrapper.cc) │ │ • Platform utilities (file dialogs, fonts, clipboard) │ │ • Project management (project.cc) │ │ • Controller (controller.cc) │ │ • gRPC services (optional - test harness, ROM service) │ │ │ │ Depends on: yaze_util, yaze_gfx, yaze_zelda3, yaze_common, │ │ ImGui, asar-static, SDL2, (gRPC) │ └─────────────────────────────────────────────────────────────────┘ ↓ Warning: CIRCULAR: yaze_gfx → depends on gfx_resource (Arena) Arena.h includes background_buffer.h (from gfx_render) gfx_render → gfx_core → gfx_resource BUT yaze_core_lib → yaze_gfx If anything in core_lib needs gfx_resource internals, we get: core_lib → gfx → gfx_resource → (potentially) core_lib ┌─────────────────────────────────────────────────────────────────┐ │ yaze_emulator │ │ • CPU (65C816) │ │ • PPU (graphics) │ │ • APU (audio - SPC700 + DSP) │ │ • Memory, DMA │ │ • Input management │ │ • Debugger UI components │ │ │ │ Depends on: yaze_util, yaze_common, yaze_core_lib, absl, SDL2 │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ yaze_net │ │ • ROM version management │ │ • WebSocket client │ │ • Collaboration service │ │ • ROM service (gRPC - disabled) │ │ │ │ Depends on: yaze_util, yaze_common, absl, (OpenSSL), (gRPC) │ └─────────────────────────────────────────────────────────────────┘ ``` ### 1.7 Application Layer ``` ┌─────────────────────────────────────────────────────────────────┐ │ yaze_test_support (Warning: CIRCULAR WITH yaze_editor) │ │ • TestManager (core test infrastructure) │ │ • z3ed test suite │ │ │ │ Depends on: yaze_editor, yaze_core_lib, yaze_gui, yaze_zelda3, │ │ yaze_gfx, yaze_util, yaze_common, yaze_agent │ └────────────────────────┬────────────────────────────────────────┘ │ │ Warning: CIRCULAR DEPENDENCY ↓ ┌─────────────────────────────────────────────────────────────────┐ │ yaze_editor │ │ • Dungeon editor │ │ • Overworld editor │ │ • Sprite editor │ │ • Graphics/palette editors │ │ • Message editor │ │ • Assembly editor │ │ • System editors (settings, commands) │ │ • Agent integration (AI features) │ │ │ │ Depends on: yaze_core_lib, yaze_gfx, yaze_gui, yaze_zelda3, │ │ yaze_emulator, yaze_util, yaze_common, ImGui, │ │ [yaze_agent], [yaze_test_support] (conditional) │ └────────────────────────┬────────────────────────────────────────┘ │ │ Links back to test_support when YAZE_BUILD_TESTS=ON └───────────────────────────────────────────┐ │ ▼ Warning: CIRCULAR DEPENDENCY ┌─────────────────────────────────────────────────────────────────┐ │ yaze_agent (Warning: LINKS TO ALMOST EVERYTHING) │ │ • Command handlers (resource, dungeon, overworld, graphics) │ │ • AI services (Ollama, Gemini) │ │ • GUI automation client │ │ • TUI system (enhanced terminal UI) │ │ • Planning/proposal system │ │ • Test generation │ │ • Conversation management │ │ │ │ Depends on: yaze_common, yaze_util, yaze_gfx, yaze_gui, │ │ yaze_core_lib, yaze_zelda3, yaze_emulator, absl, │ │ yaml-cpp, ftxui, (gRPC), (nlohmann_json), (OpenSSL) │ └─────────────────────────────────────────────────────────────────┘ Warning: ISSUE: yaze_agent is massive and pulls in the entire application stack Even simple CLI commands link against graphics, GUI, emulator, etc. ``` ### 1.8 Executables ``` ┌────────────────────────────────────────────────────────────────┐ │ yaze (Main Application) │ │ │ │ Links: yaze_editor, yaze_emulator, yaze_core_lib, yaze_agent, │ │ [yaze_test_support] (conditional), ImGui, SDL2 │ │ │ │ Transitively gets: All libraries through yaze_editor │ └────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ z3ed (CLI Tool) │ │ │ │ Links: yaze_agent, yaze_core_lib, yaze_zelda3, ftxui │ │ │ │ Transitively gets: All libraries through yaze_agent (!) │ │ Warning: ISSUE: CLI tool rebuilds if GUI/graphics/emulator changes │ └────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ yaze_emu (Standalone Emulator) │ │ │ │ Links: yaze_emulator, yaze_core_lib, ImGui, SDL2 │ │ │ │ Warning: Conditionally built with YAZE_BUILD_EMU=ON │ └────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ Test Executables │ │ │ │ yaze_test_stable: │ │ - Unit tests (asar, rom, gfx, gui, zelda3, cli) │ │ - Integration tests (dungeon, overworld, editor) │ │ - Links: yaze_test_support, gmock_main, gtest_main │ │ │ │ yaze_test_gui: │ │ - E2E GUI tests with ImGuiTestEngine │ │ - Links: yaze_test_support, ImGuiTestEngine │ │ │ │ yaze_test_rom_dependent: │ │ - Tests requiring actual ROM file │ │ - Only built when YAZE_ENABLE_ROM_TESTS=ON │ │ │ │ yaze_test_experimental: │ │ - AI integration tests (vision, tile placement) │ │ │ │ yaze_test_benchmark: │ │ - Performance benchmarks │ └────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Current Dependency Issues ### 2.1 Circular Dependencies #### Issue 1: yaze_test_support ↔ yaze_editor ``` yaze_test_support ├─→ yaze_editor (for EditorManager, Canvas, etc.) └─→ yaze_core_lib, yaze_gui, yaze_zelda3, ... yaze_editor (when YAZE_BUILD_TESTS=ON) └─→ yaze_test_support (for TestManager) Result: Neither can be built first, causes linking issues ``` **Impact**: - Confusing build order - Test dashboard cannot be excluded from release builds cleanly - Changes to test infrastructure force editor rebuilds **Solution** (from A2-test-dashboard-refactoring.md): ``` test_framework (core logic only) ├─→ yaze_util, absl (no app dependencies) test_suites (actual tests) ├─→ test_framework └─→ yaze_zelda3, yaze_gfx (only what's needed) test_dashboard (GUI component - OPTIONAL) ├─→ test_framework ├─→ yaze_gui └─→ Conditionally linked to yaze app yaze_editor └─→ (no test dependencies) ``` #### Issue 2: Potential yaze_core_lib ↔ yaze_gfx Cycle ``` yaze_core_lib └─→ yaze_gfx (for graphics operations) yaze_gfx └─→ gfx_resource (Arena) gfx_resource (Arena) └─→ Includes background_buffer.h (from gfx_render) └─→ Has BackgroundBuffer members (bg1_, bg2_) If yaze_core_lib internals ever need gfx_resource specifics: yaze_core_lib → yaze_gfx → gfx_resource → (back to) core_lib ❌ ``` **Current Status**: Not a problem yet, but risky **Solution**: Split yaze_core_lib into foundation vs services ### 2.2 Over-Linking Problems #### Problem 1: yaze_test_support Links to Everything ``` yaze_test_support dependencies: ├─→ yaze_editor (Warning: Brings in entire app stack) ├─→ yaze_core_lib ├─→ yaze_gui (Warning: Brings in all GUI widgets) ├─→ yaze_zelda3 ├─→ yaze_gfx (Warning: All 7 gfx libraries) ├─→ yaze_util ├─→ yaze_common └─→ yaze_agent (Warning: Brings in AI services, emulator, etc.) Result: Test executables link against THE ENTIRE APPLICATION ``` **Impact**: - Test binaries are massive (100+ MB) - Any change to any library forces test relink - Slow CI/CD pipeline - Cannot build minimal test suites **Solution**: - Separate test framework from test suites - Each test suite links only to what it tests - Remove yaze_editor from test framework #### Problem 2: yaze_agent Links to Everything ``` yaze_agent dependencies: ├─→ yaze_common ├─→ yaze_util ├─→ yaze_gfx (all 7 libs) ├─→ yaze_gui (all 5 libs) ├─→ yaze_core_lib ├─→ yaze_zelda3 ├─→ yaze_emulator ├─→ absl ├─→ yaml-cpp ├─→ ftxui ├─→ [gRPC] ├─→ [nlohmann_json] └─→ [OpenSSL] Result: z3ed CLI tool rebuilds if GUI changes! ``` **Impact**: - CLI tool (`z3ed`) is 80+ MB - Any GUI/graphics change forces CLI rebuild - Cannot build minimal agent for server deployment - Tight coupling between CLI and GUI **Solution**: ``` yaze_agent_core (minimal) ├─→ Command handling abstractions ├─→ TUI system (FTXUI) ├─→ yaze_util, yaze_common └─→ NO graphics, NO gui, NO emulator yaze_agent_services (full stack) ├─→ yaze_agent_core ├─→ yaze_gfx, yaze_gui (for GUI automation) ├─→ yaze_emulator (for emulator commands) └─→ yaze_zelda3 (for game logic queries) z3ed executable └─→ yaze_agent_core (minimal build) └─→ Optional: yaze_agent_services (full features) ``` #### Problem 3: yaze_editor Links to 8+ Major Libraries ``` yaze_editor dependencies: ├─→ yaze_core_lib ├─→ yaze_gfx (7 libs transitively) ├─→ yaze_gui (5 libs transitively) ├─→ yaze_zelda3 ├─→ yaze_emulator ├─→ yaze_util ├─→ yaze_common ├─→ ImGui ├─→ [yaze_agent] (conditional) └─→ [yaze_test_support] (conditional) Result: Changes to ANY of these trigger editor rebuild ``` **Impact**: - 60+ second editor rebuilds on gfx changes - Tight coupling across entire application - Difficult to isolate editor features - Hard to test individual editors **Mitigation** (already done for gfx/gui): - gfx refactored into 7 granular libs - gui refactored into 5 granular libs - Next: Refactor zelda3 into 6 granular libs - Next: Split editor into editor modules ### 2.3 Misplaced Components #### Issue 1: zelda3 Library Location ``` Current: src/app/zelda3/ └─→ Implies it's part of GUI application Reality: Used by both yaze app AND z3ed CLI └─→ Should be top-level shared library Problem: cli/ cannot depend on app/ (architectural violation) ``` **Solution** (from B6-zelda3-library-refactoring.md): - Move: `src/app/zelda3/` → `src/zelda3/` - Update all includes: `#include "app/zelda3/...` → `#include "zelda3/...` - Establish as proper shared core component #### Issue 2: Test Infrastructure Mixed into App ``` Current: src/app/test/ └─→ test_manager.cc (core logic + GUI dashboard) └─→ z3ed_test_suite.cc (test implementation) Problem: Cannot exclude test dashboard from release builds Cannot build minimal test framework ``` **Solution** (from A2-test-dashboard-refactoring.md): - Move: `src/app/test/` → `src/test/framework/` + `src/test/suites/` - Separate: `TestManager` (core) from `TestDashboard` (GUI) - Make: `test_dashboard` conditionally compiled --- ## 3. Build Time Impact Analysis ### 3.1 Current Rebuild Cascades #### Scenario 1: Change snes_tile.cc (gfx_types) ``` snes_tile.cc (gfx_types) ↓ yaze_gfx_core (depends on gfx_types) ↓ yaze_gfx_util + yaze_gfx_render (depend on gfx_core) ↓ yaze_gfx_debug (depends on gfx_util + gfx_render) ↓ yaze_gfx (INTERFACE - aggregates all) ↓ yaze_gui_core + yaze_canvas + yaze_gui_widgets (depend on yaze_gfx) ↓ yaze_gui (INTERFACE - aggregates all) ↓ yaze_core_lib (depends on yaze_gfx + yaze_gui) ↓ yaze_editor + yaze_agent + yaze_net (depend on core_lib) ↓ yaze_test_support (depends on yaze_editor) ↓ All test executables (depend on yaze_test_support) ↓ yaze + z3ed + yaze_emu (main executables) TOTAL: 20+ libraries rebuilt, 6+ executables relinked TIME: 5-10 minutes on CI, 2-3 minutes locally ``` #### Scenario 2: Change overworld_map.cc (zelda3) ``` overworld_map.cc (yaze_zelda3 - monolithic) ↓ yaze_zelda3 (ENTIRE library rebuilt) ↓ yaze_core_lib (depends on yaze_zelda3) ↓ yaze_editor + yaze_agent (depend on core_lib) ↓ yaze_test_support (depends on yaze_editor + yaze_agent) ↓ All test executables ↓ yaze + z3ed executables TOTAL: 8+ libraries rebuilt, 6+ executables relinked TIME: 3-5 minutes on CI, 1-2 minutes locally ``` #### Scenario 3: Change test_manager.cc ``` test_manager.cc (yaze_test_support) ↓ yaze_test_support ↓ yaze_editor (links to test_support when YAZE_BUILD_TESTS=ON) ↓ yaze + z3ed (link to yaze_editor) ↓ All test executables (link to yaze_test_support) TOTAL: 3 libraries rebuilt, 8+ executables relinked TIME: 1-2 minutes Warning: CIRCULAR: Editor change forces test rebuild, Test change forces editor rebuild ``` ### 3.2 Optimized Rebuild Cascades (After Refactoring) #### Scenario 1: Change snes_tile.cc (gfx_types) - Optimized ``` snes_tile.cc (gfx_types) ↓ yaze_gfx_core (depends on gfx_types) ↓ yaze_gfx_util + yaze_gfx_render (depend on gfx_core) STOP: Changes don't affect gfx_backend or gfx_resource STOP: gui libraries still use old gfx INTERFACE Only rebuilt if consumers explicitly use changed APIs: - yaze_zelda3 (if it uses modified tile functions) - Specific editor modules (if they use modified functions) TOTAL: 3-5 libraries rebuilt, 1-2 executables relinked TIME: 30-60 seconds on CI, 15-30 seconds locally SAVINGS: 80% faster! ``` #### Scenario 2: Change overworld_map.cc (zelda3) - Optimized ``` With refactored zelda3: overworld_map.cc (zelda3_overworld sub-library) ↓ yaze_zelda3_overworld (only this sub-library rebuilt) STOP: zelda3_dungeon, zelda3_sprite unchanged STOP: zelda3_screen depends on overworld but may not need rebuild Only rebuilt if consumers use changed APIs: - yaze_editor_overworld_module - Specific overworld tests - z3ed overworld commands TOTAL: 2-3 libraries rebuilt, 1-2 executables relinked TIME: 30-45 seconds on CI, 15-20 seconds locally SAVINGS: 70% faster! ``` #### Scenario 3: Change test_manager.cc - Optimized ``` With separated test infrastructure: test_manager.cc (test_framework) ↓ test_framework STOP: test_suites may not need rebuild (depends on interface changes) STOP: test_dashboard is separate, doesn't rebuild STOP: yaze_editor has NO dependency on test system Only rebuilt: - test_framework - Test executables (yaze_test_*) TOTAL: 1 library rebuilt, 5 test executables relinked TIME: 20-30 seconds on CI, 10-15 seconds locally SAVINGS: 60% faster! Warning: BONUS: Release builds exclude test_dashboard entirely → Smaller binary, faster builds, cleaner architecture ``` ### 3.3 Build Time Savings Summary | Change Type | Current Time | After Refactoring | Savings | |-------------|--------------|-------------------|---------| | gfx_types change | 5-10 min | 30-60 sec | **80%** | | zelda3 change | 3-5 min | 30-45 sec | **70%** | | Test infrastructure | 1-2 min | 20-30 sec | **60%** | | GUI widget change | 4-6 min | 45-90 sec | **65%** | | Agent change | 2-3 min | 30-45 sec | **50%** | **Overall Incremental Build Improvement**: **40-60% faster** across common development scenarios --- ## 4. Proposed Refactoring Initiatives ### 4.1 Priority 1: Execute Existing Proposals #### A. Test Dashboard Separation (A2) **Status**: Proposed **Priority**: HIGH **Effort**: Medium (2-3 days) **Impact**: 60% faster test builds, cleaner release builds **Implementation**: 1. Create `src/test/framework/` directory - Move `test_manager.h/cc` (core logic only) - Remove UI code from TestManager - Library: `yaze_test_framework` - Dependencies: `yaze_util`, `absl` 2. Create `src/test/suites/` directory - Move all `*_test_suite.h` files - Move `z3ed_test_suite.cc` - Library: `yaze_test_suites` - Dependencies: `yaze_test_framework`, specific yaze libs 3. Create `src/app/gui/testing/` directory - New `TestDashboard` class - Move `DrawTestDashboard` from TestManager - Library: `yaze_test_dashboard` - Dependencies: `yaze_test_framework`, `yaze_gui` - Conditional: `YAZE_WITH_TEST_DASHBOARD=ON` 4. Update build system - Root CMake: Add `option(YAZE_WITH_TEST_DASHBOARD "..." ON)` - app.cmake: Conditionally link `yaze_test_dashboard` - Remove circular dependency **Benefits**: - No circular dependencies - Release builds exclude test dashboard - Test changes don't rebuild editor - Cleaner architecture #### B. Zelda3 Library Refactoring (B6) **Status**: Proposed **Priority**: HIGH **Effort**: Large (4-5 days) **Impact**: 70% faster zelda3 builds, proper shared library **Phase 1: Physical Move** ```bash # Move directory mv src/app/zelda3 src/zelda3 # Update CMakeLists.txt sed -i 's|include(zelda3/zelda3_library.cmake)|include(zelda3/zelda3_library.cmake)|' src/CMakeLists.txt # Global include update find . -type f \( -name "*.cc" -o -name "*.h" \) -exec sed -i 's|#include "app/zelda3/|#include "zelda3/|g' {} + # Test build cmake --preset mac-dev && cmake --build --preset mac-dev ``` **Phase 2: Decompose into Sub-Libraries** ```cmake # src/zelda3/zelda3_library.cmake # 1. Foundation set(ZELDA3_CORE_SRC zelda3/common.h zelda3/zelda3_labels.cc zelda3/palette_constants.cc zelda3/dungeon/dungeon_rom_addresses.h ) add_library(yaze_zelda3_core STATIC ${ZELDA3_CORE_SRC}) target_link_libraries(yaze_zelda3_core PUBLIC yaze_util) # 2. Sprite (shared by dungeon + overworld) set(ZELDA3_SPRITE_SRC zelda3/sprite/sprite.cc zelda3/sprite/sprite_builder.cc zelda3/sprite/overlord.h ) add_library(yaze_zelda3_sprite STATIC ${ZELDA3_SPRITE_SRC}) target_link_libraries(yaze_zelda3_sprite PUBLIC yaze_zelda3_core) # 3. Dungeon set(ZELDA3_DUNGEON_SRC zelda3/dungeon/room.cc zelda3/dungeon/room_layout.cc zelda3/dungeon/room_object.cc zelda3/dungeon/object_parser.cc zelda3/dungeon/object_drawer.cc zelda3/dungeon/dungeon_editor_system.cc zelda3/dungeon/dungeon_object_editor.cc ) add_library(yaze_zelda3_dungeon STATIC ${ZELDA3_DUNGEON_SRC}) target_link_libraries(yaze_zelda3_dungeon PUBLIC yaze_zelda3_core yaze_zelda3_sprite ) # 4. Overworld set(ZELDA3_OVERWORLD_SRC zelda3/overworld/overworld.cc zelda3/overworld/overworld_map.cc ) add_library(yaze_zelda3_overworld STATIC ${ZELDA3_OVERWORLD_SRC}) target_link_libraries(yaze_zelda3_overworld PUBLIC yaze_zelda3_core yaze_zelda3_sprite ) # 5. Screen set(ZELDA3_SCREEN_SRC zelda3/screen/title_screen.cc zelda3/screen/inventory.cc zelda3/screen/dungeon_map.cc zelda3/screen/overworld_map_screen.cc ) add_library(yaze_zelda3_screen STATIC ${ZELDA3_SCREEN_SRC}) target_link_libraries(yaze_zelda3_screen PUBLIC yaze_zelda3_dungeon yaze_zelda3_overworld ) # 6. Music (legacy isolation) set(ZELDA3_MUSIC_SRC zelda3/music/tracker.cc ) add_library(yaze_zelda3_music STATIC ${ZELDA3_MUSIC_SRC}) target_link_libraries(yaze_zelda3_music PUBLIC yaze_zelda3_core) # Aggregate INTERFACE library add_library(yaze_zelda3 INTERFACE) target_link_libraries(yaze_zelda3 INTERFACE yaze_zelda3_core yaze_zelda3_sprite yaze_zelda3_dungeon yaze_zelda3_overworld yaze_zelda3_screen yaze_zelda3_music ) ``` **Benefits**: - Proper top-level shared library - Granular rebuilds (change dungeon → only dungeon + screen rebuild) - Clear domain boundaries - Legacy code isolated #### C. z3ed Command Abstraction (C4) **Status**: **COMPLETED** **Priority**: N/A (already done) **Impact**: 1300+ lines eliminated, 50-60% smaller command implementations **Achievements**: - Command abstraction layer (`CommandContext`, `ArgumentParser`, `OutputFormatter`) - Enhanced TUI with themes and autocomplete - Comprehensive test coverage - AI-friendly predictable structure **Next Steps**: None required, refactoring complete ### 4.2 Priority 2: New Refactoring Proposals #### D. Split yaze_core_lib to Prevent Cycles **Status**: Proposed (New) **Priority**: MEDIUM **Effort**: Medium (2-3 days) **Impact**: Prevents future circular dependencies, cleaner separation **Problem**: ``` yaze_core_lib currently contains: ├─→ ROM management (rom.cc) ├─→ Window/input (window.cc) ├─→ Asar wrapper (asar_wrapper.cc) ├─→ Platform utilities (file_dialog, fonts) ├─→ Project management (project.cc) ├─→ Controller (controller.cc) └─→ gRPC services (test_harness, rom_service) All mixed together in one library If core_lib needs gfx internals → potential cycle ``` **Solution**: ``` yaze_core_foundation: ├─→ ROM management (rom.cc) ├─→ Window basics (window.cc) ├─→ Asar wrapper (asar_wrapper.cc) ├─→ Platform utilities (file_dialog, fonts) └─→ Dependencies: yaze_util, yaze_common, asar, SDL2 (NO yaze_gfx, NO yaze_zelda3) yaze_core_services: ├─→ Project management (project.cc) - needs zelda3 for labels ├─→ Controller (controller.cc) - coordinates editors ├─→ gRPC services (test_harness, rom_service) └─→ Dependencies: yaze_core_foundation, yaze_gfx, yaze_zelda3 yaze_core_lib (INTERFACE): └─→ Aggregates: yaze_core_foundation + yaze_core_services ``` **Benefits**: - Clear separation: foundation vs services - Prevents cycles: gfx → core_foundation → gfx ❌ (no longer possible) - Selective linking: CLI can use foundation only - Better testability **Migration**: ```cmake # src/app/core/core_library.cmake set(CORE_FOUNDATION_SRC core/asar_wrapper.cc app/core/window.cc app/rom.cc app/platform/font_loader.cc app/platform/asset_loader.cc app/platform/file_dialog_nfd.cc # or .mm for macOS ) add_library(yaze_core_foundation STATIC ${CORE_FOUNDATION_SRC}) target_link_libraries(yaze_core_foundation PUBLIC yaze_util yaze_common asar-static SDL2 ) set(CORE_SERVICES_SRC app/core/project.cc app/core/controller.cc # gRPC services if enabled ) add_library(yaze_core_services STATIC ${CORE_SERVICES_SRC}) target_link_libraries(yaze_core_services PUBLIC yaze_core_foundation yaze_gfx yaze_zelda3 ImGui ) # Aggregate add_library(yaze_core_lib INTERFACE) target_link_libraries(yaze_core_lib INTERFACE yaze_core_foundation yaze_core_services ) ``` #### E. Split yaze_agent for Minimal CLI **Status**: Proposed (New) **Priority**: MEDIUM-LOW **Effort**: Medium (3-4 days) **Impact**: 50% smaller z3ed builds, faster CLI development **Problem**: ``` yaze_agent currently links to EVERYTHING: ├─→ yaze_gfx (all 7 libs) ├─→ yaze_gui (all 5 libs) ├─→ yaze_core_lib ├─→ yaze_zelda3 ├─→ yaze_emulator └─→ Result: 80+ MB z3ed binary, slow rebuilds ``` **Solution**: ``` yaze_agent_core (minimal): ├─→ Command registry & dispatcher ├─→ TUI system (FTXUI) ├─→ Argument parsing (from C4 refactoring) ├─→ Output formatting (from C4 refactoring) ├─→ Command context (from C4 refactoring) ├─→ Dependencies: yaze_util, yaze_common, ftxui, yaml-cpp └─→ Size: ~15 MB binary yaze_agent_services (full stack): ├─→ yaze_agent_core ├─→ AI services (Ollama, Gemini) ├─→ GUI automation client ├─→ Emulator commands ├─→ Proposal system ├─→ Dependencies: ALL yaze libraries └─→ Size: +65 MB (total 80+ MB) z3ed executable: └─→ Links: yaze_agent_core (default) └─→ Optional: yaze_agent_services (with --enable-full-features) ``` **Benefits**: - 80% smaller CLI binary for basic commands - Faster CLI development (no GUI rebuilds) - Server deployments can use minimal agent - Clear separation: core vs services **Implementation**: ```cmake # src/cli/agent.cmake set(AGENT_CORE_SRC cli/flags.cc cli/handlers/command_handlers.cc cli/service/command_registry.cc cli/service/agent/tool_dispatcher.cc cli/service/agent/enhanced_tui.cc cli/service/resources/command_context.cc cli/service/resources/command_handler.cc cli/service/resources/resource_catalog.cc # Minimal command handlers (resource queries, basic ROM ops) ) add_library(yaze_agent_core STATIC ${AGENT_CORE_SRC}) target_link_libraries(yaze_agent_core PUBLIC yaze_common yaze_util ftxui::component yaml-cpp ) set(AGENT_SERVICES_SRC # All AI, GUI automation, emulator integration cli/service/ai/ai_service.cc cli/service/ai/ollama_ai_service.cc cli/service/ai/gemini_ai_service.cc cli/service/gui/gui_automation_client.cc cli/handlers/tools/emulator_commands.cc # ... all other advanced features ) add_library(yaze_agent_services STATIC ${AGENT_SERVICES_SRC}) target_link_libraries(yaze_agent_services PUBLIC yaze_agent_core yaze_gfx yaze_gui yaze_core_lib yaze_zelda3 yaze_emulator # ... all dependencies ) # z3ed can choose which to link ``` ### 4.3 Priority 3: Future Optimizations #### F. Editor Modularization **Status**: Future **Priority**: LOW **Effort**: Large (1-2 weeks) **Impact**: Parallel development, isolated testing **Concept**: ``` yaze_editor_dungeon: └─→ Only dungeon editor code yaze_editor_overworld: └─→ Only overworld editor code yaze_editor_system: └─→ Settings, commands, workspace yaze_editor (INTERFACE): └─→ Aggregates all editor modules ``` **Benefits**: - Parallel development on different editors - Isolated testing per editor - Faster incremental builds **Defer**: After zelda3 refactoring, test separation complete #### G. Precompiled Headers Optimization **Status**: Future **Priority**: LOW **Effort**: Small (1 day) **Impact**: 10-20% faster full rebuilds **Current**: PCH in `src/yaze_pch.h` but not fully optimized **Improvements**: - Split into foundation PCH and app PCH - More aggressive PCH usage - Benchmark impact #### H. Unity Builds for Third-Party Code **Status**: Future **Priority**: LOW **Effort**: Small (1 day) **Impact**: Faster clean builds **Concept**: Combine multiple translation units for faster compilation --- ## 5. Conditional Compilation Matrix ### Build Configurations | Configuration | Purpose | Test Dashboard | Agent | gRPC | ROM Tests | |---------------|---------|----------------|-------|------|-----------| | **Debug** | Local development | ON | ON | ON | ❌ OFF | | **Debug-AI** | AI feature development | ON | ON | ON | ❌ OFF | | **Release** | Production | ❌ OFF | ❌ OFF | ❌ OFF | ❌ OFF | | **CI-Linux** | Ubuntu CI/CD | ❌ OFF | ON | ON | ❌ OFF | | **CI-Windows** | Windows CI/CD | ❌ OFF | ON | ON | ❌ OFF | | **CI-macOS** | macOS CI/CD | ❌ OFF | ON | ON | ❌ OFF | | **Dev-ROM** | ROM testing | ON | ON | ON | ON | ### Feature Flags | Flag | Default | Effect | |------|---------|--------| | `YAZE_BUILD_APP` | ON | Build main application | | `YAZE_BUILD_Z3ED` | ON | Build CLI tool | | `YAZE_BUILD_EMU` | OFF | Build standalone emulator | | `YAZE_BUILD_TESTS` | ON | Build test suites | | `YAZE_BUILD_LIB` | OFF | Build C API library | | `YAZE_WITH_GRPC` | ON | Enable gRPC (networking) | | `YAZE_WITH_JSON` | ON | Enable JSON (AI services) | | `YAZE_WITH_TEST_DASHBOARD` | ON | Include test dashboard in app | | `YAZE_ENABLE_ROM_TESTS` | OFF | Enable ROM-dependent tests | | `YAZE_MINIMAL_BUILD` | OFF | Minimal build (no agent/tests) | ### Library Availability Matrix | Library | Always Built | Conditional | Notes | |---------|--------------|-------------|-------| | yaze_util | | - | Foundation | | yaze_common | | - | Foundation | | yaze_gfx | | - | Core graphics | | yaze_gui | | - | Core GUI | | yaze_zelda3 | | - | Game logic | | yaze_core_lib | | - | ROM management | | yaze_emulator | | - | SNES emulation | | yaze_net | | JSON/gRPC | Networking | | yaze_editor | | APP | Main editor | | yaze_agent | | Z3ED | CLI features | | yaze_test_support | ❌ | TESTS | Test infrastructure | | yaze_test_dashboard | ❌ | TEST_DASHBOARD | GUI test dashboard | ### Executable Build Matrix | Executable | Build Condition | Dependencies | |------------|-----------------|--------------| | yaze | `YAZE_BUILD_APP=ON` | editor, emulator, core_lib, [agent], [test_dashboard] | | z3ed | `YAZE_BUILD_Z3ED=ON` | agent, core_lib, zelda3 | | yaze_emu | `YAZE_BUILD_EMU=ON` | emulator, core_lib | | yaze_test_stable | `YAZE_BUILD_TESTS=ON` | test_support, all libs | | yaze_test_gui | `YAZE_BUILD_TESTS=ON` | test_support, ImGuiTestEngine | | yaze_test_rom_dependent | `YAZE_ENABLE_ROM_TESTS=ON` | test_support + ROM | --- ## 6. Migration Roadmap ### Phase 1: Foundation Fixes ( This PR) **Timeline**: Immediate **Status**: In Progress **Tasks**: 1. Fix `BackgroundBuffer` constructor in `Arena::Arena()` 2. Add `yaze_core_lib` dependency to `yaze_emulator` 3. Document current architecture in this file **Expected Outcome**: - Ubuntu CI passes - No build regressions - Complete architectural documentation ### Phase 2: Test Separation (Next Sprint) **Timeline**: 1 week **Status**: Proposed **Reference**: A2-test-dashboard-refactoring.md **Tasks**: 1. Create `src/test/framework/` directory structure 2. Split `TestManager` into core + dashboard 3. Move test suites to `src/test/suites/` 4. Create `test_dashboard` conditional library 5. Update CMake build system 6. Update all test executables 7. Verify clean release builds **Expected Outcome**: - No circular dependencies - 60% faster test builds - Cleaner release binaries - Isolated test framework ### Phase 3: Zelda3 Refactoring (Week 2-3) **Timeline**: 1.5-2 weeks **Status**: Proposed **Reference**: B6-zelda3-library-refactoring.md **Tasks**: 1. **Week 1**: Physical move - Move `src/app/zelda3/` → `src/zelda3/` - Update all `#include` directives (300+ files) - Update CMake paths - Verify builds 2. **Week 2**: Decomposition - Create 6 sub-libraries (core, sprite, dungeon, overworld, screen, music) - Establish dependency graph - Update consumers - Verify incremental builds 3. **Week 3**: Testing & Documentation - Update test suite organization - Benchmark build times - Update documentation - Migration guide **Expected Outcome**: - Proper top-level shared library - 70% faster zelda3 incremental builds - Clear domain boundaries - Legacy code isolated ### Phase 4: Core Library Split (Week 4) **Timeline**: 1 week **Status**: Proposed **Reference**: Section 4.2.D (this document) **Tasks**: 1. Create `yaze_core_foundation` library - Move ROM, window, asar, platform utilities - Dependencies: util, common, SDL2, asar 2. Create `yaze_core_services` library - Move project, controller, gRPC services - Dependencies: core_foundation, gfx, zelda3 3. Update `yaze_core_lib` INTERFACE - Aggregate foundation + services 4. Update all consumers - Verify dependency chains - No circular dependencies **Expected Outcome**: - Prevents future circular dependencies - Cleaner separation of concerns - Minimal CLI can use foundation only ### Phase 5: Agent Split (Week 5) **Timeline**: 1 week **Status**: Proposed **Reference**: Section 4.2.E (this document) **Tasks**: 1. Create `yaze_agent_core` library - Command registry, TUI, parsers - Dependencies: util, common, ftxui 2. Create `yaze_agent_services` library - AI services, GUI automation, emulator integration - Dependencies: agent_core, all yaze libs 3. Update `z3ed` executable - Link minimal agent_core by default - Optional full services **Expected Outcome**: - 80% smaller CLI binary - 50% faster CLI development - Server-friendly minimal agent ### Phase 6: Benchmarking & Optimization (Week 6) **Timeline**: 3-4 days **Status**: Future **Tasks**: 1. Benchmark build times - Before vs after comparisons - Common development scenarios - CI/CD pipeline times 2. Profile bottlenecks - Identify remaining slow builds - Measure header include costs - Analyze link times 3. Optimize as needed - PCH improvements - Unity builds for third-party - Parallel build tuning **Expected Outcome**: - Data-driven optimization - Documented build time improvements - Tuned build system ### Phase 7: Documentation & Polish (Week 7) **Timeline**: 2-3 days **Status**: Future **Tasks**: 1. Update all documentation - Architecture diagrams - Build guides - Migration guides 2. Create developer onboarding - Quick start guide - Common workflows - Troubleshooting 3. CI/CD optimization - Parallel build strategies - Caching improvements - Test parallelization **Expected Outcome**: - Complete documentation - Smooth onboarding - Optimized CI/CD --- ## 7. Expected Build Time Improvements ### Baseline Measurements (Current) Measured on Apple M1 Max, 32 GB RAM, macOS 14.0 | Scenario | Current Time | Notes | |----------|--------------|-------| | Clean build (all features) | 8-10 min | Debug, gRPC, JSON, Tests | | Clean build (minimal) | 5-6 min | No tests, no agent | | Incremental (gfx change) | 2-3 min | Rebuilds 20+ libs | | Incremental (zelda3 change) | 1-2 min | Rebuilds 8+ libs | | Incremental (test change) | 45-60 sec | Circular rebuild | | Incremental (editor change) | 1-2 min | Many dependents | ### Projected Improvements (After All Refactoring) | Scenario | Projected Time | Savings | Notes | |----------|----------------|---------|-------| | Clean build (all features) | 7-8 min | 15-20% | Better parallelization | | Clean build (minimal) | 3-4 min | 35-40% | Fewer conditional libs | | Incremental (gfx change) | 30-45 sec | **75-80%** | Isolated gfx changes | | Incremental (zelda3 change) | 20-30 sec | **70-75%** | Sub-library isolation | | Incremental (test change) | 15-20 sec | **65-70%** | No circular rebuild | | Incremental (editor change) | 30-45 sec | **60-65%** | Modular editors | ### CI/CD Improvements | Pipeline | Current | Projected | Savings | |----------|---------|-----------|---------| | Ubuntu stable tests | 12-15 min | 8-10 min | **30-35%** | | macOS stable tests | 15-18 min | 10-12 min | **30-35%** | | Windows stable tests | 18-22 min | 12-15 min | **30-35%** | | Full matrix (3 platforms) | 45-55 min | 30-37 min | **30-35%** | ### Developer Experience Improvements | Workflow | Current | Projected | Impact | |----------|---------|-----------|--------| | Fix gfx bug → test | 3-4 min | 45-60 sec | **Much faster iteration** | | Add zelda3 feature → test | 2-3 min | 30-45 sec | **Rapid prototyping** | | Modify test → verify | 60-90 sec | 20-30 sec | **Tight feedback loop** | | CLI-only development | Rebuilds GUI! | No GUI rebuild | **Isolated development** | --- ## 8. Detailed Library Specifications ### 8.1 Foundation Libraries #### yaze_common **Purpose**: Platform definitions, common macros **Location**: `src/common/` **Source Files**: (header-only) **Dependencies**: None **Dependents**: All libraries (foundation) **Build Impact**: Header-only, minimal **Priority**: N/A (stable) #### yaze_util **Purpose**: Logging, file I/O, SDL utilities **Location**: `src/util/` **Source Files**: 8-10 .cc files **Dependencies**: yaze_common, absl, SDL2 **Dependents**: All libraries **Build Impact**: Changes trigger rebuild of EVERYTHING **Priority**: N/A (stable, rarely changes) ### 8.2 Graphics Libraries #### yaze_gfx_types **Purpose**: SNES color/palette/tile data structures **Location**: `src/app/gfx/types/` **Source Files**: 3 .cc files **Dependencies**: None (foundation) **Dependents**: gfx_core, gfx_util **Build Impact**: Medium (4-6 libs) **Priority**: DONE (refactored) #### yaze_gfx_backend **Purpose**: SDL2 renderer abstraction **Location**: `src/app/gfx/backend/` **Source Files**: 1 .cc file **Dependencies**: SDL2 **Dependents**: gfx_resource, gfx_render **Build Impact**: Low (2-3 libs) **Priority**: DONE (refactored) #### yaze_gfx_resource **Purpose**: Memory management (Arena) **Location**: `src/app/gfx/resource/` **Source Files**: 2 .cc files **Dependencies**: gfx_backend, gfx_render (BackgroundBuffer) **Dependents**: gfx_core **Build Impact**: Medium (3-4 libs) **Priority**: DONE (refactored) **Note**: Fixed BackgroundBuffer constructor issue in this PR #### yaze_gfx_core **Purpose**: Bitmap class **Location**: `src/app/gfx/core/` **Source Files**: 1 .cc file **Dependencies**: gfx_types, gfx_resource **Dependents**: gfx_util, gfx_render, gui_canvas **Build Impact**: High (8+ libs) **Priority**: DONE (refactored) #### yaze_gfx_render **Purpose**: Advanced rendering (Atlas, BackgroundBuffer) **Location**: `src/app/gfx/render/` **Source Files**: 4 .cc files **Dependencies**: gfx_core, gfx_backend **Dependents**: gfx_debug, zelda3 **Build Impact**: Medium (5-7 libs) **Priority**: DONE (refactored) #### yaze_gfx_util **Purpose**: Compression, format conversion **Location**: `src/app/gfx/util/` **Source Files**: 4 .cc files **Dependencies**: gfx_core **Dependents**: gfx_debug, editor **Build Impact**: Medium (4-6 libs) **Priority**: DONE (refactored) #### yaze_gfx_debug **Purpose**: Performance profiling, optimization **Location**: `src/app/gfx/debug/` **Source Files**: 3 .cc files **Dependencies**: gfx_util, gfx_render **Dependents**: editor (optional) **Build Impact**: Low (1-2 libs) **Priority**: DONE (refactored) ### 8.3 GUI Libraries #### yaze_gui_core **Purpose**: Theme, input, style management **Location**: `src/app/gui/core/` **Source Files**: 7 .cc files **Dependencies**: yaze_util, ImGui, nlohmann_json **Dependents**: All other GUI libs **Build Impact**: High (8+ libs) **Priority**: DONE (refactored) #### yaze_gui_canvas **Purpose**: Drawable canvas with pan/zoom **Location**: `src/app/gui/canvas/` **Source Files**: 9 .cc files **Dependencies**: gui_core, yaze_gfx **Dependents**: editor (all editors use Canvas) **Build Impact**: Very High (10+ libs) **Priority**: DONE (refactored) #### yaze_gui_widgets **Purpose**: Reusable UI widgets **Location**: `src/app/gui/widgets/` **Source Files**: 6 .cc files **Dependencies**: gui_core, yaze_gfx **Dependents**: editor **Build Impact**: Medium (5-7 libs) **Priority**: DONE (refactored) #### yaze_gui_automation **Purpose**: Widget discovery, state capture, testing **Location**: `src/app/gui/automation/` **Source Files**: 4 .cc files **Dependencies**: gui_core **Dependents**: gui_app, agent (GUI automation) **Build Impact**: Low (2-3 libs) **Priority**: DONE (refactored) #### yaze_gui_app **Purpose**: High-level app components (chat, collaboration) **Location**: `src/app/gui/app/` **Source Files**: 4 .cc files **Dependencies**: gui_core, gui_widgets, gui_automation **Dependents**: editor **Build Impact**: Low (1-2 libs) **Priority**: DONE (refactored) ### 8.4 Game Logic Libraries #### yaze_zelda3 (Current) **Purpose**: All Zelda3 game logic **Location**: `src/app/zelda3/` Warning: (wrong location) **Source Files**: 21 .cc files (monolithic) **Dependencies**: yaze_gfx, yaze_util **Dependents**: core_lib, editor, agent **Build Impact**: Very High (any change rebuilds 8+ libs) **Priority**: HIGH (refactor per B6) 🔴 **Issues**: - Wrong location (should be `src/zelda3/`) - Monolithic (should be 6 sub-libraries) #### yaze_zelda3_core (Proposed) **Purpose**: Labels, constants, common data **Location**: `src/zelda3/` (after move) **Source Files**: 3-4 .cc files **Dependencies**: yaze_util **Dependents**: All other zelda3 libs **Build Impact**: High (if changed, rebuilds all zelda3) **Priority**: HIGH (implement B6) 🔴 #### yaze_zelda3_sprite (Proposed) **Purpose**: Sprite management **Location**: `src/zelda3/sprite/` **Source Files**: 3 .cc files **Dependencies**: zelda3_core **Dependents**: zelda3_dungeon, zelda3_overworld **Build Impact**: Medium (2-3 libs) **Priority**: HIGH (implement B6) 🔴 #### yaze_zelda3_dungeon (Proposed) **Purpose**: Dungeon system **Location**: `src/zelda3/dungeon/` **Source Files**: 7 .cc files **Dependencies**: zelda3_core, zelda3_sprite **Dependents**: zelda3_screen, editor_dungeon **Build Impact**: Low (1-2 libs) **Priority**: HIGH (implement B6) 🔴 #### yaze_zelda3_overworld (Proposed) **Purpose**: Overworld system **Location**: `src/zelda3/overworld/` **Source Files**: 2 .cc files **Dependencies**: zelda3_core, zelda3_sprite **Dependents**: zelda3_screen, editor_overworld **Build Impact**: Low (1-2 libs) **Priority**: HIGH (implement B6) 🔴 #### yaze_zelda3_screen (Proposed) **Purpose**: Game screens (title, inventory, map) **Location**: `src/zelda3/screen/` **Source Files**: 4 .cc files **Dependencies**: zelda3_dungeon, zelda3_overworld **Dependents**: editor_screen **Build Impact**: Very Low (1 lib) **Priority**: HIGH (implement B6) 🔴 #### yaze_zelda3_music (Proposed) **Purpose**: Legacy music tracker **Location**: `src/zelda3/music/` **Source Files**: 1 .cc file (legacy C code) **Dependencies**: zelda3_core **Dependents**: editor_music **Build Impact**: Very Low (1 lib) **Priority**: HIGH (implement B6) 🔴 ### 8.5 Core System Libraries #### yaze_core_lib (Current) **Purpose**: ROM, window, asar, project, services **Location**: `src/app/core/` **Source Files**: 10+ .cc files (mixed concerns) Warning: **Dependencies**: yaze_util, yaze_gfx, yaze_zelda3, ImGui, asar, SDL2, [gRPC] **Dependents**: editor, agent, emulator, net **Build Impact**: Very High (10+ libs) **Priority**: MEDIUM (split into foundation + services) 🟡 **Issues**: - Mixed concerns (foundation vs services) - Potential circular dependency with gfx #### yaze_core_foundation (Proposed) **Purpose**: ROM, window, asar, platform utilities **Location**: `src/app/core/` **Source Files**: 6-7 .cc files **Dependencies**: yaze_util, yaze_common, asar, SDL2 **Dependents**: core_services, emulator, agent_core **Build Impact**: Medium (5-7 libs) **Priority**: MEDIUM (implement section 4.2.D) 🟡 #### yaze_core_services (Proposed) **Purpose**: Project, controller, gRPC services **Location**: `src/app/core/` **Source Files**: 4-5 .cc files **Dependencies**: core_foundation, yaze_gfx, yaze_zelda3, ImGui, [gRPC] **Dependents**: editor, agent_services **Build Impact**: Medium (4-6 libs) **Priority**: MEDIUM (implement section 4.2.D) 🟡 #### yaze_emulator **Purpose**: SNES emulation (CPU, PPU, APU) **Location**: `src/app/emu/` **Source Files**: 30+ .cc files **Dependencies**: yaze_util, yaze_common, yaze_core_lib, absl, SDL2 **Dependents**: editor, agent (emulator commands) **Build Impact**: Medium (3-5 libs) **Priority**: LOW (stable) **Note**: Fixed missing core_lib dependency in this PR #### yaze_net **Purpose**: Networking, collaboration **Location**: `src/app/net/` **Source Files**: 3 .cc files **Dependencies**: yaze_util, yaze_common, absl, [OpenSSL], [gRPC] **Dependents**: gui (collaboration panel) **Build Impact**: Low (1-2 libs) **Priority**: LOW (stable) ### 8.6 Application Layer Libraries #### yaze_editor **Purpose**: All editor functionality **Location**: `src/app/editor/` **Source Files**: 45+ .cc files (large, complex) **Dependencies**: core_lib, gfx, gui, zelda3, emulator, util, common, ImGui, [agent], [test_support] **Dependents**: test_support, yaze app **Build Impact**: Very High (ANY change affects main app + tests) **Priority**: LOW-FUTURE (modularize per section 4.3.F) 🔵 **Issues**: - Too many dependencies (8+ major libs) - Circular dependency with test_support #### yaze_agent (Current) **Purpose**: CLI functionality, AI services **Location**: `src/cli/` **Source Files**: 60+ .cc files (massive) Warning: **Dependencies**: common, util, gfx, gui, core_lib, zelda3, emulator, absl, yaml, ftxui, [gRPC], [JSON], [OpenSSL] **Dependents**: editor (agent integration), z3ed **Build Impact**: Very High (15+ libs) **Priority**: MEDIUM (split into core + services) 🟡 **Issues**: - Links to entire application stack - CLI tool rebuilds on GUI changes #### yaze_agent_core (Proposed) **Purpose**: Minimal CLI (commands, TUI, parsing) **Location**: `src/cli/` **Source Files**: 20-25 .cc files **Dependencies**: common, util, ftxui, yaml **Dependents**: agent_services, z3ed **Build Impact**: Low (2-3 libs) **Priority**: MEDIUM (implement section 4.2.E) 🟡 #### yaze_agent_services (Proposed) **Purpose**: Full CLI features (AI, GUI automation, emulator) **Location**: `src/cli/` **Source Files**: 35-40 .cc files **Dependencies**: agent_core, gfx, gui, core_lib, zelda3, emulator, [gRPC], [JSON], [OpenSSL] **Dependents**: editor (agent integration), z3ed (optional) **Build Impact**: High (10+ libs) **Priority**: MEDIUM (implement section 4.2.E) 🟡 #### yaze_test_support (Current) **Purpose**: Test manager + test suites **Location**: `src/app/test/` **Source Files**: 2 .cc files (mixed concerns) Warning: **Dependencies**: editor, core_lib, gui, zelda3, gfx, util, common, agent **Dependents**: editor (CIRCULAR Warning:), all test executables **Build Impact**: Very High (10+ libs) **Priority**: HIGH (separate per A2) 🔴 **Issues**: - Circular dependency with editor - Cannot exclude from release builds - Mixes core logic with GUI #### yaze_test_framework (Proposed) **Purpose**: Core test infrastructure (no GUI) **Location**: `src/test/framework/` **Source Files**: 1 .cc file **Dependencies**: yaze_util, absl **Dependents**: test_suites, test_dashboard **Build Impact**: Low (2-3 libs) **Priority**: HIGH (implement A2) 🔴 #### yaze_test_suites (Proposed) **Purpose**: Actual test implementations **Location**: `src/test/suites/` **Source Files**: 1 .cc file **Dependencies**: test_framework, specific yaze libs (what's being tested) **Dependents**: test executables **Build Impact**: Low (1-2 libs per suite) **Priority**: HIGH (implement A2) 🔴 #### yaze_test_dashboard (Proposed) **Purpose**: In-app test GUI (optional) **Location**: `src/app/gui/testing/` **Source Files**: 1-2 .cc files **Dependencies**: test_framework, yaze_gui **Dependents**: yaze app (conditionally) **Build Impact**: Low (1 lib) **Priority**: HIGH (implement A2) 🔴 **Conditional**: `YAZE_WITH_TEST_DASHBOARD=ON` --- ## 9. References & Related Documents ### Primary Documents - **C4-z3ed-refactoring.md**: CLI command abstraction (COMPLETED ) - **B6-zelda3-library-refactoring.md**: Zelda3 move & decomposition (PROPOSED 🔴) - **A2-test-dashboard-refactoring.md**: Test infrastructure separation (PROPOSED 🔴) - **This Document (A1)**: Comprehensive dependency analysis (NEW 📄) ### Related Refactoring Documents - **docs/gfx-refactor.md**: Graphics tier decomposition (COMPLETED ) - **docs/gui-refactor.md**: GUI tier decomposition (COMPLETED ) - **docs/G3-renderer-migration-complete.md**: Renderer abstraction (COMPLETED ) ### Build System Documentation - **Root CMakeLists.txt**: Main build configuration - **src/CMakeLists.txt**: Library orchestration - **test/CMakeLists.txt**: Test suite configuration - **scripts/build_cleaner.py**: Automated source list maintenance ### Architecture Documentation - **docs/CLAUDE.md**: Project overview and guidelines - **docs/B2-platform-compatibility.md**: Platform notes, Windows Clang workarounds, and CI/CD guidance - **docs/B4-git-workflow.md**: Git workflow and branching ### External Resources - [CMake Documentation](https://cmake.org/documentation/) - [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) - [Abseil C++ Libraries](https://abseil.io/) - [SDL2 Documentation](https://wiki.libsdl.org/) - [ImGui Documentation](https://github.com/ocornut/imgui) --- ## 10. Conclusion This document provides a comprehensive analysis of YAZE's dependency architecture and proposes a clear roadmap for optimization. The key takeaways are: 1. **Current State**: Complex interdependencies causing slow builds 2. **Root Causes**: Circular dependencies, over-linking, misplaced components 3. **Solution**: Execute existing proposals (A2, B6) + new splits (core_lib, agent) 4. **Expected Impact**: 40-60% faster incremental builds, cleaner architecture 5. **Timeline**: 6-7 weeks for complete refactoring By following this roadmap, YAZE will achieve: - Faster development iteration - Cleaner architecture - Better testability - Easier maintenance - Improved CI/CD performance The proposed changes are backwards-compatible and can be implemented incrementally without disrupting ongoing development. --- **Document Version**: 1.0 **Last Updated**: 2025-10-13 **Maintainer**: YAZE Development Team **Status**: Living Document (update as architecture evolves)