# DigiSim Frontend Architecture

> Angular-based frontend architecture for DigiSim's digital circuit simulation platform, featuring component-based design, reactive state management, and Material Design 3 UI system.

## Application Structure

### Core Architecture
- **Framework**: Angular 20+ with TypeScript
- **Build System**: Angular CLI with custom webpack configuration
- **State Management**: RxJS observables with service-based architecture
- **UI Framework**: Angular Material with Material Design 3 theming
- **Styling**: SCSS with component-scoped styles

### Module Organization
- **Core Module**: Singleton services and global configuration
- **Shared Module**: Reusable components and utilities
- **Feature Modules**: Lazy-loaded modules for major features
- **Pages Module**: Static pages and documentation

## Key Services

### WorkspaceService
Central service for circuit management:
- **Component Management**: Add, remove, and configure circuit components
- **Connection Handling**: Wire routing and pin connections
- **State Persistence**: Save and restore workspace state
- **Export Functions**: PNG export and circuit file generation

### SimulatorProviderService
Simulation engine facade:
- **Engine Selection**: Choose between event-driven and iterative simulators
- **Component Evaluation**: Coordinate component state updates
- **Real-time Processing**: Handle clock signals and timing
- **Performance Monitoring**: Track simulation performance metrics

### ComponentPermissionService
Subscription-based access control:
- **Permission Mapping**: Map components to subscription tiers
- **Dynamic Access**: Real-time permission updates
- **Visual Indicators**: Component availability styling
- **Upgrade Prompts**: User-friendly subscription upgrade flows

### TemplateCircuitService
Educational template management:
- **Template Loading**: Fetch and parse educational circuits
- **Category Filtering**: Filter by educational topics
- **Featured Circuits**: Curated educational progression
- **Template Browser**: Search and discovery interface

### Animation System
Educational animation playback features:
- **Playback Controls**: Play, pause, stop, step forward/backward
- **Speed Adjustment**: Variable playback speed (0.5x to 2x)
- **Audio Narration**: Synchronized voice-over with animations
- **Subtitles**: Text descriptions for each animation step
- **Camera Effects**: Automatic focus and zoom on components

### Circuit Conversion Tools
- **Export Animations**: Convert circuit designs to shareable animation files
- **Import Animations**: Load educational animations from files

## Component Architecture

### Circuit Builder (GatesComponent)
Main workspace interface:
- **Component Palette**: Organized library of logic components
- **Drag-and-Drop**: Intuitive component placement
- **Connection System**: Visual wire routing
- **Property Panels**: Component configuration interfaces

### Template Browser
Educational circuit discovery:
- **Material 3 Design**: Modern card-based interface
- **Advanced Filtering**: Category, difficulty, and text search
- **Responsive Layout**: Mobile and desktop optimization
- **One-click Loading**: Instant template integration

### Oscilloscope Component
Signal visualization:
- **Multi-channel Display**: Up to 8 signal traces
- **Real-time Updates**: Live signal monitoring
- **Zoom Controls**: Time base adjustment
- **Export Capabilities**: Waveform image export

## State Management

### Reactive Architecture
- **Observable Streams**: RxJS-based data flow
- **Service Communication**: Inter-service messaging
- **Component Updates**: Reactive UI updates
- **Error Handling**: Comprehensive error propagation

### Data Models
- **CircuitFile**: Complete circuit representation
- **LogicComponent**: Individual component with properties
- **Connection**: Wire connections between pins
- **UserSubscription**: Subscription state and permissions

## UI/UX Design

### Material Design 3
- **Color System**: Dynamic color theming
- **Typography**: Roboto font family with proper scaling
- **Elevation**: Consistent shadow and depth system
- **Component Library**: Material 3 component implementations

### Responsive Design
- **Mobile First**: Progressive enhancement approach
- **Breakpoint System**: Consistent responsive behavior
- **Touch Optimization**: Mobile-friendly interactions
- **Accessibility**: ARIA compliance and keyboard navigation

### Professional Styling
- **Component Indicators**: Visual feedback for restricted components
- **Loading States**: Professional loading animations
- **Error Handling**: User-friendly error messages
- **Success Feedback**: Confirmation and status indicators

## Performance Optimization

### Bundle Optimization
- **Lazy Loading**: Feature modules loaded on demand
- **Tree Shaking**: Eliminate unused code
- **Code Splitting**: Optimize bundle sizes
- **Asset Optimization**: Image and resource compression

### Runtime Performance
- **Change Detection**: OnPush strategy where appropriate
- **Virtual Scrolling**: Efficient large list rendering
- **Memory Management**: Proper subscription cleanup
- **Caching Strategies**: Service-level data caching

## Development Workflow

### Code Quality
- **ESLint**: Comprehensive linting rules
- **TypeScript**: Strict type checking
- **Component Testing**: Unit tests with Jasmine/Karma
- **E2E Testing**: Integration test coverage

### Build Process
- **Development Server**: Hot reload and debugging
- **Production Build**: Optimized deployment artifacts
- **Environment Configuration**: Separate dev/prod settings
- **Asset Pipeline**: Automated asset processing