# dmitrybozhko/cpu-design-and-simulation-project architecture

> Architecture diagram of the GitHub repository dmitrybozhko/cpu-design-and-simulation-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmitrybozhko/cpu-design-and-simulation-project
- Repository: https://github.com/dmitrybozhko/cpu-design-and-simulation-project

## Overview

##### Project type and purpose
- This is a Python-based toolset consisting of two command-line binaries:
- A **Numeric tool** (`numeric_main`) for low-level numeric routines
- A **CPU simulator** (`cpu_main`) that models a simple CPU (register file, ALU, memory, instruction runner)
- It’s an open-source library + CLI utilities for experimenting with numeric algorithms and RISC-style CPU behavior.

##### File structure
- Top level
- `.gitignore`, `README.md`, `AI_USAGE.md`, `ai_report.json` (project metadata)
- `demo/` – example scripts demonstrating library usage
- `count_ai_lines.py` – analysis script
- `src/` – main Python packages
- `tests/` + `test_*.py` – unit & integration tests
- `src/cli/` – CLI entry-points (wrappers that parse arguments and invoke core API)
- `src/numeric_core/` – pure arithmetic and bit-level operations (adders, shifters, float32, conversions, public_api.py)
- `src/cpu/` – CPU simulator modules (register_file, memory, ALU, interpreter, runner, state)
- tests are split into numeric unit tests, CPU unit tests, and CPU integration tests.

##### README insights
- Confirms two binaries invoked via `python -m src.cli.numeric_main` or `python -m src.cli.cpu_main`.

a. Main components
- **CLI Layer**: `src.cli.numeric_main`, `src.cli.cpu_main`
- **Numeric Core Library**: everything under `src.numeric_core` (bit_utils, adders, ALU, float32, etc.)
- **CPU Simulator Library**: modules under `src.cpu` (register_file, memory, alu, interpreter, runner, state)
- **Demo & Tests**: user examples (`demo/bit_utils_demo.py`) and test harness (`tests/`)
- **Python Runtime**: the interpreter hosting all of the above
b. Relationships & interactions
- CLI Layer → invokes Numeric Core API (for numeric tool) or CPU Simulator API
- CPU Simulator ALU component uses Numeric Core routines for arithmetic/bit ops
- Interpreter/Runner orchestrates fetch-decode-execute, using register_file & memory modules
- Demo scripts import public_api from numeric_core and runner from cpu
- Tests import and validate each module in isolation (unit) and in combination (integration)
c. Architectural patterns/design principles
- **Layered Modular Design**: clear separation between CLI, simulator core, numeric algorithms
- **Public API Facade**: `numeric_core/public_api.py` hides internal details
- **Single Responsibility**: each module (e.g., register_file, memory, alu) does one thing
- **Test-Driven Structure**: correspondence between implementation and test files
d. Key technologies/frameworks
- Python 3.x modules & `__main__` entry points
- Standard library only (no external dependencies)
- pytest (inferred from `tests/` naming and `conftest.py`)

– “CLI Layer” (show two entry points: numeric_main, cpu_main)
– “Demo & Tests” (pointing back to core for validation)
– CLI → Numeric Core
– CLI → CPU Simulator
– CPU Simulator → Numeric Core
– Runner → Interpreter → ALU/Memory/Register
– CLI (blue), Numeric Core (green), CPU Simulator (orange), Demo/Tests (gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Runtime"
        subgraph "CLI Layer"
            NUM["numeric_main"]:::cli
            CPUCLI["cpu_main"]:::cli
        end

        subgraph "Core Libraries"
            subgraph "Numeric Core"
                PUB["public_api.py"]:::core
                ADD["adders.py"]:::core
                NALU["alu.py"]:::core
                BIT["bit_utils.py"]:::core
                CMP["comparators.py"]:::core
                CONV["conversions.py"]:::core
                F32["float32.py"]:::core
                MDU["mdu.py"]:::core
                SHIF["shifter.py"]:::core
                SHIFS["shifters.py"]:::core
                SMALL["small_ops.py"]:::core
                TWOS["twos_complement.py"]:::core
            end

            subgraph "CPU Simulator"
                CU_REG["register_file.py"]:::cpu
                CU_ALU["alu.py"]:::cpu
                CU_MEM["memory.py"]:::cpu
                INTP["interpreter.py"]:::cpu
                RUN["runner.py"]:::cpu
                ST["state.py"]:::cpu
            end
        end

        subgraph "Demo & Tests"
            DEMO["bit_utils_demo.py"]:::demo
            TNUM["Numeric Tests"]:::demo
            TCPUU["CPU Unit Tests"]:::demo
            TCUPI["CPU Integration Tests"]:::demo
        end
    end

    %% Relationships
    NUM -->|"invokes"| PUB
    CPUCLI -->|"invokes"| RUN
    RUN -->|"runs"| INTP
    INTP -->|"decode/execute"| CU_REG
    INTP -->|"decode/execute"| CU_MEM
    INTP -->|"decode/execute"| CU_ALU
    CU_ALU -->|"uses numeric ops"| NALU
    DEMO -->|"imports"| PUB
    DEMO -->|"imports"| RUN
    TNUM -->|"tests core"| ADD
    TCPUU -->|"tests cpu alu"| CU_ALU
    TCPUU -->|"tests cpu regs"| CU_REG
    TCUPI -->|"integration tests"| RUN

    %% Click Events
    click NUM "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cli/numeric_main.py"
    click CPUCLI "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cli/cpu_main.py"
    click PUB "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/public_api.py"
    click ADD "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/adders.py"
    click NALU "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/alu.py"
    click BIT "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/bit_utils.py"
    click CMP "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/comparators.py"
    click CONV "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/conversions.py"
    click F32 "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/float32.py"
    click MDU "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/mdu.py"
    click SHIF "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/shifter.py"
    click SHIFS "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/shifters.py"
    click SMALL "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/small_ops.py"
    click TWOS "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/numeric_core/twos_complement.py"
    click CU_REG "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/register_file.py"
    click CU_ALU "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/alu.py"
    click CU_MEM "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/memory.py"
    click INTP "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/interpreter.py"
    click RUN "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/runner.py"
    click ST "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/src/cpu/state.py"
    click DEMO "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/blob/main/demo/bit_utils_demo.py"
    click TNUM "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/tree/main/tests/numeric/"
    click TCPUU "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/tree/main/tests/cpu_unit/"
    click TCUPI "https://github.com/dmitrybozhko/cpu-design-and-simulation-project/tree/main/tests/cpu_integration/"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#000;
    classDef core fill:#A9DFBF,stroke:#000;
    classDef cpu fill:#F5B041,stroke:#000;
    classDef demo fill:#D7DBDD,stroke:#000;
```
