System Architecture

Architecture Overview

The MicDots platform is built on a cloud-native architecture leveraging AWS services and external APIs for voice generation and QR code creation.

Technology Stack Summary

Layer	Technology	Purpose
Frontoffice	Next.js (React + TypeScript) - Docker	Landing page, client area
Backoffice	Next.js (React + TypeScript) - Docker	Admin operations, management
Backend	C# + ASP.NET Core 9.0 - Docker	REST API, Business Logic
Hosting	Single EC2 Instance (all containers)	Application hosting
Database	SQL Server (Amazon RDS)	Relational data storage
File Storage	AWS S3	Audio files and QR images
CDN	CloudFront (enhances S3)	Global content delivery (optional)
Voice API	ElevenLabs (via RageAgainstThePixel SDK) (On Hold)	Text-to-speech conversion
QR API	QR Tiger	QR code generation
ORM	Entity Framework Core	Database access layer
Authentication	JWT Tokens	Secure API authentication
Testing	xUnit/NUnit (Backend), Jest/Cypress (Frontend)	Unit & E2E tests (Epic 2 - Low Priority)

---

High-Level Architecture

---

Deployment Model

Single EC2 Instance Setup

Frontoffice, Backoffice, and Backend run as Docker containers on the same EC2 instance for the MVP phase.

Key Characteristics:

• Docker Compose manages all three containers
• Shared internal network for communication
• Frontoffice serves landing page and client area
• Backoffice serves admin operations interface
• Simple deployment and management
• Lower infrastructure costs
• Easy to scale to separate instances later

---

Component Details

1. Client Layer

Frontoffice Container (Next.js)

Purpose: Public-facing web interface for end-users

Technology Stack:

• Framework: Next.js (React)
• Language: TypeScript
• Styling: TODO - Ask Cristian about Tailwind + shadcn
• Deployment: Docker container

Responsibilities:

• Landing page rendering
• Client registration and authentication
• Client area dashboard
• Voice generation interface (text input)
• Audio player controls
• QR code display and download
• Client profile management
• Server-side rendering (SSR)
• Static site generation (SSG)

Key Pages:

• Landing page (homepage)
• Client registration/login
• Client dashboard
• Voice generation form
• Profile settings

---

Backoffice Container (Next.js)

Purpose: Administrative interface for platform management

Technology Stack:

• Framework: Next.js (React)
• Language: TypeScript
• Styling: TODO - Ask Cristian about Tailwind + shadcn
• Deployment: Docker container

Responsibilities:

• Admin authentication and authorization
• Client management (view, edit, suspend clients)
• Request management (view all generations)
• Analytics and reporting dashboards
• System configuration
• User quota management
• Email notification management
• Server-side rendering (SSR)

Key Pages:

• Admin login
• Client list and management
• Request list and details
• Analytics dashboard
• System settings

S3 Upload Strategy:

The Backoffice uses pre-signed URLs for direct file uploads to S3:

• User requests pre-signed upload URL from Backend API
• Backend generates temporary S3 upload URL with expiration
• User uploads file directly to S3 using pre-signed URL
• No file data passes through Backend, reducing server load
• Secure, time-limited access to S3 bucket

See S3 Pre-signed Upload Approach for detailed flow and API documentation.

---

2. Application Layer

Backend Container (C# / ASP.NET Core)

Purpose: Core application server hosting all business logic

Technology Stack:

• Language: C# with ASP.NET Core 9.0 Framewoork
• Deployment: Docker container
• Authentication: JWT tokens
• ElevenLabs Integration: RageAgainstThePixel SDK
• ORM: Entity Framework Core

Responsibilities:

• REST API endpoints
• Text validation and processing
• User quota management
• Integration with external services (ElevenLabs, QR Tiger)
• Database operations
• Authentication and authorization

---

3. Services Layer

Database: SQL Server (Amazon RDS)

Purpose: Persistent data storage for all platform data

Technology:

• Amazon RDS for SQL Server
• Multi-AZ deployment for production (optional)
• Automated backups and point-in-time recovery

Data Models:

• Users: Authentication, token balance
• Generations: Text input, audio URLs, QR code URLs, metadata
• Analytics Events: Scans, plays, user engagement (Stage 2)

---

File Storage: AWS S3 (with CloudFront CDN)

Purpose: Secure storage and global delivery for audio files and QR code images

Storage Features:

• Private bucket with signed URLs for access
• Server-side encryption (AES-256)
• Versioning enabled for file protection
• Lifecycle policies for cost optimization
• Automated cleanup for temporary files

Content Delivery Enhancement (CloudFront):

• Optional CDN layer that enhances S3 delivery
• Provides global content distribution with low latency
• Caches audio files and QR images at edge locations
• Reduces S3 bandwidth costs
• Transparent to users - they simply get faster access
• Can be enabled/disabled without changing application logic

Stored Content:

• Generated audio files (MP3 format)
• QR code images (PNG format)
• Temporary processing files

---

External Service: ElevenLabs (Text-to-Speech)

Purpose: AI-powered text-to-speech conversion service

Integration:

• Backend uses RageAgainstThePixel SDK (C# library)
• Converts text input to high-quality audio
• Multiple voice models available
• API key authentication

Features:

• Natural-sounding AI voices
• Multiple voice options (male, female, various accents)
• High-quality audio output (MP3 format)
• Adjustable voice parameters

---

4. External References

QR Code Generator Link (API Documentation)

Purpose: External reference link for QR Tiger API documentation

Role in Architecture:

• Not a service we use directly in production flow
• Reference documentation for developers
• Shows available QR Tiger API capabilities

Use Case:

• Developer reference during integration
• Testing and exploration of QR Tiger features
• API documentation access

---

External API: QR Tiger (QR Code Generation)

Purpose: Dynamic QR code generation with analytics capabilities

Integration:

• Backend calls QR Tiger API
• Generates QR codes linked to audio URLs
• API key authentication
• API Documentation

Features:

• Dynamic QR codes (editable URLs)
• Custom branding support
• Multiple formats (PNG, SVG)
• Built-in analytics (Stage 2)
• High resolution output
• Error correction

---

Data Flow

Generation Flow (End-to-End)

---

S3 Pre-signed Upload Approach

The MicDots platform uses AWS S3 pre-signed URLs for secure, direct file uploads from the Backoffice to S3 storage. This approach offloads file transfer from the Backend API, improving performance and reducing server bandwidth costs.

How Pre-signed URLs Work

Pre-signed URLs are temporary, secure URLs that grant time-limited access to upload files directly to S3 without exposing AWS credentials.

Key Benefits:

• Direct Upload: Files go directly from client to S3, bypassing Backend server
• Security: Time-limited access (typically 5-15 minutes)
• Performance: Reduces Backend server load and bandwidth usage
• Scalability: S3 handles file storage and scaling automatically
• Cost Effective: Lower data transfer costs

---

Pre-signed Upload Flow

---

Pre-signed URL API Endpoints

Get Pre-signed Upload URL

Endpoint: GET /api/v1/[scope]/uploads/presigned-url

Description: Request a pre-signed URL for direct S3 upload. The [scope] parameter determines the S3 folder structure and access permissions.

Supported Scopes:

• admin - Admin uploads (backoffice files, system assets) - Admin role required
• audio - Audio files (text-to-speech outputs) - All authenticated users
• qr-codes - QR code images - All authenticated users
• temp - Temporary files (auto-deleted after 24 hours) - All authenticated users

Authorization: Authenticated user required (scope-based permissions apply)

Headers:

Authorization: Bearer ACCESS_TOKEN

Query Parameters:

Parameter	Type	Required	Description
fileName	string	Yes	Original file name (used for S3 key generation)
contentType	string	Yes	MIME type (e.g., audio/mpeg, image/png)
expiresIn	number	No	URL expiration in seconds (default: 900 / 15 min)

Example Request:

curl -X GET "http://localhost:5000/api/v1/audio/uploads/presigned-url?fileName=audio.mp3&contentType=audio/mpeg" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response: 200 OK

{
  "success": true,
  "data": {
    "presignedUrl": "https://micdots-storage.s3.amazonaws.com/audio/2024/01/550e8400-e29b-41d4-a716-446655440000.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "fileKey": "audio/2024/01/550e8400-e29b-41d4-a716-446655440000.mp3",
    "bucketName": "micdots-storage",
    "expiresIn": 900,
    "expiresAt": "2024-01-22T15:45:00Z",
    "uploadId": "upload-uuid-here",
    "contentType": "audio/mpeg"
  }
}

Response Fields:

• presignedUrl (string) - Temporary S3 upload URL (valid for expiresIn seconds)
• fileKey (string) - S3 object key for the uploaded file
• bucketName (string) - S3 bucket name
• expiresIn (number) - Seconds until URL expires
• expiresAt (string) - ISO 8601 timestamp when URL expires
• uploadId (string) - Unique identifier for tracking upload
• contentType (string) - MIME type for the upload

Error Responses:

401 Unauthorized (Missing/Invalid Token):

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required."
  }
}

403 Forbidden (Insufficient Permissions):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to upload to this scope. The 'admin' scope requires administrator role."
  }
}

400 Bad Request (Invalid Parameters):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters.",
    "details": {
      "fileName": ["File name is required"],
      "contentType": ["Content type must be a valid MIME type"]
    }
  }
}

---

Uploading File to S3

Once you receive the pre-signed URL, upload the file directly to S3 using HTTP PUT:

Example Upload with cURL:

curl -X PUT "PRESIGNED_URL_FROM_API" \
  -H "Content-Type: audio/mpeg" \
  --upload-file ./audio.mp3

---

S3 Key Structure

Files are organized in S3 using a hierarchical structure:

s3://micdots-storage/
├── admin/
│   ├── 2024/
│   │   ├── 01/
│   │   │   ├── uuid-1.mp3
│   │   │   └── uuid-2.pdf
│   │   └── 02/
│   └── 2025/
├── audio/
│   ├── 2024/
│   │   ├── 01/
│   │   │   ├── uuid-1.mp3
│   │   │   └── uuid-2.mp3
│   │   └── 02/
│   └── 2025/
├── qr-codes/
│   ├── 2024/
│   │   └── 01/
│   │       ├── uuid-1.png
│   │       └── uuid-2.png
│   └── 2025/
└── temp/
    └── 2024/
        └── 01/
            └── uuid-temp.dat

Key Format: {scope}/{year}/{month}/{uuid}.{extension}

Examples:

• admin/2024/01/550e8400-e29b-41d4-a716-446655440000.mp3
• audio/2024/01/7c9e6679-7425-40de-944b-e07fc1f90ae7.mp3
• qr-codes/2024/01/a3bb189e-8bf9-3888-9912-ace4e6543002.png

---

Security Considerations

Time-Limited Access:

• Pre-signed URLs expire after a set duration (default: 15 minutes)
• Expired URLs return 403 Forbidden errors
• Request new URLs if uploads take longer than expiration time

Content Type Validation:

• Backend validates MIME types before generating URLs
• Allowed types: audio/mpeg, audio/wav, image/png, image/jpeg, application/pdf
• S3 enforces content type during upload

File Size Limits:

• Maximum file size: 100 MB (configurable)
• S3 rejects uploads exceeding size limits
• Consider using multipart uploads for files > 100 MB

Access Control:

• Authenticated users can request pre-signed upload URLs for allowed scopes
• admin scope requires administrator role
• audio, qr-codes, and temp scopes available to all authenticated users
• Each URL is unique and single-use (best practice)
• S3 bucket has private ACL (no public access)

Monitoring:

• All pre-signed URL requests are logged
• Failed uploads are tracked in CloudWatch
• Alerts for suspicious upload patterns

---

Common Use Cases

User Audio Upload:

1. User requests pre-signed URL for audio.mp3 (scope: audio)
2. Backend returns URL with key audio/2024/01/uuid.mp3
3. User uploads file directly to S3
4. File is available at S3 URL for playback

Admin System File Upload:

1. Admin requests pre-signed URL for system asset (scope: admin)
2. Backend validates admin role and returns URL
3. Admin uploads file directly to S3
4. File stored in admin-only scope

Request Audio Processing:

1. User/Admin uploads audio via pre-signed URL
2. Backend confirms upload completion
3. Backend updates request record with S3 file key
4. QR code is generated with S3 audio URL

Temporary File Upload:

1. User uploads temp file to temp/ scope
2. S3 lifecycle policy auto-deletes after 24 hours
3. No manual cleanup required

---

Security Architecture

Authentication & Authorization

• JWT-based authentication
• API key management via AWS Secrets Manager
• Regular key rotation

Data Protection

• In Transit: TLS 1.3, HTTPS only
• At Rest: RDS encryption, S3 server-side encryption
• Rate Limiting: Per user and per IP limits
• DDoS Protection: AWS WAF

Compliance

• Minimal PII collection
• GDPR considerations
• Data retention policies

---

Scalability & Performance

Scaling Strategy

• MVP: Single EC2 instance with Docker containers
• Future: Auto-scaling EC2 with load balancer, read replicas

Performance Considerations

• CloudFront CDN for global content delivery
• S3 for scalable file storage
• Efficient caching strategies
• Database indexing and query optimization

---

Monitoring & Observability

Monitoring Strategy

• Application and access logs (CloudWatch)
• Performance metrics tracking
• Error rate monitoring
• External API health checks
• Storage and cost monitoring
• Automated alerting for critical issues

---

Disaster Recovery

Backup Strategy

• Automated daily database backups
• S3 versioning enabled
• Infrastructure as Code for configuration
• Point-in-time recovery capabilities

Recovery Approach

• Database promotion from replicas
• Application restore from container images
• Validation through automated tests (Epic 2) or manual verification (Epic 1)

---

Cost Optimization

MVP Cost Structure

• Single EC2 instance (frontend + backend containers)
• RDS for SQL Server
• S3 storage with lifecycle policies
• CloudFront (optional)
• External API costs (ElevenLabs, QR Tiger)

Cost Reduction Strategies

• Single instance deployment reduces infrastructure costs
• S3 lifecycle policies for storage optimization
• Reserved instances for production workloads
• Efficient caching to reduce API calls
• CDN to reduce bandwidth costs

---

Deployment Architecture

Environments

Development:

• Single small EC2 instance
• Docker Compose with all three containers (Frontoffice, Backoffice, Backend)
• Small RDS instance
• Test API keys

Staging:

• Single medium EC2 instance
• Docker Compose with all three containers (Frontoffice, Backoffice, Backend)
• Sanitized copy of production database
• Integration testing environment

Production (MVP):

• Single medium/large EC2 instance
• Docker Compose with all three containers (Frontoffice, Backoffice, Backend)
• Multi-AZ RDS deployment
• S3 with versioning
• CloudFront CDN (optional)
• Production API keys

Production (Future - Scalable):

• Auto-scaling EC2 instances
• Load balancer
• Multi-AZ RDS with read replicas
• Separate container deployments with independent scaling

CI/CD Pipeline

Pipeline Steps:

1. Code commit to GitHub
2. Automated tests (unit, integration, E2E) - Epic 2
3. Build Docker images for Frontoffice, Backoffice, and Backend
4. Push images to container registry (ECR)
5. Deploy to staging environment
6. Automated smoke tests - Epic 2
7. Manual approval gate
8. Deploy to production (blue-green strategy)

Note: Epic 1 will focus on manual testing and deployment. Automated testing infrastructure is scheduled for Epic 2 as a low priority item.

---

Potential Future Improvements

Very Distant Future

The items below are NOT part of any current phase or roadmap. These are theoretical architectural improvements that may be considered in the very distant future, well beyond MVP completion. The current focus is exclusively on Epic 1 core functionality.

Possible Enhancements (Very Distant Future):

• Microservices: Separate services for voice, QR
• Message Queue: SQS for async job processing
• Global Expansion: Multi-region deployment
• GraphQL API: Alternative to REST for complex queries
• Blockchain Integration: NFT-based QR codes

---

Related Documentation

• Project Overview
• MVP 1 Overview
• MVP Priorities
• Epic 1: Core Features