update docs

docs/media-storage.md

@@ -0,0 +1,209 @@
+# Media Storage Architecture
+
+## Overview
+
+MPR stores media file paths **relative to the media root** to ensure portability between local development and cloud deployments (AWS S3, etc.).
+
+## Storage Strategy
+
+### File Path Storage
+- **Database**: Stores only the relative path (e.g., `videos/sample.mp4`)
+- **Media Root**: Configurable base directory via `MEDIA_ROOT` 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_ROOT=/app/media
+```
+
+### File Structure
+```
+/app/media/
+├── video1.mp4
+├── video2.mp4
+└── subfolder/
+    └── video3.mp4
+```
+
+### Database Storage
+```
+filename: video1.mp4
+file_path: video1.mp4
+
+filename: video3.mp4
+file_path: subfolder/video3.mp4
+```
+
+### URL Serving
+- Nginx serves via `location /media { alias /app/media; }`
+- Frontend accesses: `http://mpr.local.ar/media/video1.mp4`
+- Video player: `<video src="/media/video1.mp4" />`
+
+## AWS/Cloud Deployment
+
+### S3 Configuration
+```bash
+MEDIA_ROOT=s3://my-bucket/media/
+MEDIA_BASE_URL=https://my-bucket.s3.amazonaws.com/media/
+```
+
+### S3 Structure
+```
+s3://my-bucket/media/
+├── video1.mp4
+├── video2.mp4
+└── subfolder/
+    └── video3.mp4
+```
+
+### Database Storage (Same!)
+```
+filename: video1.mp4
+file_path: video1.mp4
+
+filename: video3.mp4
+file_path: subfolder/video3.mp4
+```
+
+### URL Serving
+- Frontend prepends `MEDIA_BASE_URL`: `https://my-bucket.s3.amazonaws.com/media/video1.mp4`
+- Video player: `<video src="https://my-bucket.s3.amazonaws.com/media/video1.mp4" />`
+
+## API Endpoints
+
+### Scan Media Folder
+```http
+POST /api/assets/scan
+```
+
+**Behavior:**
+1. Recursively scans `MEDIA_ROOT` directory
+2. Finds all video/audio files (mp4, mkv, avi, mov, mp3, wav, etc.)
+3. Stores paths **relative to MEDIA_ROOT**
+4. Skips already-registered files (by filename)
+5. Returns summary: `{ found, registered, skipped, files }`
+
+**Example:**
+```bash
+curl -X POST http://mpr.local.ar/api/assets/scan
+```
+
+```json
+{
+  "found": 15,
+  "registered": 12,
+  "skipped": 3,
+  "files": ["video1.mp4", "video2.mp4", ...]
+}
+```
+
+### Create Asset
+```http
+POST /api/assets/
+Content-Type: application/json
+
+{
+  "file_path": "/app/media/video.mp4",
+  "filename": "video.mp4"
+}
+```
+
+**Behavior:**
+- Validates file exists
+- Converts absolute path to relative (relative to `MEDIA_ROOT`)
+- Stores relative path in database
+
+## Migration Guide
+
+### Moving from Local to S3
+
+1. **Upload files to S3:**
+   ```bash
+   aws s3 sync /app/media/ s3://my-bucket/media/
+   ```
+
+2. **Update environment variables:**
+   ```bash
+   MEDIA_ROOT=s3://my-bucket/media/
+   MEDIA_BASE_URL=https://my-bucket.s3.amazonaws.com/media/
+   ```
+
+3. **Database paths remain unchanged** (already relative)
+
+4. **Update frontend** to use `MEDIA_BASE_URL` from config
+
+### Moving from S3 to Local
+
+1. **Download files from S3:**
+   ```bash
+   aws s3 sync s3://my-bucket/media/ /app/media/
+   ```
+
+2. **Update environment variables:**
+   ```bash
+   MEDIA_ROOT=/app/media
+   # Remove MEDIA_BASE_URL or set to /media/
+   ```
+
+3. **Database paths remain unchanged** (already relative)
+
+## Implementation Details
+
+### Backend (FastAPI)
+
+**File path normalization** (`api/routes/assets.py`):
+```python
+import os
+from pathlib import Path
+
+media_root = Path(os.environ.get("MEDIA_ROOT", "/app/media"))
+
+# Convert absolute to relative
+file_path = Path("/app/media/subfolder/video.mp4")
+rel_path = str(file_path.relative_to(media_root))
+# Result: "subfolder/video.mp4"
+```
+
+### Frontend (React)
+
+**Current implementation:**
+```typescript
+<video src={`/media/${asset.file_path}`} />
+```
+
+**Future cloud implementation:**
+```typescript
+const MEDIA_BASE_URL = import.meta.env.VITE_MEDIA_BASE_URL || '/media/';
+<video src={`${MEDIA_BASE_URL}${asset.file_path}`} />
+```
+
+## Supported File Types
+
+**Video formats:**
+- `.mp4`, `.mkv`, `.avi`, `.mov`, `.webm`, `.flv`, `.wmv`, `.m4v`
+
+**Audio formats:**
+- `.mp3`, `.wav`, `.flac`, `.aac`, `.ogg`, `.m4a`
+
+## Best Practices
+
+1. **Always use relative paths** when storing file references
+2. **Use environment variables** for media root and base URL
+3. **Validate file existence** before creating assets
+4. **Scan periodically** to discover new files
+5. **Use presigned URLs** for S3 private buckets (TODO: implement)
+
+## Future Enhancements
+
+- [ ] S3 presigned URL generation for private buckets
+- [ ] CloudFront CDN integration
+- [ ] Multi-region S3 replication
+- [ ] Automatic metadata extraction on upload
+- [ ] Thumbnail generation and storage