# arashsameni/manocomputer architecture

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

- Interactive diagram: https://gitdiagram.com/arashsameni/manocomputer
- Repository: https://github.com/arashsameni/manocomputer

## Overview

##### Project type and purpose
- This is a full-stack, cross-platform desktop application (Electron + React frontend, Flask backend) that implements an assembler and hardware simulator for Mano’s basic computer.
- The user types or loads `.asm` code in the UI, clicks “Assemble,” and the code is sent to the backend to be assembled into machine instructions and then simulated through a CPU/RAM model.

##### File structure
- Top level
- Example_Codes/ – sample `.asm` programs
- backend/ – Flask API + core simulation logic
- frontend/ – Electron wrapper around a React SPA
- backend modules
- api.py – HTTP endpoints (e.g., /assemble, /run)
- assembler.py – parses `.asm` into binary
- computer.py – drives fetch-decode-execute cycles
- ram.py, register.py, conditions.py – low-level simulation primitives
- frontend structure
- public/ – static HTML, preload scripts for Electron
- src/ – React entry (index.js), contexts (ComputerContext, ThemeContext), components (CodeEditor, FilesBar, StatusBar, Simulator), assets (syntax highlighter)
- package.json & .env – build and runtime configs for Electron and React

##### README
- Confirms tech stack: React + Electron, Flask backend.
- Usage section shows two separate processes: `flask run` + `npm run electron-dev`.

##### Main components and interactions
a. Frontend (Electron + React)
– Electron Main Process: launches browser window, loads React app
– React Renderer: UI components grouped under
- LeftSideBar (AboutUs, CodeEditor, FilesBar, StatusBar)
- Simulator pane (Ram view, Registers view)
– Contexts hold theme and simulator state
b. Backend (Flask)
– API Layer (api.py): receives HTTP POST with assembly source or run commands
– Assembler Layer (assembler.py): tokenizes, resolves symbols, produces machine code
– Simulation Layer (computer.py + ram.py + register.py + conditions.py): steps through instructions, updates PC, registers, RAM
c. Data flow
1. User edits or loads `.asm` in CodeEditor
2. On “Assemble,” React calls `POST http://localhost:5000/assemble`
3. Flask/api.py invokes assembler, returns object with machine words
4. React updates ComputerContext with new memory image
5. On “Run Step/Toggle,” React calls `/step` or uses client-side stepping (optional)
6. Simulation results (register values, memory snapshot) flow back to UI
d. External services & files
– Example_Codes folder for file loading in FilesBar
– Prism.js for syntax highlighting, Electron for desktop packaging

##### Architectural patterns & design principles
- Clear separation of concerns:
- Presentation (React/Electron)
- Application/API (Flask)
- Domain logic (Assembler + Simulator modules)
- Context API in React for global simulator state
- Modular simulation primitives (ram.py, register.py, conditions.py) to keep simulator testable and extensible

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend (Electron + React)" 
        direction TB
        ElectronHost["Electron Host\n(Node + Chromium)"]:::ui
        ElectronHost -->|launches| ReactRenderer

        ReactRenderer["React Renderer\n(SPA)"]:::ui
        ElectronHost -->|preload bridge| Preload["Preload Script"]:::ext
        click Preload "https://github.com/arashsameni/manocomputer/blob/master/frontend/public/preload.js"
        ElectronMain["Electron Main Process"]:::ext
        click ElectronMain "https://github.com/arashsameni/manocomputer/blob/master/frontend/public/main.js"
        ElectronMain -->|loads| ReactRenderer

        ReactRenderer -->|uses| Index["Entry Point\nindex.js"]:::ui
        click Index "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/index.js"
        ReactRenderer -->|renders| App["Root Component\nApp.jsx"]:::ui
        click App "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/App.jsx"

        subgraph "Contexts" 
            direction TB
            ThemeCtx["ThemeContext"]:::ui
            click ThemeCtx "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/contexts/ThemeContext.js"
            ComputerCtx["ComputerContext"]:::ui
            click ComputerCtx "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/contexts/ComputerContext.js"
        end
        ReactRenderer --> Contexts

        subgraph "LeftSideBar" 
            direction TB
            LeftSideBar["LeftSideBar"]:::ui
            click LeftSideBar "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/LeftSideBar.jsx"
            AboutUs["AboutUs"]:::ui
            click AboutUs "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/AboutUs/AboutUs.jsx"
            CodeEditor["CodeEditor"]:::ui
            click CodeEditor "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/CodeEditor/CodeEditor.jsx"
            FilesBar["FilesBar"]:::ui
            click FilesBar "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/FilesBar/FilesBar.jsx"
            StatusBar["StatusBar"]:::ui
            click StatusBar "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/StatusBar/StatusBar.jsx"
            AssembleBtn["AssembleButton"]:::ui
            click AssembleBtn "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/StatusBar/AssembleButton/AssembleButton.jsx"
            ToggleBtn["ToggleButton"]:::ui
            click ToggleBtn "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/LeftSideBar/StatusBar/ToggleButton/ToggleButton.jsx"
            LeftSideBar --> AboutUs
            LeftSideBar --> CodeEditor
            LeftSideBar --> FilesBar
            LeftSideBar --> StatusBar
            StatusBar --> AssembleBtn
            StatusBar --> ToggleBtn
        end
        ReactRenderer --> LeftSideBar

        subgraph "Simulator Pane" 
            direction TB
            Simulator["Simulator"]:::ui
            click Simulator "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/Simulator/Simulator.jsx"
            RAMView["RAM View"]:::ui
            click RAMView "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/components/Simulator/Ram/Ram.jsx"
            Simulator --> RAMView
            Simulator --> Registers["Registers View"]:::ui
        end
        ReactRenderer --> Simulator

        ReactRenderer -->|loads syntax highlighting| Prism["Prism.js"]:::ext
        click Prism "https://github.com/arashsameni/manocomputer/blob/master/frontend/src/assets/prism/mano-asm.js"

        ReactRenderer -->|reads files| ExampleFS["Example_Codes Folder"]:::fs
        click ExampleFS "https://github.com/arashsameni/manocomputer/tree/master/Example_Codes/"
    end

    subgraph "Backend (Flask API + Simulation)" 
        direction TB
        API["API Server\napi.py"]:::api
        click API "https://github.com/arashsameni/manocomputer/blob/master/backend/api.py"
        Init["Flask Init\n__init__.py"]:::api
        click Init "https://github.com/arashsameni/manocomputer/blob/master/backend/__init__.py"
        Requirements["Dependencies\nrequirements.txt"]:::api
        click Requirements "https://github.com/arashsameni/manocomputer/blob/master/backend/requirements.txt"
        API -->|calls| Assembler["Assembler Module"]:::sim
        click Assembler "https://github.com/arashsameni/manocomputer/blob/master/backend/assembler.py"
        Assembler -->|"tokenize/resolve"| Computer["Simulation Engine"]:::sim
        click Computer "https://github.com/arashsameni/manocomputer/blob/master/backend/computer.py"
        Computer --> RAMSim["RAM"]:::sim
        click RAMSim "https://github.com/arashsameni/manocomputer/blob/master/backend/ram.py"
        Computer --> RegSim["Registers"]:::sim
        click RegSim "https://github.com/arashsameni/manocomputer/blob/master/backend/register.py"
        Computer --> CondSim["Conditions"]:::sim
        click CondSim "https://github.com/arashsameni/manocomputer/blob/master/backend/conditions.py"
    end

    subgraph "Data Flow" 
        direction TB
        CodeEditor -->|POST /assemble| API
        API -->|200 OK machine code| ReactRenderer
        AssembleBtn -->|trigger assemble| ReactRenderer
        ReactRenderer -->|update| ComputerCtx
        ToggleBtn -->|step/run| API
        API -->|step result| ReactRenderer
    end

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#90EE90,stroke:#333,stroke-width:1px
    classDef sim fill:#FFD580,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef fs fill:#E6E6FA,stroke:#333,stroke-width:1px
```
