updated docs

docs/architecture/04-media-storage.md

@@ -0,0 +1,150 @@
+# Media Storage Architecture
+
+## Overview
+
+MPR separates media into **input** and **output** paths, each independently configurable. File paths are stored **relative to their respective root** to ensure portability between local development and cloud deployments (AWS S3, etc.).
+
+## Storage Strategy
+
+### Input / Output Separation
+
+| Path | Env Var | Purpose |
+|------|---------|---------|
+| `MEDIA_IN` | `/app/media/in` | Source media files to process |
+| `MEDIA_OUT` | `/app/media/out` | Transcoded/trimmed output files |
+
+These can point to different locations or even different servers/buckets in production.
+
+### File Path Storage
+- **Database**: Stores only the relative path (e.g., `videos/sample.mp4`)
+- **Input Root**: Configurable via `MEDIA_IN` env var
+- **Output Root**: Configurable via `MEDIA_OUT` env var
+- **Serving**: Base URL configurable via `MEDIA_BASE_URL` env var
+
+### Why Relative Paths?
+1. **Portability**: Same database works locally and in cloud
+2. **Flexibility**: Easy to switch between storage backends
+3. **Simplicity**: No need to update paths when migrating
+
+## Local Development
+
+### Configuration
+```bash
+MEDIA_IN=/app/media/in
+MEDIA_OUT=/app/media/out
+```
+
+### File Structure
+```
+/app/media/
+├── in/                    # Source files
+│   ├── video1.mp4
+│   ├── video2.mp4
+│   └── subfolder/
+│       └── video3.mp4
+└── out/                   # Transcoded output
+    ├── video1_h264.mp4
+    └── video2_trimmed.mp4
+```
+
+### Database Storage
+```
+# Source assets (scanned from media/in)
+filename: video1.mp4
+file_path: video1.mp4
+
+filename: video3.mp4
+file_path: subfolder/video3.mp4
+```
+
+### URL Serving
+- Nginx serves input via `location /media/in { alias /app/media/in; }`
+- Nginx serves output via `location /media/out { alias /app/media/out; }`
+- Frontend accesses: `http://mpr.local.ar/media/in/video1.mp4`
+- Video player: `<video src="/media/in/video1.mp4" />`
+
+## AWS/Cloud Deployment
+
+### S3 Configuration
+```bash
+# Input and output can be different buckets/paths
+MEDIA_IN=s3://source-bucket/media/
+MEDIA_OUT=s3://output-bucket/transcoded/
+MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/
+```
+
+### S3 Structure
+```
+s3://source-bucket/media/
+├── video1.mp4
+└── subfolder/
+    └── video3.mp4
+
+s3://output-bucket/transcoded/
+├── video1_h264.mp4
+└── video2_trimmed.mp4
+```
+
+### Database Storage (Same!)
+```
+filename: video1.mp4
+file_path: video1.mp4
+
+filename: video3.mp4
+file_path: subfolder/video3.mp4
+```
+
+## API Endpoints
+
+### Scan Media Folder
+```http
+POST /api/assets/scan
+```
+
+**Behavior:**
+1. Recursively scans `MEDIA_IN` directory
+2. Finds all video/audio files (mp4, mkv, avi, mov, mp3, wav, etc.)
+3. Stores paths **relative to MEDIA_IN**
+4. Skips already-registered files (by filename)
+5. Returns summary: `{ found, registered, skipped, files }`
+
+### Create Job
+```http
+POST /api/jobs/
+Content-Type: application/json
+
+{
+  "source_asset_id": "uuid",
+  "preset_id": "uuid",
+  "trim_start": 10.0,
+  "trim_end": 30.0
+}
+```
+
+**Behavior:**
+- Server sets `output_path` using `MEDIA_OUT` + generated filename
+- Output goes to the output directory, not alongside source files
+
+## Migration Guide
+
+### Moving from Local to S3
+
+1. **Upload source files to S3:**
+   ```bash
+   aws s3 sync /app/media/in/ s3://source-bucket/media/
+   aws s3 sync /app/media/out/ s3://output-bucket/transcoded/
+   ```
+
+2. **Update environment variables:**
+   ```bash
+   MEDIA_IN=s3://source-bucket/media/
+   MEDIA_OUT=s3://output-bucket/transcoded/
+   MEDIA_BASE_URL=https://source-bucket.s3.amazonaws.com/media/
+   ```
+
+3. **Database paths remain unchanged** (already relative)
+
+## Supported File Types
+
+**Video:** `.mp4`, `.mkv`, `.avi`, `.mov`, `.webm`, `.flv`, `.wmv`, `.m4v`
+**Audio:** `.mp3`, `.wav`, `.flac`, `.aac`, `.ogg`, `.m4a`