# DigiSim - Complete Documentation

> DigiSim is a comprehensive digital logic circuit simulator and educational platform built with Angular and TypeScript. It provides an intuitive web-based interface for designing, simulating, and analyzing digital circuits, from basic logic gates to complete CPU architectures.

## Platform Overview

DigiSim serves as both an educational tool and a professional circuit design platform. The system supports:

- **Real-time Circuit Simulation**: Dual simulation engines (event-driven and iterative) for accurate digital circuit behavior
- **Component-based Architecture**: Modular design with 50+ logic components including gates, flip-flops, counters, ALUs, and memory systems
- **Educational Progression**: Structured learning path from basic logic to CPU architecture
- **Subscription Model**: Tiered access (FREE, BASIC, PROFESSIONAL) with progressive component unlocking
- **Template System**: Curated educational circuits with professional documentation
- **Export Capabilities**: PNG export and simulation file formats for sharing and documentation

## Core Architecture

### Frontend (Angular 20+)
- **Component Library**: 50+ digital logic components with standardized pin configurations
- **Simulation Services**: EventDrivenSimulatorService and LegacySimulatorService for circuit evaluation
- **Workspace Management**: Drag-and-drop circuit builder with connection management
- **Subscription Integration**: Dynamic component access control based on user subscription
- **Template Browser**: Material 3 design system for circuit template discovery
- **Export System**: PNG generation without external dependencies using native browser APIs

### Backend Integration
- **Protobuf APIs**: Type-safe communication with backend services
- **Authentication**: JWT-based auth with Google, Apple, and email sign-in
- **Circuit Storage**: Save/load circuit files with metadata and AI summaries
- **Template Management**: CRUD operations for educational circuit templates
- **Subscription Management**: PayPal integration for subscription billing

### Component System
The platform includes comprehensive digital logic components:

**Basic Logic Gates**: AND, OR, NOT, NAND, NOR, XOR, XNOR, Buffer
**Input Components**: Switch, Clock, Constant values
**Output Components**: Light, 7-Segment Display, Oscilloscope
**Sequential Logic**: D/JK/T Flip-flops, SR/D Latches, Registers, Counters
**Arithmetic**: 8-bit ALU, Binary Adders, Comparators
**Memory Systems**: RAM, ROM, Register files
**Data Routing**: Multiplexers, Demultiplexers, Encoders, Decoders
**CPU Components**: Program Counter, Instruction Register, Control Unit
**Advanced**: Assembly Program Loader, Pixel Screen displays

## Educational Framework

### Template Categories
1. **Logic Fundamentals & Basic Gates**: Introduction to digital logic
2. **Combining & Derived Gates**: Complex gate combinations
3. **Combinational Circuits**: Adders, multiplexers, encoders
4. **Memory & Sequential Logic**: Flip-flops, latches, state machines
5. **Registers, Counters & Memory**: Storage and counting circuits
6. **Output and Visualization**: Display systems and debugging tools
7. **CPU Components & Architecture**: Processor design and instruction execution

### Featured Educational Circuits
- **AND Gate Security System**: Basic logic gate introduction
- **4-Bit Binary Counter**: Sequential logic and visual dynamics
- **3-Bit Binary Adder**: Complex combinational logic
- **Register Data Transfer System**: Computer architecture basics
- **8-Bit ALU System**: CPU core component demonstration
- **Sequential Instruction Executor**: Complete CPU instruction cycle

## Simulation Technology

### Event-Driven Simulator
- **Real-time Processing**: Handles clock signals and timing-dependent components
- **Bus Contention Resolution**: Manages multiple drivers on shared connections
- **Component State Management**: Maintains flip-flop, counter, and memory states
- **Performance Optimization**: Efficient event scheduling and propagation

### Component Evaluation
Each component type has specialized evaluation logic:
- **Combinational Logic**: Immediate output calculation based on inputs
- **Sequential Elements**: State-based evaluation with clock edge detection
- **Memory Components**: Address-based data storage and retrieval
- **Display Elements**: Visual output rendering and signal visualization

## Subscription Architecture

### Access Control System
- **ComponentPermissionService**: Maps components to required subscription levels
- **Dynamic UI Updates**: Real-time component availability based on subscription status
- **Professional Styling**: Visual indicators for restricted components
- **Upgrade Prompts**: User-friendly subscription upgrade flows

### Subscription Tiers
- **FREE**: Basic logic gates, switches, lights, text labels
- **BASIC**: Clock generators, displays, multiplexers, basic sequential logic
- **PROFESSIONAL**: ALUs, memory systems, CPU components, advanced debugging tools

## Technical Implementation

### Angular Services
- **WorkspaceService**: Circuit component and connection management
- **CircuitFileService**: Save/load circuit files with JSON serialization
- **TemplateCircuitService**: Educational template management
- **SubscriptionStateService**: User subscription state management
- **ComponentAvailabilityService**: Dynamic component access control

### Data Models
- **CircuitFile**: Complete circuit representation with metadata
- **LogicComponent**: Individual component with pins and properties
- **Connection**: Wire connections between component pins
- **TemplateCircuit**: Educational circuit with category and difficulty
- **UserSubscription**: Subscription status and feature access

### UI Components
- **GatesComponent**: Main circuit builder interface
- **TemplateBrowserComponent**: Circuit template discovery
- **OscilloscopeComponent**: Signal visualization and timing analysis
- **ComponentPalette**: Organized component library with search
- **ConnectionLayer**: Visual wire rendering and interaction

## API Integration

### Authentication Endpoints
- **Email Sign-in**: `/api/auth/email/signin`
- **Google OAuth**: `/api/auth/google/signin`
- **Apple Sign-in**: `/api/auth/apple/signin`
- **Token Refresh**: `/api/auth/refresh`

### Circuit Management
- **Save Circuit**: `/api/digisim/circuits/save`
- **Load Circuits**: `/api/digisim/circuits/list`
- **Delete Circuit**: `/api/digisim/circuits/delete`

### Template System
- **List Templates**: `/api/digisim/templates/list`
- **Featured Templates**: `/api/digisim/templates/featured`
- **Template CRUD**: Admin endpoints for template management

### Subscription Management
- **Subscription Status**: `/api/subscription/status`
- **Create Subscription**: `/api/subscription/create`
- **Cancel Subscription**: `/api/subscription/cancel`

## Development Workflow

### Build System
- **Angular CLI**: Version 20.3.7 with custom webpack configuration
- **TypeScript**: Strict type checking with comprehensive interfaces
- **SCSS Styling**: Material Design 3 with custom component themes
- **ESLint**: Code quality and consistency enforcement

### Testing Strategy
- **Unit Tests**: Karma/Jasmine for component and service testing
- **Integration Tests**: End-to-end testing for critical user flows
- **Simulation Testing**: Automated circuit behavior verification

### Deployment
- **Production Build**: Optimized bundle with tree-shaking
- **Environment Configuration**: Separate configs for development and production
- **Asset Management**: Static file serving for templates and documentation

This comprehensive documentation provides complete context for understanding and working with the DigiSim digital circuit simulation platform.