# advaitharyag/webic-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/advaitharyag/webic-trainer
- Repository: https://github.com/advaitharyag/webic-trainer

## Overview

1. **Overall shape**
   - This is a **single-page, browser-only digital logic trainer**. There is no backend service in the repo; the entire app runs from `index.html` and the JavaScript modules under `js/`.
   - The architecture is centered on a **circuit editor + simulator + export tools** loop.

2. **UI/orchestration layer**
   - `js/ui.js` is the main entry point and orchestration layer.
   - It owns user-facing actions such as adding ICs, wiring, loading/saving JSON, running truth tables, waveform viewing, code generation, and opening datasheets.
   - It also bridges the visual state in the browser to the underlying circuit model and simulation engine.

3. **Circuit interaction model**
   - The UI exposes a fixed trainer environment with **4 IC sockets** (`ic-1` to `ic-4`) plus built-in resources like power rails, clocks, switches, LEDs, and a BCD display area.
   - User interactions primarily fall into two categories: **placing/removing ICs** and **creating/removing wires** between valid board pins and trainer resources.

4. **Wiring subsystem**
   - `js/wiring-engine.js` is the graph/bus layer for the circuit layout.
   - It handles wire connections and node merging so that different pins/resources can be treated as electrically linked.
   - This is the main boundary between the user-drawn circuit and the logic simulation, because it defines what is actually connected.

5. **Simulation subsystem**
   - `js/simulation.js` is the digital logic execution engine.
   - It evaluates the circuit state based on IC placement, wiring connectivity, power, inputs, and clock changes.
   - Output from simulation drives features like LED states, truth tables, waveform capture, and any code-generation/export data derived from circuit behavior.

6. **IC abstraction and behavior**
   - `js/ttl-chip.js` defines the TTL chip model/abstraction used across the app.
   - `js/ic-implementations.js` contains the actual behavior definitions for supported 74LS parts.
   - `js/ic-registration.js` and `js/ic-registry.js` form the metadata/lookup layer that maps IC types to their implementations and make them selectable in the UI.

7. **Clock and time-based behavior**
   - `js/clock-manager.js` manages the built-in clock sources (`1Hz` through `10kHz`) and pulse generation.
   - These time-based signals feed into the wiring/simulation system, enabling synchronous IC behavior and waveform capture.

8. **Persistence and circuit schema**
   - Circuits are saved and loaded as **JSON snapshots** using the schema `ic-trainer-circuit-v1`.
   - The saved model includes: IC placements, wires, switch states, power state, preset metadata, and optional expression metadata.
   - Load-time validation is important here because the app explicitly constrains socket IDs, supported IC types, and pin references.

9. **Preset and demo data**
   - The `presets/` directory contains prebuilt circuit JSON files, such as `sample-empty-circuit.json`.
   - These act as reusable starting points or demo configurations and are part of the app’s circuit-input layer rather than code.

10. **Derived tools and outputs**
   - Several features are not separate subsystems but outputs of the same circuit model: **truth table generation**, **waveform viewing**, and **code export** to Arduino, Python, C/C++, and Verilog.
   - The Boolean expression builder also sits on top of the circuit model: it turns a logic expression into IC placement and wiring automatically.

11. **External integration boundary**
   - The only notable external dependency in the architecture is **datasheet linking**: the UI opens PDF URLs in a new tab from a hardcoded mapping in `ui.js`.
   - This is an external documentation/viewing boundary, not an API integration.

12. **Repo structure and delivery**
   - The repository is intentionally lightweight: static HTML, modular JavaScript, JSON presets, and documentation.
   - `.github/workflows/ci.yml` suggests CI exists for validation/build checks, but the runtime architecture remains fully client-side and deployable as static files.

13. **How the pieces flow together**
   - A user action in the UI updates the circuit model.
   - Wiring changes update connectivity.
   - The simulation engine evaluates the current graph and IC behaviors.
   - UI panels such as LEDs, truth tables, waveform capture, and exporters read from that evaluated state.
   - Save/load serializes and restores the same circuit model, making the UI state reproducible.

14. **Diagram boundaries to show**
   - A useful architecture diagram should separate:
     - **Presentation/UI**
     - **Circuit graph/wiring**
     - **Logic simulation**
     - **IC registry/implementations**
     - **Clock/timing**
     - **Persistence/import-export**
     - **Static presets and docs**
   - The key internal dependency direction is: **UI → wiring model → simulation → derived outputs**, with IC metadata/implementations feeding the simulator.

Main entry points: [`js/ui.js`](https://github.com/advaitharyag/webic-trainer/blob/main/js/ui.js) (Trainer UI), [`js/simulation.js`](https://github.com/advaitharyag/webic-trainer/blob/main/js/simulation.js) (Simulation Engine), [`js/ic-registration.js`](https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-registration.js) (IC Registry), [`js/ic-implementations.js`](https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-implementations.js) (IC Behaviors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Browser UI"]
  node_n_index["App Shell<br/>static html<br/>[index.html]"]
  node_n_ui["Trainer UI<br/>orchestrator<br/>[ui.js]"]
  node_n_datasheet["Datasheet Links<br/>external docs<br/>[ui.js]"]
end

subgraph group_group_core["Circuit Core"]
  node_n_wiring{{"Wiring Engine<br/>connectivity graph<br/>[wiring-engine.js]"}}
  node_n_sim["Simulation Engine<br/>logic evaluator<br/>[simulation.js]"]
  node_n_clock(("Clock Manager<br/>timing source<br/>[clock-manager.js]"))
  node_n_ttl["TTL Model<br/>chip abstraction<br/>[ttl-chip.js]"]
  node_n_impl["IC Behaviors<br/>74LS implementations"]
  node_n_reg["IC Registry<br/>lookup layer<br/>[ic-registration.js]"]
  node_n_lookup["IC Catalog<br/>selection registry<br/>[ic-registry.js]"]
end

subgraph group_group_data["Data & Outputs"]
  node_n_save["Circuit JSON<br/>snapshot schema"]
  node_n_preset["Preset Circuit<br/>sample data"]
  node_n_outputs["Derived Outputs<br/>reports & export"]
end

subgraph group_group_docs["Repo Ops"]
  node_n_readme["Architecture Notes<br/>docs<br/>[ARCHITECTURE.md]"]
  node_n_ci["CI Workflow<br/>validation<br/>[ci.yml]"]
end

node_n_index -->|"loads"| node_n_ui
node_n_ui -->|"edits graph"| node_n_wiring
node_n_ui -->|"runs"| node_n_sim
node_n_ui -->|"controls timing"| node_n_clock
node_n_ui -->|"selects ICs"| node_n_lookup
node_n_ui -->|"save/load"| node_n_save
node_n_ui -->|"opens docs"| node_n_datasheet
node_n_wiring -->|"connectivity"| node_n_sim
node_n_clock -->|"pulses"| node_n_sim
node_n_lookup -->|"resolves"| node_n_reg
node_n_reg -->|"adapts"| node_n_ttl
node_n_reg -->|"maps to"| node_n_impl
node_n_impl -->|"executes logic"| node_n_sim
node_n_ttl -->|"models pins"| node_n_impl
node_n_sim -->|"drives"| node_n_outputs
node_n_save -->|"shares schema"| node_n_preset
node_n_preset -->|"starts from"| node_n_ui
node_n_readme -.->|"documents"| node_n_ui
node_n_ci -.->|"validates"| node_n_save

click node_n_index "https://github.com/advaitharyag/webic-trainer/blob/main/index.html"
click node_n_ui "https://github.com/advaitharyag/webic-trainer/blob/main/js/ui.js"
click node_n_datasheet "https://github.com/advaitharyag/webic-trainer/blob/main/js/ui.js"
click node_n_wiring "https://github.com/advaitharyag/webic-trainer/blob/main/js/wiring-engine.js"
click node_n_sim "https://github.com/advaitharyag/webic-trainer/blob/main/js/simulation.js"
click node_n_clock "https://github.com/advaitharyag/webic-trainer/blob/main/js/clock-manager.js"
click node_n_ttl "https://github.com/advaitharyag/webic-trainer/blob/main/js/ttl-chip.js"
click node_n_impl "https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-implementations.js"
click node_n_reg "https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-registration.js"
click node_n_lookup "https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-registry.js"
click node_n_preset "https://github.com/advaitharyag/webic-trainer/blob/main/presets/sample-empty-circuit.json"
click node_n_readme "https://github.com/advaitharyag/webic-trainer/blob/main/docs/ARCHITECTURE.md"
click node_n_ci "https://github.com/advaitharyag/webic-trainer/blob/main/.github/workflows/ci.yml"

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_n_index,node_n_ui,node_n_datasheet toneBlue
class node_n_wiring,node_n_sim,node_n_clock,node_n_ttl,node_n_impl,node_n_reg,node_n_lookup toneAmber
class node_n_save,node_n_preset,node_n_outputs toneMint
class node_n_readme,node_n_ci toneRose
```

## Components

### Browser UI

Single-page presentation and user orchestration in the browser.

- [App Shell](https://github.com/advaitharyag/webic-trainer/blob/main/index.html): static html · Single-page entry point that loads the browser app. · `index.html`
- [Trainer UI](https://github.com/advaitharyag/webic-trainer/blob/main/js/ui.js): orchestrator · Main interaction layer for placing ICs, wiring, loading/saving, simulation views, and exports. · `js/ui.js`
- [Datasheet Links](https://github.com/advaitharyag/webic-trainer/blob/main/js/ui.js): external docs · Hardcoded mapping that opens chip datasheets in a browser tab. · `js/ui.js`

### Circuit Core

Connectivity, simulation, and IC behavior for the trainer model.

- [Wiring Engine](https://github.com/advaitharyag/webic-trainer/blob/main/js/wiring-engine.js): connectivity graph · Maintains wire connections and merged electrical nodes for the trainer board. · `js/wiring-engine.js`
- [Simulation Engine](https://github.com/advaitharyag/webic-trainer/blob/main/js/simulation.js): logic evaluator · Evaluates circuit state from placements, wiring, power, inputs, and clocks. · `js/simulation.js`
- [Clock Manager](https://github.com/advaitharyag/webic-trainer/blob/main/js/clock-manager.js): timing source · Generates built-in clock pulses from low to high frequency sources. · `js/clock-manager.js`
- [TTL Model](https://github.com/advaitharyag/webic-trainer/blob/main/js/ttl-chip.js): chip abstraction · Shared abstraction for supported TTL ICs and pin behavior. · `js/ttl-chip.js`
- [IC Behaviors](https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-implementations.js): 74LS implementations · Concrete functional definitions for supported logic chips. · `js/ic-implementations.js`
- [IC Registry](https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-registration.js): lookup layer · Registers supported ICs and maps types to implementations. · `js/ic-registration.js`
- [IC Catalog](https://github.com/advaitharyag/webic-trainer/blob/main/js/ic-registry.js): selection registry · Resolves selectable IC metadata for the trainer UI. · `js/ic-registry.js`

### Data & Outputs

Saved circuit snapshots, presets, and derived exports.

- **Circuit JSON**: snapshot schema · Serialized circuit model for save and load operations.
- [Preset Circuit](https://github.com/advaitharyag/webic-trainer/blob/main/presets/sample-empty-circuit.json): sample data · Prebuilt starter circuit snapshot used as a reusable input. · `presets/sample-empty-circuit.json`
- **Derived Outputs**: reports & export · Truth tables, waveform capture, and code generation outputs derived from simulation.

### Repo Ops

Documentation and CI around the static client app.

- [Architecture Notes](https://github.com/advaitharyag/webic-trainer/blob/main/docs/ARCHITECTURE.md): docs · Repository documentation describing the trainer and its structure. · `docs/ARCHITECTURE.md`
- [CI Workflow](https://github.com/advaitharyag/webic-trainer/blob/main/.github/workflows/ci.yml): validation · GitHub Actions workflow for automated checks. · `.github/workflows/ci.yml`

## Connections

- App Shell → Trainer UI: loads · The app shell bootstraps the main browser UI.
- Trainer UI → Wiring Engine: edits graph · User actions create, remove, and inspect board connections.
- Trainer UI → Simulation Engine: runs · UI triggers simulation and reads evaluated circuit state.
- Trainer UI → Clock Manager: controls timing · UI exposes clock sources and pulse control.
- Trainer UI → IC Catalog: selects ICs · The interface uses the registry to populate supported parts.
- Trainer UI → Circuit JSON: save/load · UI serializes and restores circuit snapshots.
- Trainer UI → Datasheet Links: opens docs · UI launches external datasheet PDFs for supported ICs.
- Wiring Engine → Simulation Engine: connectivity · Merged electrical nodes define what the simulator sees as connected.
- Clock Manager → Simulation Engine: pulses · Clock sources feed synchronous behavior into simulation.
- IC Catalog → IC Registry: resolves · Catalog lookup is backed by the registration layer.
- IC Registry → TTL Model: adapts · Registered part metadata is bound to the shared TTL abstraction.
- IC Registry → IC Behaviors: maps to · Registry points each supported IC type to its behavior implementation.
- IC Behaviors → Simulation Engine: executes logic · Chip behavior definitions are evaluated by the simulator.
- TTL Model → IC Behaviors: models pins · The abstraction standardizes pin and chip-level behavior.
- Simulation Engine → Derived Outputs: drives · Simulation results feed truth tables, waveforms, and code export.
- Circuit JSON → Preset Circuit: shares schema · Preset circuits are stored as the same JSON snapshot format.
- Preset Circuit → Trainer UI: starts from · Presets are loaded into the interactive trainer.
- Architecture Notes → Trainer UI: documents · Repository docs explain the browser app and architecture.
- CI Workflow → Circuit JSON: validates · CI likely checks repository consistency and snapshot validity.
