managarten/services/mana-media/CLAUDE.md

# mana-media - Unified Media Platform

Central media handling service for all Mana applications with content-addressable storage (CAS) and automatic deduplication.

**Stack:** Hono + Bun (migrated from NestJS 2026-03-28)

## Overview

mana-media provides:
- **Content-Addressable Storage** - SHA-256 based deduplication across all apps
- **Upload API** - File uploads with automatic deduplication
- **Processing** - Thumbnails, WebP conversion, resizing (via BullMQ)
- **Delivery** - Optimized file serving, on-the-fly transforms

**Port:** 3015 (production)

## Quick Start

```bash
# Start dependencies (Redis + MinIO + PostgreSQL)
pnpm docker:up

# Create database
PGPASSWORD=devpassword psql -h localhost -U mana -d postgres -c "CREATE DATABASE mana_media;"

# Install dependencies
cd services/mana-media/apps/api
pnpm install

# Push schema
pnpm db:push

# Start development server
pnpm dev
```

Service runs on `http://localhost:3015`

## API Endpoints

### Upload
```bash
# Upload file
curl -X POST http://localhost:3015/api/v1/media/upload \
  -F "file=@image.jpg" \
  -F "app=chat" \
  -F "userId=user123"

# Response
{
  "id": "abc123",
  "status": "processing",
  "hash": "sha256...",
  "urls": {
    "original": "http://localhost:3015/api/v1/media/abc123/file",
    "thumbnail": "http://localhost:3015/api/v1/media/abc123/file/thumb"
  }
}
```

### Get Media
```bash
# Get metadata
GET /api/v1/media/:id

# Get by content hash (check if file exists)
GET /api/v1/media/hash/:sha256hash

# Get original file
GET /api/v1/media/:id/file

# Get thumbnail
GET /api/v1/media/:id/file/thumb

# Get medium variant
GET /api/v1/media/:id/file/medium

# On-the-fly transform
GET /api/v1/media/:id/transform?w=400&h=300&fit=cover&format=webp
```

### List & Delete
```bash
# List media (filter by app/user)
GET /api/v1/media?app=chat&userId=user123&limit=50

# Delete
DELETE /api/v1/media/:id
```

## Client Library

```typescript
import { MediaClient } from '@mana/media-client';

const media = new MediaClient('http://localhost:3050');

// Upload
const result = await media.upload(file, { app: 'chat' });

// Wait for processing
const ready = await media.waitForReady(result.id);

// Get URLs
const thumbUrl = media.getThumbnailUrl(result.id);
const customUrl = media.getTransformUrl(result.id, {
  width: 400,
  format: 'webp'
});
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      mana-media (Port 3015)                  │
├─────────────────────────────────────────────────────────────┤
│  Upload Module   │  File uploads, dedup                     │
│  Process Module  │  Sharp thumbnail generation (BullMQ)     │
│  Storage Module  │  MinIO S3 abstraction                    │
│  Delivery Module │  File serving + on-the-fly transforms    │
│  Database Module │  PostgreSQL + Drizzle ORM                │
└─────────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
    ┌─────────┐   ┌─────────┐   ┌────────────┐
    │  Redis  │   │  MinIO  │   │ PostgreSQL │
    │ BullMQ  │   │ Storage │   │   mana_media │
    └─────────┘   └─────────┘   └────────────┘
```

## Database Schema

### media (Content-Addressable Storage)
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| content_hash | TEXT | SHA-256 hash (unique) |
| original_name | TEXT | Original filename |
| mime_type | TEXT | MIME type |
| size | BIGINT | File size in bytes |
| original_key | TEXT | S3 storage key |
| status | TEXT | uploading/processing/ready/failed |
| thumbnail_key | TEXT | Thumbnail S3 key |
| width/height | INT | Image dimensions |

### media_references (User ownership)
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| media_id | UUID | FK to media |
| user_id | UUID | Owner user ID |
| app | TEXT | Source app (food, contacts, etc.) |
| source_url | TEXT | Original source URL |

## Processing Pipeline

| File Type | Generated Variants |
|-----------|-------------------|
| Images    | thumb (200x200), medium (800x800), large (1920x1920) |
| Videos    | (planned) thumbnail, HLS streaming |
| Documents | (planned) thumbnail, text extraction |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| PORT | 3015 | API port |
| DATABASE_URL | - | PostgreSQL connection string |
| REDIS_HOST | localhost | Redis host |
| REDIS_PORT | 6379 | Redis port |
| REDIS_PASSWORD | - | Redis password (optional) |
| S3_ENDPOINT | localhost | MinIO/S3 endpoint |
| S3_PORT | 9000 | MinIO/S3 port |
| S3_USE_SSL | false | Use HTTPS for S3 |
| S3_ACCESS_KEY | minioadmin | S3 access key |
| S3_SECRET_KEY | minioadmin | S3 secret key |
| S3_BUCKET | mana-media | Storage bucket |
| S3_PUBLIC_URL | - | Public URL for media |
| PUBLIC_URL | http://localhost:3015/api/v1 | Public API URL |

## Development

```bash
# Run with watch mode (Bun)
pnpm dev

# Type check
pnpm type-check

# Database commands
cd apps/api
pnpm db:push    # Push schema to database
pnpm db:studio  # Open Drizzle Studio
```

## Storage Layout

```
mana-media bucket/
├── originals/           # Original uploads
│   └── 2026/02/01/
│       └── {id}.{ext}
├── processed/           # Generated variants
│   └── {id}/
│       ├── thumb.webp
│       ├── medium.webp
│       └── large.webp
└── cache/               # Transform cache
    └── {id}_{params}.webp
```

## Roadmap

- [x] v0.1: Basic upload + thumbnails
- [x] v0.2: PostgreSQL persistence with Drizzle ORM
- [x] v0.3: Content-addressable storage with SHA-256 deduplication
- [ ] v0.5: Video thumbnails (FFmpeg)
- [ ] v0.6: Chunked upload for large files
- [ ] v0.7: OCR for documents
- [ ] v0.8: Vector search (Qdrant)
- [ ] v1.0: Full production ready