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