# Fire-OS Data Flow Architecture

## Overview

This document describes how data flows through the Fire-OS platform, from user input to storage and back to the user interface.

## High-Level Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Browser/UI    │────▶│   Next.js API   │────▶│   PostgreSQL    │
│   (React/TLS)   │◀────│   (Server)      │◀────│   (Supabase)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               │ External APIs
                               ▼
                    ┌─────────────────────────────┐
                    │ - Stripe (Payments)         │
                    │ - Resend (Email)            │
                    │ - Anthropic (AI Processing) │
                    │ - Twilio/Telnyx (Voice)     │
                    └─────────────────────────────┘
```

## Data Flow Stages

### 1. User Input (Browser)

All user interactions start in the browser:

- Forms validated client-side for UX
- No sensitive data stored in localStorage/sessionStorage
- Cookies are httpOnly, secure, and SameSite=Strict
- All requests sent over HTTPS

### 2. API Layer (Next.js Server)

The Next.js API layer processes all requests:

```
Request → Auth Middleware → Validation → Business Logic → Database → Response
```

**Security controls at this layer:**
- Session validation via NextAuth.js
- Tenant isolation check (user has access to project)
- Input validation using Zod schemas
- Rate limiting (see API Security doc)
- Request logging for audit trail

### 3. Database (Supabase PostgreSQL)

Data storage and retrieval:

**Write operations:**
1. Validate data shape (Zod)
2. Check user permissions
3. Transform data (Drizzle ORM)
4. Insert/update with tenant isolation
5. Return result

**Read operations:**
1. Validate query parameters
2. Apply tenant filter (WHERE project_id = ?)
3. Execute query with indexes
4. Transform for response
5. Return data

### 4. External API Integrations

Fire-OS integrates with several external services:

| Service | Data Sent | Purpose |
|---------|-----------|---------|
| Stripe | Payment info, customer email | Subscription billing |
| Resend | Recipient email, content | Email campaigns |
| Anthropic | Conversation context | AI agent processing |
| Twilio/Telnyx | Phone numbers, audio | Voice calls |

**Security for external APIs:**
- API keys stored encrypted in database
- Keys never exposed to client-side
- Webhook signatures verified
- Minimal data sent (need-to-know basis)

## Sensitive Data Categories

### Category 1: Authentication Data
- Passwords (hashed, never transmitted in logs)
- Session tokens
- API keys

**Handling:** Never logged, encrypted at rest, hashed where applicable

### Category 2: Personal Information
- Email addresses
- Phone numbers
- Names

**Handling:** Encrypted in transit, access logged, retention policies applied

### Category 3: Business Data
- Prospect information
- Customer records
- Revenue data

**Handling:** Tenant-isolated, backed up, audit logged

### Category 4: Integration Credentials
- Third-party API keys
- OAuth tokens
- Webhook secrets

**Handling:** Encrypted at rest, decrypted only when needed, rotatable

## Data Retention

| Data Type | Retention Period | Deletion Method |
|-----------|-----------------|-----------------|
| User sessions | 24 hours inactive | Automatic expiration |
| Audit logs | 90 days | Automatic purge |
| Customer data | Until deletion requested | Soft delete → hard delete after 30 days |
| Backups | 30 days | Automatic rotation |
| Analytics | 1 year | Anonymization after retention |

## Data Export

Users can request their data at any time:
- All personal data exported in JSON format
- Delivered via secure download link
- Link expires after 24 hours

## Data Deletion

On account deletion:
1. Immediate soft delete of all records
2. 30-day grace period for recovery
3. Permanent deletion after grace period
4. Backups purged on next rotation cycle

## Network Boundaries

```
Internet
    │
    ▼
┌───────────────────────────────────────────┐
│ Vercel Edge Network (CDN, DDoS Protection)│
└───────────────────────────────────────────┘
    │
    ▼
┌───────────────────────────────────────────┐
│ Next.js Serverless Functions              │
│ - Auth middleware                         │
│ - API routes                              │
└───────────────────────────────────────────┘
    │
    ▼
┌───────────────────────────────────────────┐
│ Supabase                                  │
│ - PostgreSQL (private network)            │
│ - Connection pooling                      │
│ - TLS encryption                          │
└───────────────────────────────────────────┘
```

## Audit Logging

Every significant action is logged:

```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "userId": "user_123",
  "projectId": "proj_456",
  "action": "customer.create",
  "resourceId": "cust_789",
  "ip": "192.168.1.1",
  "userAgent": "Mozilla/5.0..."
}
```

Logs are:
- Immutable (append-only)
- Retained for 90 days
- Available for export upon request
- Used for security monitoring