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:

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

Admin System File Upload:

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

Request Audio Processing:

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

Temporary File Upload:

User uploads temp file to temp/ scope
S3 lifecycle policy auto-deletes after 24 hours
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:

Code commit to GitHub
Automated tests (unit, integration, E2E) - Epic 2
Build Docker images for Frontoffice, Backoffice, and Backend
Push images to container registry (ECR)
Deploy to staging environment
Automated smoke tests - Epic 2
Manual approval gate
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

Architecture Overview​

Technology Stack Summary​

High-Level Architecture​

Deployment Model​

Single EC2 Instance Setup​

Component Details​

1. Client Layer​

Frontoffice Container (Next.js)​

Backoffice Container (Next.js)​

2. Application Layer​

Backend Container (C# / ASP.NET Core)​

3. Services Layer​

Database: SQL Server (Amazon RDS)​

File Storage: AWS S3 (with CloudFront CDN)​

External Service: ElevenLabs (Text-to-Speech)​

4. External References​

QR Code Generator Link (API Documentation)​

External API: QR Tiger (QR Code Generation)​

Data Flow​

Generation Flow (End-to-End)​

S3 Pre-signed Upload Approach​

How Pre-signed URLs Work​

Pre-signed Upload Flow​

Pre-signed URL API Endpoints​

Get Pre-signed Upload URL​

Uploading File to S3​

S3 Key Structure​

Security Considerations​

Common Use Cases​

Security Architecture​

Authentication & Authorization​

Data Protection​

Compliance​

Scalability & Performance​

Scaling Strategy​

Performance Considerations​

Monitoring & Observability​

Monitoring Strategy​

Disaster Recovery​

Backup Strategy​

Recovery Approach​

Cost Optimization​

MVP Cost Structure​

Cost Reduction Strategies​

Deployment Architecture​

Environments​

CI/CD Pipeline​

Potential Future Improvements​

Related Documentation​

Architecture Overview

Technology Stack Summary

High-Level Architecture

Deployment Model

Single EC2 Instance Setup

Component Details

1. Client Layer

Frontoffice Container (Next.js)

Backoffice Container (Next.js)

2. Application Layer

Backend Container (C# / ASP.NET Core)

3. Services Layer

Database: SQL Server (Amazon RDS)

File Storage: AWS S3 (with CloudFront CDN)

External Service: ElevenLabs (Text-to-Speech)

4. External References

QR Code Generator Link (API Documentation)

External API: QR Tiger (QR Code Generation)

Data Flow

Generation Flow (End-to-End)

S3 Pre-signed Upload Approach

How Pre-signed URLs Work

Pre-signed Upload Flow

Pre-signed URL API Endpoints

Get Pre-signed Upload URL

Uploading File to S3

S3 Key Structure

Security Considerations

Common Use Cases

Security Architecture

Authentication & Authorization

Data Protection

Compliance

Scalability & Performance

Scaling Strategy

Performance Considerations

Monitoring & Observability

Monitoring Strategy

Disaster Recovery

Backup Strategy

Recovery Approach

Cost Optimization

MVP Cost Structure

Cost Reduction Strategies

Deployment Architecture

Environments

CI/CD Pipeline

Potential Future Improvements

Related Documentation