How advaitharyag/webic-trainer works
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: ui.js Trainer UI · simulation.js Simulation Engine · ic-registration.js IC Registry · ic-implementations.js IC Behaviors
Components 15
Browser UI
Single-page presentation and user orchestration in the browser.
- App Shell · Single-page entry point that loads the browser app.
index.html - Trainer UI · Main interaction layer for placing ICs, wiring, loading/saving, simulation views, and exports.
js/ui.js - Datasheet Links · 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 · Maintains wire connections and merged electrical nodes for the trainer board.
js/wiring-engine.js - Simulation Engine · Evaluates circuit state from placements, wiring, power, inputs, and clocks.
js/simulation.js - Clock Manager · Generates built-in clock pulses from low to high frequency sources.
js/clock-manager.js - TTL Model · Shared abstraction for supported TTL ICs and pin behavior.
js/ttl-chip.js - IC Behaviors · Concrete functional definitions for supported logic chips.
js/ic-implementations.js - IC Registry · Registers supported ICs and maps types to implementations.
js/ic-registration.js - IC Catalog · Resolves selectable IC metadata for the trainer UI.
js/ic-registry.js
Data & Outputs
Saved circuit snapshots, presets, and derived exports.
- Circuit JSON · Serialized circuit model for save and load operations.
- Preset Circuit · Prebuilt starter circuit snapshot used as a reusable input.
presets/sample-empty-circuit.json - Derived Outputs · Truth tables, waveform capture, and code generation outputs derived from simulation.
Repo Ops
Documentation and CI around the static client app.
- Architecture Notes · Repository documentation describing the trainer and its structure.
docs/ARCHITECTURE.md - CI Workflow · GitHub Actions workflow for automated checks.
.github/workflows/ci.yml
Connections 19
- 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.