# void-sg/logic_sim_suite architecture

> Architecture diagram of the GitHub repository void-sg/logic_sim_suite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/void-sg/logic_sim_suite
- Repository: https://github.com/void-sg/logic_sim_suite

## Overview

OBSIDIAN is a browser-based digital logic simulator backed by a FastAPI service. The principal workflow is selecting a converter, arithmetic, comparator, multiplexer, or circuit-view page; submitting logic inputs to the API; and presenting the returned result or circuit layout. The graph preserves both ordinary logic operations and IC-style circuit layouts. Source excerpts establish backend routing and several simulator dependencies; frontend-to-API wiring and some backend implementations were not shown, so those links are omitted or marked unverified.

Main entry points: [`backend/main.py`](https://github.com/void-sg/logic_sim_suite/blob/main/backend/main.py) (FastAPI app), [`backend/circuit_router.py`](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_router.py) (Circuit routes), [`backend/circuit_models.py`](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_models.py) (Circuit models), [`backend/mux_router.py`](https://github.com/void-sg/logic_sim_suite/blob/main/backend/mux_router.py) (Mux route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser interface"]
  node_pages["Logic pages"]
  node_converter_ui["Converter engine"]
  node_viewer["Circuit viewer<br/>[circuit-viewer.js]"]
end

subgraph group_api["API routing"]
  node_api_main["FastAPI app<br/>[main.py]"]
  node_conversion_route["Conversion route<br/>[convert.py]"]
  node_arithmetic_route["Arithmetic route<br/>[arithmetic.py]"]
  node_compare_route["Compare route<br/>[compare.py]"]
  node_mux_route["Mux route<br/>[mux_router.py]"]
  node_circuit_route["Circuit routes<br/>[circuit_router.py]"]
end

subgraph group_logic["Logic simulators"]
  node_conversions["Code conversion"]
  node_adder["Adder subtractor"]
  node_comparator["Comparator<br/>[comparator.py]"]
  node_multiplexer["Multiplexer<br/>[mux.py]"]
end

subgraph group_circuits["Circuit layouts"]
  node_circuit_mux["8:1 mux layout<br/>[circuit_mux.py]"]
  node_circuit_standalone_mux["4:1 mux layout"]
  node_circuit_comparator["Comparator layout"]
  node_circuit_adder["Adder layout"]
  node_hardware_schematic["Converter schematic"]
end

subgraph group_contracts["Data contracts"]
  node_models["Circuit models<br/>[circuit_models.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

node_user(("User"))

node_user -.->|"chooses operation"| node_pages
node_pages -.->|"submits inputs"| node_api_main
node_api_main -->|"registers route"| node_conversion_route
node_api_main -->|"registers route"| node_arithmetic_route
node_api_main -->|"registers route"| node_compare_route
node_api_main -->|"registers route"| node_mux_route
node_api_main -->|"registers routes"| node_circuit_route
node_conversion_route -->|"calls logic"| node_conversions
node_arithmetic_route -->|"calls logic"| node_adder
node_compare_route -->|"calls logic"| node_comparator
node_mux_route -->|"calls simulator"| node_multiplexer
node_circuit_route -->|"dispatches layout"| node_circuit_mux
node_circuit_route -->|"dispatches layout"| node_circuit_standalone_mux
node_circuit_route -->|"dispatches layout"| node_circuit_comparator
node_circuit_route -->|"dispatches layout"| node_circuit_adder
node_circuit_mux -->|"reuses logic"| node_multiplexer
node_circuit_standalone_mux -->|"reuses logic"| node_multiplexer
node_circuit_comparator -->|"reuses logic"| node_comparator
node_circuit_adder -->|"reuses logic"| node_adder
node_circuit_mux -->|"builds response"| node_models
node_circuit_standalone_mux -->|"builds response"| node_models
node_circuit_comparator -->|"builds response"| node_models
node_circuit_adder -->|"builds response"| node_models
node_mux_route -->|"uses contract"| node_schemas
node_circuit_route -->|"uses contract"| node_schemas
node_viewer -.->|"requests layouts"| node_api_main
node_converter_ui -.->|"requests conversion"| node_api_main

click node_pages "https://github.com/void-sg/logic_sim_suite/tree/main/frontend"
click node_converter_ui "https://github.com/void-sg/logic_sim_suite/blob/main/frontend/converter-engine.js"
click node_viewer "https://github.com/void-sg/logic_sim_suite/blob/main/frontend/circuit-viewer.js"
click node_api_main "https://github.com/void-sg/logic_sim_suite/blob/main/backend/main.py"
click node_conversion_route "https://github.com/void-sg/logic_sim_suite/blob/main/backend/convert.py"
click node_arithmetic_route "https://github.com/void-sg/logic_sim_suite/blob/main/backend/arithmetic.py"
click node_compare_route "https://github.com/void-sg/logic_sim_suite/blob/main/backend/compare.py"
click node_mux_route "https://github.com/void-sg/logic_sim_suite/blob/main/backend/mux_router.py"
click node_circuit_route "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_router.py"
click node_conversions "https://github.com/void-sg/logic_sim_suite/blob/main/backend/code_conversions.py"
click node_adder "https://github.com/void-sg/logic_sim_suite/blob/main/backend/adder_subtractor.py"
click node_comparator "https://github.com/void-sg/logic_sim_suite/blob/main/backend/comparator.py"
click node_multiplexer "https://github.com/void-sg/logic_sim_suite/blob/main/backend/mux.py"
click node_circuit_mux "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_mux.py"
click node_circuit_standalone_mux "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_standalone_mux.py"
click node_circuit_comparator "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_comparator.py"
click node_circuit_adder "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_adder_subtractor.py"
click node_models "https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_models.py"
click node_schemas "https://github.com/void-sg/logic_sim_suite/blob/main/backend/schemas.py"
click node_hardware_schematic "https://github.com/void-sg/logic_sim_suite/blob/main/hardware/code_converter_4bit/code_converter_4bit.kicad_sch"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pages,node_converter_ui,node_viewer,node_user toneBlue
class node_api_main,node_conversion_route,node_arithmetic_route,node_compare_route,node_mux_route,node_circuit_route toneAmber
class node_conversions,node_adder,node_comparator,node_multiplexer toneMint
class node_circuit_mux,node_circuit_standalone_mux,node_circuit_comparator,node_circuit_adder,node_hardware_schematic toneRose
class node_models,node_schemas toneIndigo
```

## Components

### Browser interface

- [Logic pages](https://github.com/void-sg/logic_sim_suite/tree/main/frontend): `frontend`
- [Converter engine](https://github.com/void-sg/logic_sim_suite/blob/main/frontend/converter-engine.js): `frontend/converter-engine.js`
- [Circuit viewer](https://github.com/void-sg/logic_sim_suite/blob/main/frontend/circuit-viewer.js): `frontend/circuit-viewer.js`

### API routing

- [FastAPI app](https://github.com/void-sg/logic_sim_suite/blob/main/backend/main.py): `backend/main.py`
- [Conversion route](https://github.com/void-sg/logic_sim_suite/blob/main/backend/convert.py): `backend/convert.py`
- [Arithmetic route](https://github.com/void-sg/logic_sim_suite/blob/main/backend/arithmetic.py): `backend/arithmetic.py`
- [Compare route](https://github.com/void-sg/logic_sim_suite/blob/main/backend/compare.py): `backend/compare.py`
- [Mux route](https://github.com/void-sg/logic_sim_suite/blob/main/backend/mux_router.py): `backend/mux_router.py`
- [Circuit routes](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_router.py): `backend/circuit_router.py`

### Logic simulators

- [Code conversion](https://github.com/void-sg/logic_sim_suite/blob/main/backend/code_conversions.py): `backend/code_conversions.py`
- [Adder subtractor](https://github.com/void-sg/logic_sim_suite/blob/main/backend/adder_subtractor.py): `backend/adder_subtractor.py`
- [Comparator](https://github.com/void-sg/logic_sim_suite/blob/main/backend/comparator.py): `backend/comparator.py`
- [Multiplexer](https://github.com/void-sg/logic_sim_suite/blob/main/backend/mux.py): `backend/mux.py`

### Circuit layouts

- [8:1 mux layout](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_mux.py): `backend/circuit_mux.py`
- [4:1 mux layout](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_standalone_mux.py): `backend/circuit_standalone_mux.py`
- [Comparator layout](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_comparator.py): `backend/circuit_comparator.py`
- [Adder layout](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_adder_subtractor.py): `backend/circuit_adder_subtractor.py`
- [Converter schematic](https://github.com/void-sg/logic_sim_suite/blob/main/hardware/code_converter_4bit/code_converter_4bit.kicad_sch): `hardware/code_converter_4bit/code_converter_4bit.kicad_sch`

### Data contracts

- [Circuit models](https://github.com/void-sg/logic_sim_suite/blob/main/backend/circuit_models.py): `backend/circuit_models.py`
- [API schemas](https://github.com/void-sg/logic_sim_suite/blob/main/backend/schemas.py): `backend/schemas.py`

### Other components

- **User**

## Connections

- User → Logic pages: chooses operation
- Logic pages → FastAPI app: submits inputs
- FastAPI app → Conversion route: registers route (evidence: `backend/main.py`)
- FastAPI app → Arithmetic route: registers route (evidence: `backend/main.py`)
- FastAPI app → Compare route: registers route (evidence: `backend/main.py`)
- FastAPI app → Mux route: registers route (evidence: `backend/main.py`)
- FastAPI app → Circuit routes: registers routes (evidence: `backend/main.py`)
- Conversion route → Code conversion: calls logic (evidence: `backend/convert.py`)
- Arithmetic route → Adder subtractor: calls logic (evidence: `backend/arithmetic.py`)
- Compare route → Comparator: calls logic (evidence: `backend/compare.py`)
- Mux route → Multiplexer: calls simulator (evidence: `backend/mux_router.py`)
- Circuit routes → 8:1 mux layout: dispatches layout (evidence: `backend/circuit_router.py`)
- Circuit routes → 4:1 mux layout: dispatches layout (evidence: `backend/circuit_router.py`)
- Circuit routes → Comparator layout: dispatches layout (evidence: `backend/circuit_router.py`)
- Circuit routes → Adder layout: dispatches layout (evidence: `backend/circuit_router.py`)
- 8:1 mux layout → Multiplexer: reuses logic (evidence: `backend/circuit_mux.py`)
- 4:1 mux layout → Multiplexer: reuses logic (evidence: `backend/circuit_standalone_mux.py`)
- Comparator layout → Comparator: reuses logic (evidence: `backend/circuit_comparator.py`)
- Adder layout → Adder subtractor: reuses logic (evidence: `backend/circuit_adder_subtractor.py`)
- 8:1 mux layout → Circuit models: builds response (evidence: `backend/circuit_mux.py`)
- 4:1 mux layout → Circuit models: builds response (evidence: `backend/circuit_standalone_mux.py`)
- Comparator layout → Circuit models: builds response (evidence: `backend/circuit_comparator.py`)
- Adder layout → Circuit models: builds response (evidence: `backend/circuit_adder_subtractor.py`)
- Mux route → API schemas: uses contract (evidence: `backend/mux_router.py`)
- Circuit routes → API schemas: uses contract (evidence: `backend/circuit_router.py`)
- Circuit viewer → FastAPI app: requests layouts
- Converter engine → FastAPI app: requests conversion
