# scoldev/canes architecture

> Architecture diagram of the GitHub repository scoldev/canes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scoldev/canes
- Repository: https://github.com/scoldev/canes

## Overview

##### Main Components
- Emulator Core (nes/core)
- CPU: Located under src/nes/core/cpu, including constants (clock, flags, registers, state), the CPU implementation, and integration with instructions.
- ALU: Under src/nes/core/alu, handling arithmetic and logic operations.
- Memory: Under src/nes/core/memory, with related constants defining the memory map and mirrors.
- Addressing Modes: Found in nes/core/addressing-modes, which plays a key role in CPU instruction decoding.
- Instructions: The instructions implementation is separated further into a table of instructions (each instruction in its own file) and related error handling.

- Debugger and Disassembler
- Debugger: Both in the emulator’s core (src/nes/debugger) and on the UI side (src/ui/debugger) with context providers, hooks, and adapters. This indicates a separation of concerns between the debugging logic and its presentation.
- Disassembler: Implemented in both core (src/nes/disasm) and app-level folders (src/app/disasm), handling the parsing and conversion of binary opcodes into human-readable assembly code.

- UI Layer
- The interface is implemented using components (src/ui/debugger/components, src/ui/main.tsx, etc.). This layer includes debugger windows, layout components, and adapters (such as the ROM file loader).

- ROM and Services
- ROM Loader: Located in the nes/rom directory (and its constants, types, and service in nes/services).
- Services: nes-service and rom-service to serve as higher-level abstractions for interactions between ROM data and emulator state.

- Additional Supporting Components
- Benchmark: Contains specific scripts (in benchmark/) that test and measure instruction implementation performance.
- Testing: There is a comprehensive tests directory, including unit, integration, and UI tests that support TDD.
- Configuration/Build: Files such as package.json, tsconfig.json, vite.config.js, and linting/commit hooks are part of the project’s infrastructure.

##### Relationships and Interactions
- The Emulator Core interacts internally via data flow from:
- Memory ↔ CPU (ALU, addressing, and instructions).
- The CPU uses instructions, and these interact with the addressing modes and memory.

- The Debugger/Disassembler components sit on top of the Core:
- They request state and disassembled code from the emulator’s core.
- Errors generated by core components (like unknown instructions or missing ROM) are handled and surfaced.

- User Interface Components:
- The UI layer (written in React) communicates with the core debugger via hooks, adapters, and context providers, creating an interactive debugging experience.
- The UI sends commands (via defined debugger commands and state) back to the core to control emulation.

- ROM Loading and Service Modules:
- The ROM Service loads, validates, and prepares ROM files.
- This service interacts with the emulator core and also the debugger/adapters in the UI.

##### Architectural Patterns and Design Principles
- Layered Architecture – Separation among core emulation (business logic), debugging/disassembly (auxiliary services), and UI (presentation layer).
- Modularization – Each major function (CPU, ALU, memory, instructions, etc.) is broken into multiple files for maintainability.
- Use of TDD – As suggested by the extensive tests and integration directories, the system’s design has been influenced by TDD principles to reduce bugs.
- Dependency Direction – The core components (emulator, modules) should be independent, while UI and debugging modules act as layers that communicate with these core services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Emulator Core Subgraph
    subgraph "Emulator Core"
        CPU["CPU (src/nes/core/cpu)"]:::core
        ALU["ALU (src/nes/core/alu/alu.ts)"]:::core
        Memory["Memory (src/nes/core/memory)"]:::core
        AM["Addressing Modes (src/nes/core/addressing-modes)"]:::core
        Instr["Instructions (src/nes/core/instructions/instruction.ts)"]:::core
    end

    %% Relationships within Emulator Core
    CPU -->|"uses"| ALU
    CPU -->|"reads/writes"| Memory
    CPU -->|"decodesUsing"| AM
    CPU -->|"executes"| Instr

    %% Debugger & Disassembler Subgraph
    subgraph "Debugger & Disassembler"
        DebugCore["Debugger (Core) (src/nes/debugger)"]:::debug
        DisasmCore["Disassembler (Core) (src/nes/disasm)"]:::debug
        DebugUI["Debugger (UI) (src/ui/debugger)"]:::debug
        DisasmUI["Disassembler (UI) (src/app/disasm)"]:::debug
    end

    %% Connections between Emulator Core and Debug/Disasm
    CPU -->|"state"| DebugCore
    CPU -->|"opcode"| DisasmCore
    DebugCore -->|"provides"| DebugUI
    DisasmCore -->|"generates"| DisasmUI

    %% UI Layer Subgraph
    subgraph "UI Layer"
        UI["React UI (src/ui)"]:::ui
    end

    %% UI interactions with Debugger UI & Disassembler UI
    UI -->|"commands"| DebugUI
    UI -->|"commands"| DisasmUI

    %% ROM Management Subgraph
    subgraph "ROM Management"
        ROMLoader["ROM Loader (src/nes/rom)"]:::rom
        ROMService["ROM Service (src/nes/services/rom-service.ts)"]:::rom
    end

    %% ROM Feeding into the Emulator Core
    ROMLoader -->|"loads"| CPU
    ROMService -->|"feeds"| CPU

    %% Support Subgraph
    subgraph "Support"
        Benchmark["Benchmark (benchmark)"]:::support
        Testing["Testing Suites (tests)"]:::support
    end

    %% Testing validates multiple components (indicating TDD influence)
    Testing -->|"validates"| CPU
    Testing -->|"validates"| UI
    Testing -->|"validates"| ROMService

    %% Click Events
    click CPU "https://github.com/scoldev/canes/tree/master/src/nes/core/cpu"
    click ALU "https://github.com/scoldev/canes/blob/master/src/nes/core/alu/alu.ts"
    click Memory "https://github.com/scoldev/canes/tree/master/src/nes/core/memory"
    click AM "https://github.com/scoldev/canes/tree/master/src/nes/core/addressing-modes"
    click Instr "https://github.com/scoldev/canes/blob/master/src/nes/core/instructions/instruction.ts"
    click DebugCore "https://github.com/scoldev/canes/tree/master/src/nes/debugger"
    click DebugUI "https://github.com/scoldev/canes/tree/master/src/ui/debugger"
    click DisasmCore "https://github.com/scoldev/canes/tree/master/src/nes/disasm"
    click DisasmUI "https://github.com/scoldev/canes/tree/master/src/app/disasm"
    click UI "https://github.com/scoldev/canes/tree/master/src/ui"
    click ROMLoader "https://github.com/scoldev/canes/tree/master/src/nes/rom"
    click ROMService "https://github.com/scoldev/canes/blob/master/src/nes/services/rom-service.ts"
    click Benchmark "https://github.com/scoldev/canes/tree/master/benchmark"
    click Testing "https://github.com/scoldev/canes/tree/master/tests"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef debug fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ui fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef rom fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef support fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
