# DigiSim API Reference

> Complete API documentation for DigiSim's backend services, including authentication, circuit management, template systems, and subscription handling using protobuf-based communication.

## Authentication APIs

### Email Authentication
- **Endpoint**: `/api/auth/email/signin`
- **Method**: POST
- **Request**: `EmailSignInRequest` with email and password
- **Response**: `AuthResponse` with JWT tokens and user subscription info
- **Usage**: Standard email/password authentication

### Google OAuth
- **Endpoint**: `/api/auth/google/signin`
- **Method**: POST
- **Request**: `GoogleSignInRequest` with OAuth token
- **Response**: `AuthResponse` with JWT and subscription data
- **Usage**: Google OAuth 2.0 integration

### Apple Sign-In
- **Endpoint**: `/api/auth/apple/signin`
- **Method**: POST
- **Request**: `AppleSignInRequest` with Apple identity token
- **Response**: `AuthResponse` with authentication data
- **Usage**: Apple ID authentication

### Token Refresh
- **Endpoint**: `/api/auth/refresh`
- **Method**: POST
- **Request**: `RefreshTokenRequest` with refresh token
- **Response**: New JWT access token
- **Usage**: Maintain authentication session

## Circuit Management APIs

### Save Circuit
- **Endpoint**: `/api/digisim/circuits/save`
- **Method**: POST
- **Request**: `SaveCircuitRequest` with circuit data and metadata
- **Response**: `SaveCircuitResponse` with circuit ID and status
- **Features**: Automatic AI summary generation, version tracking

### List User Circuits
- **Endpoint**: `/api/digisim/circuits/list`
- **Method**: GET
- **Parameters**: Optional pagination and filtering
- **Response**: `ListCircuitsResponse` with circuit metadata array
- **Data**: Circuit name, creation date, modification date, AI summary

### Delete Circuit
- **Endpoint**: `/api/digisim/circuits/delete`
- **Method**: DELETE
- **Request**: Circuit ID parameter
- **Response**: Deletion confirmation
- **Security**: User ownership validation

### Load Circuit
- **Endpoint**: `/api/digisim/circuits/load/{id}`
- **Method**: GET
- **Response**: Complete circuit data with components and connections
- **Format**: JSON serialized CircuitFile format

## Template Circuit APIs

### List Templates
- **Endpoint**: `/api/digisim/templates/list`
- **Method**: GET
- **Parameters**: 
  - `categoryValue`: TemplateCategory enum value
  - `difficultyValue`: TemplateDifficulty enum value
  - `page`: Pagination offset
  - `limit`: Results per page
- **Response**: Array of TemplateCircuit objects with metadata

### Featured Templates
- **Endpoint**: `/api/digisim/templates/featured`
- **Method**: GET
- **Response**: Curated list of educational template circuits
- **Content**: 6 featured circuits spanning beginner to advanced levels

### Template Categories
- **LOGIC_FUNDAMENTALS**: Basic gates and truth tables
- **COMBINING_AND_DERIVED_GATES**: Complex gate combinations
- **COMBINATIONAL_CIRCUITS**: Adders, multiplexers, encoders
- **MEMORY_AND_SEQUENTIAL_LOGIC**: Flip-flops, latches, state machines
- **REGISTERS_COUNTERS_AND_MEMORY**: Storage and counting circuits
- **OUTPUT_AND_VISUALIZATION**: Display systems and debugging
- **CPU_COMPONENTS_AND_ARCHITECTURE**: Processor design and instruction execution

### Template Difficulties
- **BEGINNER**: Introduction to digital logic concepts
- **INTERMEDIATE**: Complex circuits requiring multiple concepts
- **ADVANCED**: CPU architecture and system-level design

## Animation Circuit Features

DigiSim provides step-by-step animated circuit demonstrations for educational purposes:

### Animation Capabilities
- **Step-by-Step Playback**: Watch circuits being built component by component
- **Audio Narration**: Synchronized voice-over explanations
- **Camera Controls**: Automatic focus and zoom on relevant components
- **Subtitles**: Text descriptions for each animation step
- **Playback Controls**: Play, pause, speed adjustment, step forward/backward

### Animation Step Types
- **Add Component**: Place logic gates, inputs, and outputs on canvas
- **Add Connection**: Draw wires between component pins
- **Toggle State**: Change input switch states during demonstration
- **Highlight**: Visual emphasis on specific components
- **Camera Focus**: Pan and zoom to specific circuit areas

### AI-Powered Refinement
- Automatic subtitle generation for animation steps
- Optimized timing and pacing for educational content
- Smart camera positioning for better visibility

## Admin Template APIs

### Create Template
- **Endpoint**: `/api/digisim/templates/create`
- **Method**: POST
- **Request**: `CreateTemplateCircuitRequest` with circuit data and metadata
- **Access**: Admin users only
- **Validation**: Category, difficulty, and circuit data validation

### Update Template
- **Endpoint**: `/api/digisim/templates/update/{id}`
- **Method**: PUT
- **Request**: `UpdateTemplateCircuitRequest` with modified data
- **Access**: Admin users only
- **Features**: Version control and change tracking

### Delete Template
- **Endpoint**: `/api/digisim/templates/delete/{id}`
- **Method**: DELETE
- **Access**: Admin users only
- **Validation**: Dependency checking before deletion

## Subscription Management APIs

### Get Subscription Status
- **Endpoint**: `/api/subscription/status`
- **Method**: GET
- **Response**: Current subscription details and feature access
- **Data**: Plan type, billing cycle, expiration date, available components

### Create Subscription
- **Endpoint**: `/api/subscription/create`
- **Method**: POST
- **Request**: `CreateSubscriptionRequest` with plan details
- **Integration**: PayPal subscription creation
- **Response**: Subscription ID and payment URL

### Cancel Subscription
- **Endpoint**: `/api/subscription/cancel`
- **Method**: POST
- **Request**: `CancelSubscriptionRequest` with reason and preferences
- **Options**: Immediate or end-of-cycle cancellation
- **Response**: Cancellation confirmation and effective date

### Update Billing
- **Endpoint**: `/api/subscription/update-billing`
- **Method**: PUT
- **Request**: Billing cycle change (monthly/yearly)
- **Integration**: PayPal subscription modification
- **Response**: Updated subscription details

## Data Models

### AuthResponse
```protobuf
message AuthResponse {
  string accessToken = 1;
  string refreshToken = 2;
  UserSubscriptionInfo userSubscription = 3;
  AvailableActionsInfo availableActions = 4;
}
```

### UserSubscriptionInfo
```protobuf
message UserSubscriptionInfo {
  SubscriptionPlanType planType = 1;
  string planName = 2;
  bool isActive = 3;
  FeatureAccess featureAccess = 4;
  CircuitQuota circuitQuota = 5;
  string status = 6;
  google.protobuf.Timestamp expiresAt = 7;
  string billingCycle = 8;
}
```

### TemplateCircuit
```protobuf
message TemplateCircuit {
  string id = 1;
  string name = 2;
  string description = 3;
  TemplateCategory category = 4;
  TemplateDifficulty difficulty = 5;
  string circuitData = 6;
  string imageUrl = 7;
  int32 categoryOrder = 8;
  int32 difficultyOrder = 9;
}
```

### CircuitFile
```protobuf
message DigiSimSavedCircuitProto {
  string id = 1;
  string name = 2;
  string description = 3;
  string circuitData = 4;
  google.protobuf.Timestamp createdAt = 5;
  google.protobuf.Timestamp lastModifiedAt = 6;
  string aiSummary = 7;
}
```

## Error Handling

### Standard Error Response
```protobuf
message ErrorResponse {
  int32 errorCode = 1;
  string message = 2;
  repeated string details = 3;
}
```

### Common Error Codes
- **1001**: Invalid authentication credentials
- **1002**: Expired or invalid JWT token
- **2001**: Circuit not found or access denied
- **2002**: Invalid circuit data format
- **3001**: Template not found
- **3002**: Insufficient permissions for template operation
- **4001**: Subscription not found or inactive
- **4002**: Payment processing error
- **5001**: Internal server error
- **7001**: Protobuf parsing error

## Request/Response Format

### Content Types
- **Request**: `application/x-protobuf` for binary protobuf data
- **Response**: `application/x-protobuf` with proper protobuf serialization
- **Headers**: `Authorization: Bearer {jwt_token}` for authenticated requests

### Pagination
```protobuf
message PaginationRequest {
  int32 page = 1;
  int32 limit = 2;
}

message PaginationResponse {
  int32 totalCount = 1;
  int32 currentPage = 2;
  int32 totalPages = 3;
  bool hasNext = 4;
  bool hasPrevious = 5;
}
```

## Rate Limiting

### API Limits
- **Authentication**: 10 requests per minute per IP
- **Circuit Operations**: 100 requests per minute per user
- **Template Browsing**: 200 requests per minute per user
- **Subscription**: 20 requests per minute per user

### Headers
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in current window
- `X-RateLimit-Reset`: Time when rate limit resets

## Security

### Authentication
- **JWT Tokens**: RS256 signed tokens with user claims
- **Refresh Tokens**: Secure token rotation for session management
- **HTTPS Only**: All API endpoints require HTTPS in production

### Authorization
- **User Circuits**: Users can only access their own circuits
- **Admin Templates**: Template CRUD requires admin role
- **Subscription Data**: Users can only access their own subscription info

### Data Validation
- **Input Sanitization**: All user inputs validated and sanitized
- **Circuit Data**: JSON schema validation for circuit files
- **File Size Limits**: Maximum circuit file size enforcement