keys-for-all/docs/SYSTEM_ARCHITECTURE.md

Keys for All - System Architecture

Overview

Keys for All is a distributed licensing system that enables community-driven software access through shareable license keys. The system consists of three main components that work together:

1. keys-api - Backend API server for key management
2. keys-web-components - Web interface for key distribution and community features
3. ios-integration - Swift package for iOS app integration

Directory Structure

keys-for-all/
├── docs/                      # System documentation
│   ├── SYSTEM_ARCHITECTURE.md # This file
│   ├── API_SPECIFICATION.md   # API endpoint documentation
│   ├── DATABASE_SCHEMA.md     # Database design
│   ├── SECURITY_MODEL.md      # Security and encryption details
│   └── DEPLOYMENT_GUIDE.md    # How to deploy the system
│
├── keys-api/                  # Backend API Server
│   ├── package.json          # Node.js dependencies
│   ├── src/
│   │   ├── server.js         # Express server entry point
│   │   ├── config/           # Configuration management
│   │   ├── controllers/      # Request handlers
│   │   ├── models/           # Database models
│   │   ├── routes/           # API routes
│   │   ├── middleware/       # Auth, validation, etc.
│   │   ├── services/         # Business logic
│   │   └── utils/            # Helper functions
│   ├── tests/
│   └── README.md
│
├── keys-web-components/       # Web Frontend
│   ├── package.json          # React/Vue dependencies
│   ├── public/               # Static assets
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   ├── pages/            # Page components
│   │   ├── services/         # API client
│   │   ├── store/            # State management
│   │   └── styles/           # CSS/styling
│   ├── tests/
│   └── README.md
│
└── ios-integration/          # Swift Package
    ├── Package.swift         # SPM manifest
    ├── Sources/KeysForAll/   # Swift source code
    ├── Tests/                # Unit tests
    └── README.md

Component Interactions

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│   iOS Apps      │────▶│   Keys API       │◀────│  Web Portal     │
│ (VoiceUwu etc) │     │   (Backend)      │     │  (Community)    │
│                 │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         ▲                       │                         ▲
         │                       ▼                         │
         │              ┌──────────────────┐               │
         │              │                  │               │
         └──────────────│    Database      │───────────────┘
                        │  (PostgreSQL)    │
                        │                  │
                        └──────────────────┘

Data Flow

1. Key Purchase Flow

iOS App ──▶ StoreKit ──▶ Keys API ──▶ Generate Keys ──▶ Store in DB ──▶ Return to App

2. Key Validation Flow

iOS App ──▶ Keys API ──▶ Validate Key ──▶ Check DB ──▶ Return Status

3. Key Sharing Flow

iOS App ──▶ Generate Share Code ──▶ Keys API ──▶ Create Transfer ──▶ Other User Claims

4. Community Pool Flow

Donor ──▶ Web Portal ──▶ Keys API ──▶ Add to Pool ──▶ Available for Request

Key Components

Keys API (Backend)

• Purpose: Central authority for key management
• Technology: Node.js, Express, PostgreSQL
• Responsibilities:
  • Key generation and validation
  • Purchase verification
  • Usage tracking
  • Community pool management
  • Analytics and reporting

Web Components (Frontend)

• Purpose: Community interface for key management
• Technology: React/Vue, TailwindCSS
• Features:
  • Community pool interface
  • Key request system
  • Donation tracking
  • Public statistics
  • Admin dashboard

iOS Integration (Swift Package)

• Purpose: Easy integration for iOS apps
• Technology: Swift, SwiftUI
• Features:
  • Feature gating
  • License UI
  • Local caching
  • Offline support
  • StoreKit integration

Security Model

Key Generation

• Keys use cryptographically secure random generation
• Format: XXXX-XXXX-XXXX-XXXX (Base32 encoded)
• Each key includes a checksum for validation

API Authentication

• Apps use API keys for authentication
• Rate limiting per app/IP
• HTTPS required for all communications

Data Privacy

• No personal data stored with keys
• Anonymous usage statistics only
• GDPR compliant design

Deployment Architecture

Production Environment

┌─────────────────┐
│   CloudFlare    │ ─── CDN & DDoS Protection
└────────┬────────┘
         │
┌────────▼────────┐
│  Load Balancer  │ ─── AWS ALB
└────────┬────────┘
         │
┌────────▼────────┐     ┌──────────────┐
│   API Servers   │────▶│   Database   │
│   (Auto-scale)  │     │   (RDS)      │
└─────────────────┘     └──────────────┘
         │
┌────────▼────────┐
│   Redis Cache   │ ─── Session & Rate Limiting
└─────────────────┘

Development Environment

• Docker Compose for local development
• SQLite for local database
• Mock StoreKit for testing

Integration Points

For App Developers

1. Add Swift package dependency
2. Implement FeatureProvider protocol
3. Initialize KeysForAllManager
4. Use feature checking in UI

For Community Managers

1. Access web portal
2. Monitor key pool status
3. Review requests
4. Generate bulk keys for events

For System Administrators

1. Deploy API server
2. Configure database
3. Set up monitoring
4. Manage API keys

Next Steps

1. Implement keys-api backend
2. Build keys-web-components frontend
3. Add StoreKit integration to iOS package
4. Create deployment scripts
5. Write comprehensive tests
6. Set up CI/CD pipeline