# asi-uniovi/simct architecture

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

- Interactive diagram: https://gitdiagram.com/asi-uniovi/simct
- Repository: https://github.com/asi-uniovi/simct

## Overview

##### Project Type and Purpose
- The README emphasizes user interaction with memory configuration, peripheral devices, and the visual display of the computer’s internal operations. This makes it a specialized full-stack (client-only) application with strong visualization and simulation components.

##### File Structure
- The top-level directories indicate a modular separation of concerns:
- The “app” folder is the core codebase divided into:
▪ config: Contains configuration and language files (control.js, instructions.js, language-specific literals) that likely set up the simulation parameters.
▪ control: Implements the logical behavior of the simulator (e.g., cpu.js, alu.js, bus.js, registers, memory, and support for devices). This is where the simulation core runs, managing instruction execution, clock cycles, etc.
▪ lib: Contains utility modules such as base conversion, bits manipulation, observers, queues, logging, etc. These provide auxiliary functions that support both the control and view layers.
▪ view: Manages the frontend visualization of the simulator with extensive subdirectories:
- CSS: Styling for the different components (keyboard, lights, memory editor, windows, etc.).
- ctelements and ctperipherals: JavaScript modules that build and manage the visual representation of internal components (ALU, bus elements, registers, etc.) and peripheral device forms.
- “dist”: Contains the built/compiled output for production use (e.g., index.html, built view assets).
- “tests”: Provides unit tests using Jest for validating functionality across modules (cpu, instructions, devices, memory, registers, etc.).
- Additionally, supporting files such as package.json, babel configuration, GitHub workflows, and IDE settings indicate a modern development ecosystem.

a. Main Components:
- Configuration Module (app/config): Handles simulation settings, control parameters, and language-specific configurations.
- Simulation Core / Control Module (app/control): Implements the internal functioning of the Computador Teórico – managing CPU operations, ALU, bus, registers, memory, and other internal signals. It also handles peripherals (keyboard, lights, screen).
- Utility Libraries (app/lib): Provides supporting functions such as bit manipulation, logging, observer pattern for state changes, and form handling.
- User Interface / View Module (app/view): Renders the simulation visually using HTML, CSS, and SVG – including interactive elements for controlling the simulation, configuring devices, and visualizing internal operations.
- Test Suite (tests): While not part of the runtime architecture, it validates system components and can be represented separately as ensuring quality control.

b. Relationships and Interactions:
- Data flows from the configuration module to the simulation core to set up initial parameters.
- The simulation core (control) drives both the backend simulation logic and shares status updates that the UI (view) listens to.
- Utility libraries underpin both the control logic and the UI with common functions.
- The view module makes extensive use of SVG elements and DOM components to render the simulator’s working state. User interactions (e.g., via device elements like the keyboard or lights) feed back into the control module, forming a loop of simulation control and visualization.
- Testing suites interact with each module individually (represented as separate components ensuring robustness).

c. Architectural Patterns/Design Principles:
- Separation of concerns: Clear division among configuration, business logic (control), utility libraries, and presentation (view) layers.
- Modular design: Each folder reflects a modular approach (e.g., devices, registers, SVG elements).
- Observer/Listener patterns: Given the presence of observer.js and event utilities, likely used to notify the view of changes in the simulation state.
- Client-side MVC-like (or MVVM) organization: The control manages state and operations, while the view reflects these changes in the UI.

d. Relevant Technologies & Frameworks:
- JavaScript: The core language used for simulation logic, UI, and utilities.
- Jest: For testing (exemplified in the tests/ directory).
- Babel: Indicating the code might be transpiled for broader browser support.
- CSS and SVG: For rendering and styling the simulator UI.
- Node.js & npm: For dependency management and running tests/development server instances.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraph for Configuration Module
    subgraph "Configuration Module"
        Config["Configuration Module"]:::config
    end

    %% Subgraph for Simulation Core / Control Module
    subgraph "Simulation Core"
        Control["Control Module"]:::simulation
        subgraph "Control Components"
            CPU["CPU"]:::simulation
            ALU["ALU (Arithmetic Logic)"]:::simulation
            Bus["Bus"]:::simulation
            Clock["Clock"]:::simulation
            Memory["Memory"]:::simulation
            Registers["Registers"]:::simulation
            Devices["Devices"]:::simulation
            Computer["Computer (Main)"]:::simulation
        end
    end

    %% Subgraph for Utility Libraries
    subgraph "Utility Libraries"
        Util["Utility Libraries"]:::util
    end

    %% Subgraph for User Interface / View Module
    subgraph "User Interface Module"
        UI["UI / View Module"]:::view
        subgraph "UI Components"
            SVG["SVG Rendering"]:::view
            Elements["CT Elements & Peripherals"]:::view
            Style["CSS & Navigation"]:::view
            SimEdit["Simulator & Memory Editor"]:::view
        end
    end

    %% Subgraph for Test Suite
    subgraph "Test Suite"
        Tests["Tests"]:::tests
    end

    %% Relationships
    Config -->|"initializes"| Control
    Control -->|"executes"| CPU
    Control -->|"executes"| ALU
    Control -->|"executes"| Bus
    Control -->|"executes"| Clock
    Control -->|"executes"| Memory
    Control -->|"executes"| Registers
    Control -->|"executes"| Devices
    Control -->|"drives"| Computer

    Util -->|"supports"| Control
    Util -->|"supports"| UI

    Control -->|"stateUpdates"| UI
    UI -->|"userInput"| Control

    Tests -->|"validates"| Config
    Tests -->|"validates"| Control
    Tests -->|"validates"| Util
    Tests -->|"validates"| UI

    %% Click Events
    click Config "https://github.com/asi-uniovi/simct/tree/main/app/config"
    click Control "https://github.com/asi-uniovi/simct/tree/main/app/control"
    click Util "https://github.com/asi-uniovi/simct/tree/main/app/lib"
    click UI "https://github.com/asi-uniovi/simct/tree/main/app/view"
    click Tests "https://github.com/asi-uniovi/simct/tree/main/tests"

    %% Styles
    classDef config fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef simulation fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef util fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef view fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef tests fill:#D7BDE2,stroke:#5D6D7E,stroke-width:2px;
```
