# ayushdixit1-av/ar-project architecture

> Architecture diagram of the GitHub repository ayushdixit1-av/ar-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayushdixit1-av/ar-project
- Repository: https://github.com/ayushdixit1-av/ar-project

## Overview

#### Purpose and Module Boundaries
This repository is a collection of digital-electronics AR/3D lab prototypes. Its primary runnable implementation is Ayush’s browser-based breadboard simulator with WebXR AR support. A separate, more application-structured trainer prototype exists under `Shivam/source/`; other contributor folders mostly hold 3D assets or placeholders.

#### Primary Entry Points
- Ayush simulator: `Ayush/index.html` loads `Ayush/main.js`; local static serving is provided by `Ayush/serve.js`.
- AR-specific view: `Ayush/ar.html` and `Ayush/ARMode.js`.
- Shivam trainer source: `Shivam/source/index.html` → `Shivam/source/src/main.tsx` → `Shivam/source/src/App.tsx`.
- A prebuilt Shivam deployment is represented by `Shivam/index.html` and `Shivam/assets/index-ZWi_3kXW.js`.

#### Breadboard Scene and Physical Layout
Ayush’s simulator constructs a visual and logical solderless breadboard, including holes, labels, and power rails.
- Board geometry/configuration: `Ayush/BreadboardConfig.js`, `Ayush/BreadboardBody.js`
- Hole and rail generation: `Ayush/HoleGenerator.js`, `Ayush/Hole.js`, `Ayush/PowerRailGenerator.js`
- Display/feature composition: `Ayush/BreadboardShowcase.js`, `Ayush/EquipmentShowcase.js`

This layer is the coordinate-system boundary: placement tools and renderers target its hole/rail locations.

#### Interaction and Component Placement
Tool modules translate user actions into placed circuit entities, while managers own the resulting collections and lifecycle.
- IC workflow: `Ayush/ICPlacementTool.js`, `Ayush/ICManager.js`, `Ayush/IC.js`
- Wires: `Ayush/WirePlacementTool.js`, `Ayush/WireManager.js`, `Ayush/WireRenderer.js`
- LEDs and switches: `Ayush/LEDPlacementTool.js`, `Ayush/LEDManager.js`, `Ayush/SwitchPlacementTool.js`
- Power and probing: `Ayush/PowerSupplyTool.js`, `Ayush/PowerSupplyManager.js`, `Ayush/ProbeManager.js`

Renderers are separated from interaction/management for wires, LEDs, switches, probes, and power supplies.

#### Circuit Logic, Validation, and Learning Feedback
The simulation boundary consumes placed components and connectivity to evaluate circuit behavior and guide users.
- Simulation and broad validation: `Ayush/Simulator.js`, `Ayush/Validator.js`
- IC-specific validation and labels/previews: `Ayush/ICValidator.js`, `Ayush/ICLabel.js`, `Ayush/ICPreview.js`
- Educational/status panels: `Ayush/TruthTablePanel.js`, `Ayush/ExperimentGuide.js`, `Ayush/ProbePanel.js`
- Gate definitions/catalog: `Ayush/GateCatalog.js`

#### AR and Runtime Infrastructure
Ayush is plain browser JavaScript packaged as a static site, with Node used only to host it locally (`Ayush/package.json`, `Ayush/serve.js`). WebXR is exposed as a separate AR mode rather than a server-side service. The repository contains Blender source assets such as `Aadvik/bread.blend`, `Amar/SecondBlend.blend`, and `Shreya/trainer kit.glb`.

#### Shivam Trainer Prototype
`Shivam/source/` is a TypeScript/Vite application with a trainer-oriented UI shell around a 3D viewport and electronics instruction flows.
- Main composition and viewport: `Shivam/source/src/App.tsx`, `Shivam/source/src/components/Trainer3DViewport.tsx`
- Library/inspector controls: `Shivam/source/src/components/LeftSidebarLibrary.tsx`, `Shivam/source/src/components/RightSidebarInspector.tsx`
- Logic and 3D utilities: `Shivam/source/src/utils/logicEngine.ts`, `Shivam/source/src/utils/threeHelpers.ts`
- AR, verification, and instructional overlays: `Shivam/source/src/components/ARModeView.tsx`, `Shivam/source/src/components/TruthTableVerificationView.tsx`, `Shivam/source/src/components/AITeacherDrawer.tsx`

Main entry points: [`Ayush/main.js`](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/main.js) (Main composition), [`Shivam/source/src/App.tsx`](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/App.tsx) (Trainer UI shell), [`Ayush/ICPlacementTool.js`](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICPlacementTool.js) (Placement tools), [`Ayush/ICManager.js`](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICManager.js) (Component managers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ayush["Ayush simulator"]
  node_ayush_entry["Simulator entry<br/>browser entry<br/>[index.html]"]
  node_ayush_main["Main composition<br/>browser runtime<br/>[main.js]"]
  node_ayush_static_server["Local static server<br/>Node host<br/>[serve.js]"]
  node_breadboard["Breadboard layout<br/>scene geometry"]
  node_holes_rails["Holes and power rails<br/>layout generation<br/>[HoleGenerator.js]"]
  node_showcase["Board and equipment view<br/>scene composition"]
  node_placement["Placement tools<br/>interaction<br/>[ICPlacementTool.js]"]
  node_component_managers["Component managers<br/>component lifecycle<br/>[ICManager.js]"]
  node_renderers["Component renderers<br/>visual rendering<br/>[WireRenderer.js]"]
  node_simulation["Circuit simulation<br/>logic evaluation<br/>[Simulator.js]"]
  node_validation["Circuit validation<br/>[Validator.js]"]
  node_gate_catalog["Gate catalog<br/>logic definitions<br/>[GateCatalog.js]"]
  node_learning_feedback["Learning feedback<br/>educational UI<br/>[TruthTablePanel.js]"]
  node_ar_entry["AR mode<br/>WebXR view<br/>[ar.html]"]
  node_ar_runtime["AR runtime<br/>WebXR runtime<br/>[ARMode.js]"]
end

subgraph group_shivam["Shivam trainer"]
  node_shivam_entry["Trainer entry<br/>Vite entry<br/>[index.html]"]
  node_shivam_main["React bootstrap<br/>TypeScript runtime<br/>[main.tsx]"]
  node_trainer_app["Trainer UI shell<br/>application composition<br/>[App.tsx]"]
  node_trainer_viewport["3D trainer viewport<br/>3D interface"]
  node_trainer_controls["Trainer controls<br/>library and inspector UI"]
  node_trainer_logic["Trainer logic engine<br/>logic utility<br/>[logicEngine.ts]"]
  node_trainer_overlays["Trainer overlays<br/>AR and instruction UI<br/>[ARModeView.tsx]"]
end

node_ayush_entry -->|"loads"| node_ayush_main
node_ayush_static_server -->|"serves"| node_ayush_entry
node_ayush_main -->|"builds"| node_breadboard
node_breadboard -->|"generates"| node_holes_rails
node_holes_rails -->|"provides locations"| node_showcase
node_ayush_main -->|"composes"| node_showcase
node_ayush_main -->|"activates"| node_placement
node_placement -->|"targets coordinates"| node_breadboard
node_placement -->|"creates entities"| node_component_managers
node_component_managers -->|"supplies components"| node_renderers
node_component_managers -->|"supplies connectivity"| node_simulation
node_gate_catalog -->|"defines gates"| node_simulation
node_simulation -->|"evaluates"| node_validation
node_validation -->|"guides user"| node_learning_feedback
node_ar_entry -->|"loads"| node_ar_runtime
node_shivam_entry -->|"loads"| node_shivam_main
node_shivam_main -->|"mounts"| node_trainer_app
node_trainer_app -->|"composes"| node_trainer_viewport
node_trainer_app -->|"composes"| node_trainer_controls
node_trainer_app -->|"composes"| node_trainer_overlays
node_trainer_viewport -->|"uses"| node_trainer_logic
node_trainer_controls -->|"configures"| node_trainer_viewport

click node_ayush_entry "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/index.html"
click node_ayush_main "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/main.js"
click node_ayush_static_server "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/serve.js"
click node_breadboard "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/BreadboardConfig.js"
click node_holes_rails "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/HoleGenerator.js"
click node_showcase "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/BreadboardShowcase.js"
click node_placement "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICPlacementTool.js"
click node_component_managers "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICManager.js"
click node_renderers "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/WireRenderer.js"
click node_simulation "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/Simulator.js"
click node_validation "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/Validator.js"
click node_gate_catalog "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/GateCatalog.js"
click node_learning_feedback "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/TruthTablePanel.js"
click node_ar_entry "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ar.html"
click node_ar_runtime "https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ARMode.js"
click node_shivam_entry "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/index.html"
click node_shivam_main "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/main.tsx"
click node_trainer_app "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/App.tsx"
click node_trainer_viewport "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/Trainer3DViewport.tsx"
click node_trainer_controls "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/LeftSidebarLibrary.tsx"
click node_trainer_logic "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/utils/logicEngine.ts"
click node_trainer_overlays "https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/ARModeView.tsx"

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_ayush_entry,node_ayush_main,node_ayush_static_server,node_breadboard,node_holes_rails,node_showcase,node_placement,node_component_managers,node_renderers,node_simulation,node_validation,node_gate_catalog,node_learning_feedback,node_ar_entry,node_ar_runtime toneBlue
class node_shivam_entry,node_shivam_main,node_trainer_app,node_trainer_viewport,node_trainer_controls,node_trainer_logic,node_trainer_overlays toneAmber
```

## Components

### Ayush simulator

Browser-based breadboard and WebXR prototype.

- [Simulator entry](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/index.html): browser entry · `Ayush/index.html`
- [Main composition](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/main.js): browser runtime · `Ayush/main.js`
- [Local static server](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/serve.js): Node host · Hosts the static simulator locally. · `Ayush/serve.js`
- [Breadboard layout](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/BreadboardConfig.js): scene geometry · Coordinate-system boundary for holes and power rails. · `Ayush/BreadboardConfig.js`
- [Holes and power rails](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/HoleGenerator.js): layout generation · `Ayush/HoleGenerator.js`
- [Board and equipment view](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/BreadboardShowcase.js): scene composition · `Ayush/BreadboardShowcase.js`
- [Placement tools](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICPlacementTool.js): interaction · Places ICs, wires, LEDs, switches, and power supplies. · `Ayush/ICPlacementTool.js`
- [Component managers](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ICManager.js): component lifecycle · Own placed IC, wire, LED, switch, power, and probe collections. · `Ayush/ICManager.js`
- [Component renderers](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/WireRenderer.js): visual rendering · Renders wires, LEDs, switches, probes, and power supplies. · `Ayush/WireRenderer.js`
- [Circuit simulation](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/Simulator.js): logic evaluation · `Ayush/Simulator.js`
- [Circuit validation](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/Validator.js): validation · Combines broad and IC-specific circuit checks. · `Ayush/Validator.js`
- [Gate catalog](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/GateCatalog.js): logic definitions · `Ayush/GateCatalog.js`
- [Learning feedback](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/TruthTablePanel.js): educational UI · Truth tables, experiment guidance, and probe status. · `Ayush/TruthTablePanel.js`
- [AR mode](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ar.html): WebXR view · Separate browser AR experience. · `Ayush/ar.html`
- [AR runtime](https://github.com/ayushdixit1-av/ar-project/blob/main/Ayush/ARMode.js): WebXR runtime · `Ayush/ARMode.js`

### Shivam trainer

Separate TypeScript/Vite trainer prototype.

- [Trainer entry](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/index.html): Vite entry · `Shivam/source/index.html`
- [React bootstrap](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/main.tsx): TypeScript runtime · `Shivam/source/src/main.tsx`
- [Trainer UI shell](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/App.tsx): application composition · `Shivam/source/src/App.tsx`
- [3D trainer viewport](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/Trainer3DViewport.tsx): 3D interface · `Shivam/source/src/components/Trainer3DViewport.tsx`
- [Trainer controls](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/LeftSidebarLibrary.tsx): library and inspector UI · `Shivam/source/src/components/LeftSidebarLibrary.tsx`
- [Trainer logic engine](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/utils/logicEngine.ts): logic utility · `Shivam/source/src/utils/logicEngine.ts`
- [Trainer overlays](https://github.com/ayushdixit1-av/ar-project/blob/main/Shivam/source/src/components/ARModeView.tsx): AR and instruction UI · Provides AR, truth-table verification, and AI teacher views. · `Shivam/source/src/components/ARModeView.tsx`

## Connections

- Simulator entry → Main composition: loads
- Local static server → Simulator entry: serves
- Main composition → Breadboard layout: builds
- Breadboard layout → Holes and power rails: generates
- Holes and power rails → Board and equipment view: provides locations
- Main composition → Board and equipment view: composes
- Main composition → Placement tools: activates
- Placement tools → Breadboard layout: targets coordinates
- Placement tools → Component managers: creates entities
- Component managers → Component renderers: supplies components
- Component managers → Circuit simulation: supplies connectivity
- Gate catalog → Circuit simulation: defines gates
- Circuit simulation → Circuit validation: evaluates
- Circuit validation → Learning feedback: guides user
- AR mode → AR runtime: loads
- Trainer entry → React bootstrap: loads
- React bootstrap → Trainer UI shell: mounts
- Trainer UI shell → 3D trainer viewport: composes
- Trainer UI shell → Trainer controls: composes
- Trainer UI shell → Trainer overlays: composes
- 3D trainer viewport → Trainer logic engine: uses
- Trainer controls → 3D trainer viewport: configures