# DigiSim — Complete Platform Documentation

> DigiSim.io is a browser-based digital logic circuit simulator and interactive learning platform. It enables users to build, simulate, and share digital circuits using 60+ components — from basic logic gates to complete 8-bit CPU architectures. The platform includes SimCast animated lessons narrated in 5 languages and uses a one-time purchase pricing model.

Website: https://digisim.io
Simulator: https://digisim.io/circuits/new

## Platform Overview

DigiSim is designed for computer science students, electrical engineering learners, educators, and hobbyists. It provides:

- A real-time circuit simulator with drag-and-drop component placement
- 60+ digital logic components with standardized pin interfaces
- An event-driven simulation engine with signal propagation
- SimCast: animated step-by-step circuit-building lessons with audio narration
- 70+ pre-built educational template circuits across 7 difficulty categories
- Circuit saving, sharing via public links, and cloud synchronization
- Multi-language support: English, Chinese (Simplified), Japanese, Spanish, Korean

## Component Library (60+ Components)

### Input Components
- **Switch** — Manual high/low signal toggle
- **Clock** — Periodic square wave generator with configurable frequency
- **Constant 1** — Always outputs logic high
- **Constant 0** — Always outputs logic low

### Basic Logic Gates
- **AND Gate** — Output high when all inputs are high
- **OR Gate** — Output high when any input is high
- **NOT Gate (Inverter)** — Inverts the input signal
- **Buffer** — Passes signal without change (used for isolation)
- **NAND Gate** — Inverted AND (universal gate)
- **NOR Gate** — Inverted OR (universal gate)
- **XOR Gate** — Output high when inputs differ
- **XNOR Gate** — Output high when inputs are the same

### Tri-State Components
- **Tri-State Buffer** — 1-bit buffer with enable control (high-Z when disabled)
- **8-bit Tri-State Buffer** — 8-bit version for bus systems

### Data Routing
- **2:1 Multiplexer** — Selects one of 2 inputs
- **4:1 Multiplexer** — Selects one of 4 inputs
- **8:1 Multiplexer** — Selects one of 8 inputs
- **1:2 Demultiplexer** — Routes input to one of 2 outputs
- **1:4 Demultiplexer** — Routes input to one of 4 outputs
- **1:8 Demultiplexer** — Routes input to one of 8 outputs
- **4:2 Encoder** — Encodes 4 inputs to 2-bit binary
- **8:3 Encoder** — Encodes 8 inputs to 3-bit binary
- **2:4 Decoder** — Decodes 2-bit binary to 4 outputs
- **3:8 Decoder** — Decodes 3-bit binary to 8 outputs

### Arithmetic Components
- **Half Adder** — Adds two 1-bit inputs, produces sum and carry
- **Full Adder** — Adds two 1-bit inputs with carry-in
- **4-bit Adder** — Ripple-carry adder for 4-bit addition
- **8-bit Adder** — Ripple-carry adder for 8-bit addition
- **4-bit Comparator** — Compares two 4-bit numbers (greater, equal, less)
- **8-bit Comparator** — Compares two 8-bit numbers
- **4-bit ALU** — Arithmetic Logic Unit supporting add, subtract, AND, OR, XOR, NOT
- **8-bit ALU** — Full 8-bit ALU with carry and overflow flags

### Sequential Logic
- **SR Latch** — Set-Reset latch (level-triggered)
- **D Latch** — Data latch (level-triggered, transparent when enabled)
- **D Flip-Flop** — Edge-triggered data storage
- **JK Flip-Flop** — Universal flip-flop with toggle capability
- **T Flip-Flop** — Toggle flip-flop (frequency divider)

### Registers & Counters
- **4-bit Register** — Parallel-load 4-bit storage
- **8-bit Register** — Parallel-load 8-bit storage
- **4-bit Shift Register** — Serial-in/parallel-out shift register
- **8-bit Shift Register** — 8-bit serial-in/parallel-out
- **4-bit Counter** — Synchronous up counter with reset
- **8-bit Counter** — 8-bit counter with load, reset, and enable
- **Flags Register** — CPU status flags (zero, carry, negative, overflow)

### CPU Components
- **Program Counter (8-bit)** — Tracks the current instruction address
- **Instruction Register** — Holds the currently executing instruction
- **Control Unit** — Decodes instructions and generates control signals
- **Accumulator** — Primary CPU register for arithmetic operations
- **Assembly Program Loader** — Loads and executes 8-bit assembly programs

### Memory
- **RAM (256×8)** — Random-access read/write memory, 256 bytes
- **ROM (256×8)** — Read-only memory, 256 bytes, programmable

### Output & Display
- **Output Light** — LED indicator (on/off based on input)
- **7-Segment Display (4-bit)** — Displays 0-9 from 4-bit BCD input
- **7-Segment Display (8-pin)** — Individual segment control
- **2-Channel Oscilloscope** — Real-time waveform visualization
- **8-Channel Oscilloscope** — Advanced multi-signal analysis
- **16×16 Pixel Screen** — Graphics output for CPU programming projects

## SimCast — Animated Lesson System

SimCast is DigiSim's interactive lesson format. Each lesson is a sequence of animated steps that builds a circuit from scratch:

1. **Press Play** — The simulator opens with an empty canvas
2. **Watch It Build** — Components appear, wires connect, and the circuit assembles step by step
3. **Explore & Learn** — Pause anytime, toggle inputs, trace signals, interact with the running circuit

### Key Features
- 155+ animated lessons spanning basic gates to CPU architecture
- Audio narration in 5 languages (English, Chinese, Japanese, Spanish, Korean)
- Subtitle tracks synchronized with each animation step
- Variable playback speed with pause/rewind controls
- Lessons organized into 8 themed "SimCast Sets" following cognitive-flow learning

### SimCast Sets (Themed Lesson Bundles)
1. **Digital Foundations** — Binary signals, switches, and basic inputs
2. **Logic Gates** — AND, OR, NOT, NAND, NOR, XOR, XNOR
3. **Boolean Optimization** — Gate combinations and derived circuits
4. **Arithmetic Circuits** — Adders, comparators, ALU design
5. **Data Routing** — Multiplexers, demultiplexers, encoders, decoders
6. **Latches & Flip-Flops** — SR, D, JK, T sequential elements
7. **Registers & Counters** — Storage, shifting, counting circuits
8. **State Machines** — Control units and CPU-level design

## Template Circuit Library

70+ pre-built educational circuits organized by category and difficulty:

### Categories
1. **Logic Fundamentals & Basic Gates** — Introduction to digital logic
2. **Combining & Derived Gates** — NAND/NOR universality, complex combinations
3. **Combinational Circuits** — Adders, multiplexers, encoders, decoders
4. **Memory & Sequential Logic** — Flip-flops, latches, state machines
5. **Registers, Counters & Memory** — Data storage and counting circuits
6. **Output and Visualization** — Display systems, oscilloscopes, debugging
7. **CPU Components & Architecture** — Processor design, instruction execution

### Difficulty Levels
- **Beginner** — Simple circuits with 2-5 components
- **Intermediate** — Multi-component designs with sequential logic
- **Advanced** — CPU-level architectures and complex systems

## Pricing Model

DigiSim uses a one-time purchase model (no subscription). Payment is processed through Stripe.

| Tier | Components | Lessons | Saved Circuits |
|------|-----------|---------|----------------|
| Free | ~15 basic gates and I/O | Subset of free lessons | 3 |
| Fundamental | ~35 including sequential logic | Extended set | 20 |
| Professional | ~55 including ALU, memory | Most lessons | 100 |
| Max | All 60+ including CPU components | All lessons | Unlimited |

- **Education Discount**: Students and educators with academic email addresses (.edu, .ac.uk, etc.) receive 50% off all paid tiers automatically at checkout.
- **Upgrade Path**: Users can upgrade from any tier to a higher one, paying only the price difference.

## Technical Architecture

### Frontend
- **Framework**: Angular 20 with TypeScript
- **UI**: Angular Material with custom theming
- **Simulation**: Event-driven simulator service with real-time signal propagation
- **State**: RxJS-based reactive state management

### Backend
- **Framework**: Spring Boot 3.5 (Java)
- **Database**: MySQL 8.4 on AWS RDS
- **API Protocol**: Protocol Buffers (not JSON)
- **Authentication**: Firebase Auth + JWT tokens
- **Payments**: Stripe Checkout Sessions (one-time purchases)
- **AI/Localization**: Google Cloud Generative AI for multi-language audio generation
- **CDN**: AWS CloudFront for static assets and circuit sharing

### API Overview (Protobuf)

**Public Endpoints (No Authentication)**:
- `POST /pub/api/digisim/products/pricing` — Get pricing tiers and product data
- `POST /pub/api/digisim/templates/list` — List template circuits
- `GET /pub/api/digisim/lesson-circuits/slug/{slug}` — Get SimCast lesson by slug
- `POST /pub/api/digisim/simcast/sets` — Get SimCast Sets
- `POST /pub/api/digisim/simcast/lessons` — Get SimCast lessons

**Authenticated Endpoints**:
- `POST /api/digisim/circuits/save` — Save a circuit
- `POST /api/digisim/circuits/get` — Get user's saved circuits
- `POST /api/digisim/circuits/delete` — Delete a circuit
- `POST /api/digisim/circuits/share` — Share a circuit publicly
- `POST /api/digisim/products/access/components` — Check accessible components
- `POST /api/digisim/products/upgrade/check` — Get available tier upgrades

**Authentication**:
- `POST /auth/firebase/signin` — Exchange Firebase token for JWT
- All authenticated requests use Bearer JWT in Authorization header

## Internationalization

The platform supports 5 languages:
- **English (en)** — Default, URL: `https://digisim.io/`
- **Chinese Simplified (zh-Hans)** — URL: `https://digisim.io/zh/`
- **Japanese (ja)** — URL: `https://digisim.io/ja/`
- **Spanish (es)** — URL: `https://digisim.io/es/`
- **Korean (ko)** — URL: `https://digisim.io/ko/`

All marketing pages, documentation, SEO metadata, and SimCast narration are available in all 5 languages. The simulator UI uses NGX-Translate for runtime language switching.