# Blossom Protocol Flow Charts

This document provides ASCII flow charts illustrating how each Blossom Upgrade Document (BUD) works in practice.

---

## BUD-01: Basic Blob Retrieval

### GET Request Flow
```
Client Request                    nginx                     Database
     |                            |                           |
     | GET /<sha256>              |                           |
     |--------------------------->|                           |
     |                            |                           |
     |                            | Check file exists         |
     |                            | in blobs/ directory       |
     |                            |                           |
     |     File Found             |                           |
     |<---------------------------|                           |
     | 200 OK + File Content      |                           |
     |                            |                           |
     |     File Not Found         |                           |
     |<---------------------------|                           |
     | 404 Not Found              |                           |
```

### HEAD Request Flow
```
Client Request              FastCGI App                 Database
     |                          |                           |
     | HEAD /<sha256>           |                           |
     |------------------------->|                           |
     |                          |                           |
     |                          | Query blob metadata       |
     |                          |-------------------------->|
     |                          |                           |
     |                          |    Blob exists            |
     |                          |<--------------------------|
     |                          | size, type, uploaded_at   |
     |                          |                           |
     | 200 OK + Headers         |                           |
     |<-------------------------|                           |
     | Content-Type: image/png  |                           |
     | Content-Length: 12345    |                           |
     |                          |                           |
     |                          |    Blob not found         |
     |                          |<--------------------------|
     |                          |                           |
     | 404 Not Found            |                           |
     |<-------------------------|                           |
```

---

## BUD-02: Blob Upload & Authentication

### Upload Without Authentication
```
Client                      FastCGI App                 File System          Database
  |                            |                           |                    |
  | PUT /upload                |                           |                    |
  |--------------------------->|                           |                    |
  | Content: <binary data>     |                           |                    |
  |                            |                           |                    |
  |                            | Calculate SHA-256         |                    |
  |                            | hash of data              |                    |
  |                            |                           |                    |
  |                            | Write to blobs/           |                    |
  |                            |-------------------------->|                    |
  |                            |                           | File saved         |
  |                            |<--------------------------|                    |
  |                            |                           |                    |
  |                            | Store metadata            |                    |
  |                            |----------------------------------------------->|
  |                            |                           |           | INSERT |
  |                            |<-----------------------------------------------|
  |                            |                           |                    |
  | 200 OK                     |                           |                    |
  |<---------------------------|                           |                    |
  | {                          |                           |                    |
  |   "url": "https://...",    |                           |                    |
  |   "sha256": "abc123...",   |                           |                    |
  |   "size": 12345,           |                           |                    |
  |   "type": "image/png",     |                           |                    |
  |   "uploaded": 1234567890   |                           |                    |
  | }                          |                           |                    |
```

### Upload With Nostr Authentication
```
Client                      FastCGI App                 Nostr Validation     File System    Database
  |                            |                           |                    |              |
  | PUT /upload                |                           |                    |              |
  |--------------------------->|                           |                    |              |
  | Authorization: Nostr <evt> |                           |                    |              |
  | Content: <binary data>     |                           |                    |              |
  |                            |                           |                    |              |
  |                            | Parse auth event          |                    |              |
  |                            |-------------------------->|                    |              |
  |                            |                           | • Verify signature |              |
  |                            |                           | • Check expiration |              |
  |                            |                           | • Validate tags    |              |
  |                            |<--------------------------|                    |              |
  |                            | Valid ✓                   |                    |              |
  |                            |                           |                    |              |
  |                            | Calculate hash            |                    |              |
  |                            |                           |                    |              |
  |                            | Compare with 'x' tag      |                    |              |
  |                            | in auth event             |                    |              |
  |                            |                           |                    |              |
  |                            | Hash matches ✓            |                    |              |
  |                            |                           |                    |              |
  |                            | Save file                 |                    |              |
  |                            |----------------------------------------------->|              |
  |                            |                           |           | Write  |              |
  |                            |<-----------------------------------------------|              |
  |                            |                           |                    |              |
  |                            | Store metadata            |                    |              |
  |                            |-------------------------------------------------------------->|
  |                            | (include uploader_pubkey) |                    |     | INSERT |
  |                            |<--------------------------------------------------------------|
  |                            |                           |                    |              |
  | 200 OK + Blob Descriptor   |                           |                    |              |
  |<---------------------------|                           |                    |              |
```

### Authentication Failure Flows
```
Invalid Signature:
Client --> FastCGI --> Nostr Validation --> 401 Unauthorized

Expired Event:
Client --> FastCGI --> Nostr Validation --> 401 Unauthorized

Hash Mismatch:
Client --> FastCGI --> Hash Check --> 409 Conflict
```

---

## BUD-03: User Server Lists

### Server List Publication
```
User/Client                 Nostr Relay                 Other Clients
     |                         |                           |
     | Publish kind:10063      |                           |
     | event with server tags  |                           |
     |------------------------>|                           |
     | {                       |                           |
     |   "kind": 10063,        |                           |
     |   "tags": [             |                           |
     |     ["server", "cdn1"], |                           |
     |     ["server", "cdn2"]  |                           |
     |   ]                     |                           |
     | }                       |                           |
     |                         |                           |
     |                         | Store event               |
     |                         |                           |
     |                         |                           |
     |                         | Query for user's          |
     |                         | server list               |
     |                         |<--------------------------|
     |                         |                           |
     |                         | Return server list        |
     |                         |-------------------------->|
```

### Client Blob Discovery
```
Client                    Original URL              Author's Servers
  |                          |                         |
  | GET blob from URL        |                         |
  |------------------------->|                         |
  |                          |                         |
  | 404 Not Found            |                         |
  |<-------------------------|                         |
  |                          |                         |
  | Extract SHA-256 hash     |                         |
  | from URL                 |                         |
  |                          |                         |
  | Query nostr for author's |                         |
  | server list (kind:10063) |                         |
  |                          |                         |
  | Try each server in order |                         |
  |--------------------------------------------------->|
  |                          |                         |
  | GET /<sha256>            |                         |
  |                          |                         |
  | 200 OK + File Content    |                         |
  |<---------------------------------------------------|
```

---

## BUD-04: Blob Mirroring

### Mirror Request Flow
```
Client                    Server B                  Server A                Database
  |                         |                         |                       |
  | PUT /mirror             |                         |                       |
  |------------------------>|                         |                       |
  | {                       |                         |                       |
  |   "url": "https://      |                         |                       |
  |    serverA/abc123..."   |                         |                       |
  | }                       |                         |                       |
  | Authorization: <event>  |                         |                       |
  |                         |                         |                       |
  |                         | Validate auth event     |                       |
  |                         | (check x tag matches)   |                       |
  |                         |                         |                       |
  |                         | Download from URL       |                       |
  |                         |------------------------>|                       |
  |                         |                         |                       |
  |                         | Stream blob content     |                       |
  |                         |<------------------------|                       |
  |                         |                         |                       |
  |                         | Calculate SHA-256       |                       |
  |                         | during download         |                       |
  |                         |                         |                       |
  |                         | Verify hash matches     |                       |
  |                         | x tag in auth event     |                       |
  |                         |                         |                       |
  |                         | Save blob locally       |                       |
  |                         |                         |                       |
  |                         | Store metadata          |                       |
  |                         |------------------------------------------------>|
  |                         |                         |           | INSERT    |
  |                         |<------------------------------------------------|
  |                         |                         |                       |
  | 200 OK                  |                         |                       |
  |<------------------------|                         |                       |
  | Blob Descriptor         |                         |                       |
```

---

## BUD-05: Media Optimization

### Media Processing Flow
```
Client                    Media Server              Optimization Engine     File System
  |                         |                         |                       |
  | PUT /media              |                         |                       |
  |------------------------>|                         |                       |
  | Content: <raw image>    |                         |                       |
  | Content-Type: image/png |                         |                       |
  | Authorization: <event>  |                         |                       |
  |                         |                         |                       |
  |                         | Validate auth           |                       |
  |                         | (type="media")          |                       |
  |                         |                         |                       |
  |                         | Process media           |                       |
  |                         |------------------------>|                       |
  |                         |                         | • Resize/compress     |
  |                         |                         | • Format conversion   |
  |                         |                         | • Quality optimization|
  |                         |<------------------------| Optimized media       |
  |                         |                         |                       |
  |                         | Calculate new hash      |                       |
  |                         |                         |                       |
  |                         | Save optimized blob     |                       |
  |                         |------------------------------------------------>|
  |                         |                         |           | Write     |
  |                         |<------------------------------------------------|
  |                         |                         |                       |
  | 200 OK                  |                         |                       |
  |<------------------------|                         |                       |
  | {                       |                         |                       |
  |   "url": "new_hash...", |                         |                       |
  |   "sha256": "def456...",|                         |                       |
  |   "size": 8765,         |                         |                       |
  |   "type": "image/webp"  |                         |                       |
  | }                       |                         |                       |
```

---

## BUD-06: Upload Requirements

### Upload Requirement Check
```
Client                    FastCGI App               Configuration
  |                         |                         |
  | HEAD /upload            |                         |
  |------------------------>|                         |
  | Authorization: <event>  |                         |
  | (optional)              |                         |
  |                         |                         |
  |                         | Check server config     |
  |                         |------------------------>|
  |                         |                         | • Max file size
  |                         |                         | • Auth required?
  |                         |                         | • Allowed types
  |                         |<------------------------| • Rate limits
  |                         |                         |
  |                         | Validate auth if        |
  |                         | provided                |
  |                         |                         |
  | 200 OK                  |                         |
  |<------------------------|                         |
  | X-Upload-Size-Limit:    |                         |
  |   10485760              |                         |
  | X-Upload-Auth-Required: |                         |
  |   true                  |                         |
  | X-Upload-Types:         |                         |
  |   image/*,video/*       |                         |
```

### Upload Policy Enforcement
```
Client                    FastCGI App               Policy Check
  |                         |                         |
  | PUT /upload             |                         |
  |------------------------>|                         |
  | Content-Length: 50MB    |                         |
  |                         |                         |
  |                         | Check against limits    |
  |                         |------------------------>|
  |                         |                         | Size: 50MB > 10MB ✗
  |                         |<------------------------| REJECT
  |                         |                         |
  | 413 Payload Too Large   |                         |
  |<------------------------|                         |
  | {                       |                         |
  |   "error": "File too    |                         |
  |   large. Max: 10MB"     |                         |
  | }                       |                         |
```

---

## BUD-07: Paid Upload/Download

### Payment Required Flow
```
Client                    Paid Server               Payment Provider
  |                         |                         |
  | PUT /upload             |                         |
  |------------------------>|                         |
  |                         |                         |
  |                         | Check payment required  |
  |                         |                         |
  | 402 Payment Required    |                         |
  |<------------------------|                         |
  | X-Lightning: lnbc...    |                         |
  | X-Cashu: creq...        |                         |
  |                         |                         |
  | User pays invoice       |                         |
  |-------------------------------------------------->|
  |                         |                         |
  | PUT /upload (retry)     |                         |
  |------------------------>|                         |
  | X-Lightning: <preimage> |                         |
  |                         |                         |
  |                         | Verify payment proof    |
  |                         |------------------------>|
  |                         |                         | Valid ✓
  |                         |<------------------------|
  |                         |                         |
  |                         | Process upload          |
  |                         |                         |
  | 200 OK + Blob Desc      |                         |
  |<------------------------|                         |
```

### Payment Methods
```
Lightning Payment:
Client --> Server --> Lightning Node --> Payment Verification --> Upload Success

Cashu Payment:
Client --> Server --> Cashu Mint --> Token Validation --> Upload Success
```

---

## BUD-08: NIP-94 File Metadata

### Enhanced Blob Descriptor
```
Client Upload             FastCGI App               Metadata Generation      Response
     |                       |                         |                       |
     | PUT /upload           |                         |                       |
     |---------------------> |                         |                       |
     |                       |                         |                       |
     |                       | Process file            |                       |
     |                       |                         |                       |
     |                       | Generate NIP-94 tags    |                       |
     |                       |------------------------>|                       |
     |                       |                         | • ["url", "..."]      |
     |                       |                         | • ["m", "image/png"]  |
     |                       |                         | • ["x", "hash..."]    |
     |                       |                         | • ["size", "12345"]   |
     |                       |                         | • ["magnet", "..."]   |
     |                       |<------------------------| NIP-94 tags           |
     |                       |                         |                       |
     |                       | Build response          |                       |
     |                       |------------------------------------------------>|
     | Enhanced Response     |                         |                       |
     |<--------------------- |                         |                       |
     | {                     |                         |                       |
     |   "url": "...",       |                         |                       |
     |   "sha256": "...",    |                         |                       |
     |   "nip94": [          |                         |                       |
     |     ["url", "..."],   |                         |                       |
     |     ["m", "..."],     |                         |                       |
     |     ["x", "..."]      |                         |                       |
     |   ]                   |                         |                       |
     | }                     |                         |                       |
```

---

## BUD-09: Blob Reporting

### Content Moderation Flow
```
Client/User               FastCGI App               Moderation System        Action
     |                       |                         |                       |
     | PUT /report           |                         |                       |
     |---------------------> |                         |                       |
     | NIP-56 report event   |                         |                       |
     | {                     |                         |                       |
     |   "kind": 1984,       |                         |                       |
     |   "tags": [           |                         |                       |
     |     ["x", "hash..."]  |                         |                       |
     |   ],                  |                         |                       |
     |   "content": "spam"   |                         |                       |
     | }                     |                         |                       |
     |                       |                         |                       |
     |                       | Validate report         |                       |
     |                       |                         |                       |
     |                       | Store report            |                       |
     |                       |------------------------>|                       |
     |                       |                         | • Log report          |
     |                       |                         | • Check reporter      |
     |                       |                         | • Queue for review    |
     |                       |<------------------------| Stored                |
     |                       |                         |                       |
     | 200 OK                |                         |                       |
     |<--------------------- |                         |                       |
     |                       |                         |                       |
     |                       |                         | Manual Review         |
     |                       |                         |---------------------> |
     |                       |                         |                       | Remove blob
     |                       |                         |                       | Block hash
     |                       |                         |                       | Ban user
```

### Automated Moderation
```
Trusted Reporter Report --> Immediate Action --> Blob Removed

Multiple Reports --> Temporary Hide --> Manual Review --> Final Decision
```

---

## Complete Ginxsom Architecture Flow

### Nginx + FastCGI Integration
```
Internet                nginx               FastCGI App           Database         File System
    |                     |                     |                    |                  |
    | GET /<sha256>       |                     |                    |                  |
    |-------------------->|                     |                    |                  |
    |                     | Direct file serve   |                    |                  |
    |                     |----------------------------------------->|                  |
    |                     |                     |                    |        blobs/    |
    | File Content        |<-----------------------------------------|        <hash>    |
    |<--------------------|                     |                    |                  |
    |                     |                     |                    |                  |
    | HEAD /<sha256>      |                     |                    |                  |
    |-------------------->|                     |                    |                  |
    |                     | Forward to FastCGI  |                    |                  |
    |                     |-------------------->|                    |                  |
    |                     |                     | Query metadata     |                  |
    |                     |                     |------------------->|                  |
    |                     |                     |                    | SELECT           |
    |                     |                     |<-------------------|                  |
    |                     | Headers response    |                    |                  |
    |                     |<--------------------|                    |                  |
    | Metadata Headers    |                     |                    |                  |
    |<--------------------|                     |                    |                  |
    |                     |                     |                    |                  |
    | PUT /upload         |                     |                    |                  |
    |-------------------->|                     |                    |                  |
    |                     | Forward to FastCGI  |                    |                  |
    |                     |-------------------->|                    |                  |
    |                     |                     | Process upload     |                  |
    |                     |                     |                    |                  |
    |                     |                     | Store metadata     |                  |
    |                     |                     |------------------->|                  |
    |                     |                     |                    | INSERT           |
    |                     |                     |<-------------------|                  |
    |                     |                     |                    |                  |
    |                     |                     | Save file          |                  |
    |                     |                     |-------------------------------------->|
    |                     |                     |                    |        Write     |
    |                     |                     |<--------------------------------------|
    |                     | JSON response       |                    |                  |
    |                     |<--------------------|                    |                  |
    | Blob Descriptor     |                     |                    |                  |
    |<--------------------|                     |                    |                  |
```