Add FastAPI backend and React frontend subprojects
Backend: - FastAPI app with 17 REST endpoints covering dashboard, monitoring, media index, file browser, and jobs - Reuses existing clients/domain/services unchanged - pydantic-settings config, dependency injection, CORS setup - Auto-generated OpenAPI docs at /docs Frontend: - Vite + React + TypeScript SPA - @tanstack/react-query for data fetching with polling - ag-grid-react for media table and file browser - recharts for monitoring charts - Tailwind CSS styling - 4 pages: Dashboard, Monitoring, Media, File Browser - Typed API client matching all backend endpoints Also: - docs/MIGRATION_PLAN.md with full architecture plan - Updated .gitignore for both subprojects - Streamlit app preserved for now (can coexist)
This commit is contained in:
@@ -0,0 +1,241 @@
|
||||
# Migration Plan: Streamlit → FastAPI + React
|
||||
|
||||
## Overview
|
||||
|
||||
Split the current Streamlit monolith into:
|
||||
|
||||
- **Backend:** FastAPI (Python) serving a REST API
|
||||
- **Frontend:** React SPA (TypeScript) consuming that API
|
||||
|
||||
The existing `clients/`, `domain/`, `services/`, `jobs.py`, `utils.py`, and `config.py` are already UI-independent and transfer directly to the FastAPI backend with minimal changes.
|
||||
|
||||
---
|
||||
|
||||
## Current Architecture
|
||||
|
||||
```
|
||||
src/media_library_viewer/
|
||||
├── app.py # Streamlit orchestration + caching (DELETE)
|
||||
├── config.py # Env/dotenv config
|
||||
├── jobs.py # SSH job templates
|
||||
├── utils.py # Formatting helpers
|
||||
├── clients/
|
||||
│ ├── jellyfin.py # Jellyfin HTTP client
|
||||
│ ├── resources.py # Remote resource collector
|
||||
│ └── ssh.py # SSH command execution
|
||||
├── domain/
|
||||
│ └── media.py # Media normalization
|
||||
├── services/
|
||||
│ └── media_index.py # SQLite media index
|
||||
└── ui/ # Streamlit rendering (DELETE)
|
||||
├── dashboard.py
|
||||
├── file_browser.py
|
||||
├── media.py
|
||||
└── preview.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Target Architecture
|
||||
|
||||
```
|
||||
repo/
|
||||
├── backend/
|
||||
│ ├── main.py # FastAPI app + CORS + lifespan
|
||||
│ ├── config.py # pydantic-settings based config
|
||||
│ ├── dependencies.py # DI for SSH/Jellyfin clients
|
||||
│ ├── routers/
|
||||
│ │ ├── dashboard.py # /api/dashboard/*
|
||||
│ │ ├── monitoring.py # /api/monitoring/*
|
||||
│ │ ├── media.py # /api/media/*
|
||||
│ │ ├── files.py # /api/files/*
|
||||
│ │ └── jobs.py # /api/jobs/*
|
||||
│ ├── clients/ # Copied unchanged
|
||||
│ │ ├── jellyfin.py
|
||||
│ │ ├── resources.py
|
||||
│ │ └── ssh.py
|
||||
│ ├── domain/ # Copied unchanged
|
||||
│ │ └── media.py
|
||||
│ ├── services/ # Copied unchanged
|
||||
│ │ └── media_index.py
|
||||
│ ├── jobs.py # Copied unchanged
|
||||
│ ├── utils.py # Copied unchanged
|
||||
│ └── pyproject.toml
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── package.json
|
||||
│ ├── vite.config.ts
|
||||
│ ├── tsconfig.json
|
||||
│ └── src/
|
||||
│ ├── main.tsx
|
||||
│ ├── App.tsx
|
||||
│ ├── api/
|
||||
│ │ └── client.ts # Typed fetch wrappers
|
||||
│ ├── hooks/
|
||||
│ │ ├── useDashboard.ts
|
||||
│ │ ├── useMonitoring.ts
|
||||
│ │ ├── useMedia.ts
|
||||
│ │ └── useFiles.ts
|
||||
│ ├── pages/
|
||||
│ │ ├── Dashboard.tsx
|
||||
│ │ ├── Monitoring.tsx
|
||||
│ │ ├── Media.tsx
|
||||
│ │ └── FileBrowser.tsx
|
||||
│ ├── components/
|
||||
│ │ ├── NowPlaying.tsx
|
||||
│ │ ├── MetricCard.tsx
|
||||
│ │ ├── LibraryOverview.tsx
|
||||
│ │ ├── MonitoringCharts.tsx
|
||||
│ │ ├── MediaTable.tsx
|
||||
│ │ ├── FileListing.tsx
|
||||
│ │ └── FfprobePreview.tsx
|
||||
│ └── types/
|
||||
│ └── index.ts
|
||||
│
|
||||
├── docker-compose.yml # Optional unified deployment
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FastAPI Endpoints
|
||||
|
||||
| Endpoint | Method | Source | Description |
|
||||
| ------------------------------- | ------ | ---------------------------------------- | -------------------------------- |
|
||||
| `/api/dashboard/counts` | GET | `jellyfin.media_counts()` | Movie/series/episode totals |
|
||||
| `/api/dashboard/libraries` | GET | `jellyfin.library_item_counts()` | Per-library breakdown |
|
||||
| `/api/dashboard/now-playing` | GET | `jellyfin.active_sessions()` | Active sessions + transcode info |
|
||||
| `/api/monitoring/status` | GET | `resources.resource_collector_status()` | Collector running? |
|
||||
| `/api/monitoring/metrics` | GET | `resources.read_resource_metrics()` | Last-hour JSONL samples |
|
||||
| `/api/monitoring/disk` | GET | `resources.disk_space()` | df for media root |
|
||||
| `/api/monitoring/start` | POST | `resources.start_resource_collector()` | Start collector |
|
||||
| `/api/monitoring/stop` | POST | `resources.stop_resource_collector()` | Stop collector |
|
||||
| `/api/monitoring/restart` | POST | `resources.restart_resource_collector()` | Restart collector |
|
||||
| `/api/media/status` | GET | `MediaIndex.status()` | Index exists/count/age |
|
||||
| `/api/media/build` | POST | `build_media_index()` | Rebuild index |
|
||||
| `/api/media/query` | GET | `MediaIndex.query()` | Filtered/sorted/paged query |
|
||||
| `/api/files/list?path=` | GET | `ssh.list_dir()` | Directory listing |
|
||||
| `/api/files/ffprobe?path=` | GET | `ssh.ffprobe_json()` | ffprobe JSON |
|
||||
| `/api/files/stat?path=` | GET | `ssh.stat_path()` | stat output |
|
||||
| `/api/files/resolve-path?path=` | GET | `resolve_remote_media_path()` | Jellyfin→SSH path mapping |
|
||||
| `/api/jobs/templates` | GET | `JOB_TEMPLATES` | Available job list |
|
||||
| `/api/jobs/run` | POST | `run_job()` | Execute a job |
|
||||
|
||||
---
|
||||
|
||||
## React Frontend
|
||||
|
||||
### Tech Stack
|
||||
|
||||
- **Vite** + React 18+ + TypeScript
|
||||
- **@tanstack/react-query** — data fetching with polling
|
||||
- **ag-grid-react** — media table and file browser (same grid lib)
|
||||
- **recharts** — monitoring line charts
|
||||
- **react-router** — page navigation
|
||||
- **tailwindcss** + **shadcn/ui** — styling
|
||||
|
||||
### Page → Component Mapping
|
||||
|
||||
| Page | Components | Polling |
|
||||
| ------------ | --------------------------------------------------------- | -------------------------------- |
|
||||
| Dashboard | NowPlaying, MetricCard (server overview), LibraryOverview | 15s (now-playing), 30s (metrics) |
|
||||
| Monitoring | MonitoringCharts, MetricCard, CollectorControls | 15s |
|
||||
| Media | MediaTable (AG Grid), filter/sort/page controls | on-demand |
|
||||
| File Browser | FileListing (AG Grid), FfprobePreview, JobRunner | on-demand |
|
||||
|
||||
### Key Interactions
|
||||
|
||||
- Media row click → updates client-side file browser path state (no API call)
|
||||
- File browser directory click → fetches `/api/files/list?path=...`
|
||||
- File browser file click → fetches `/api/files/ffprobe?path=...`
|
||||
- Path input Enter → navigates directory
|
||||
- Monitoring charts → recharts line chart from `/api/monitoring/metrics`
|
||||
|
||||
---
|
||||
|
||||
## What Transfers Unchanged (~1,350 lines)
|
||||
|
||||
| File | Lines | Notes |
|
||||
| ------------------------- | ----- | ---------------------------- |
|
||||
| `clients/jellyfin.py` | 167 | Remove unused methods if any |
|
||||
| `clients/ssh.py` | 146 | No changes |
|
||||
| `clients/resources.py` | 316 | No changes |
|
||||
| `domain/media.py` | 161 | No changes |
|
||||
| `services/media_index.py` | 278 | No changes |
|
||||
| `jobs.py` | 59 | No changes |
|
||||
| `utils.py` | 227 | No changes |
|
||||
|
||||
---
|
||||
|
||||
## What Gets Deleted
|
||||
|
||||
- `src/media_library_viewer/ui/` (all Streamlit rendering)
|
||||
- `src/media_library_viewer/app.py` (Streamlit orchestration)
|
||||
- Root `app.py` (Streamlit launcher)
|
||||
- `streamlit` and `streamlit-aggrid` dependencies
|
||||
|
||||
---
|
||||
|
||||
## Migration Steps
|
||||
|
||||
### Step 1: Backend scaffold
|
||||
|
||||
- Create `backend/` with FastAPI, pydantic-settings config, DI
|
||||
- Copy `clients/`, `domain/`, `services/`, `jobs.py`, `utils.py`
|
||||
- Implement routers wrapping existing functions
|
||||
- Test with curl
|
||||
|
||||
### Step 2: Frontend scaffold
|
||||
|
||||
- Create `frontend/` with Vite + React + TypeScript
|
||||
- API client with typed wrappers
|
||||
- React Query provider + hooks
|
||||
- Router with 4 pages
|
||||
|
||||
### Step 3: Build pages (one at a time)
|
||||
|
||||
1. Dashboard (simplest — just fetches and displays)
|
||||
2. Monitoring (charts + controls)
|
||||
3. Media (AG Grid + filters)
|
||||
4. File Browser (AG Grid + ffprobe + jobs)
|
||||
|
||||
### Step 4: Validate feature parity
|
||||
|
||||
- Compare behavior side-by-side with Streamlit
|
||||
- Remove Streamlit code
|
||||
|
||||
---
|
||||
|
||||
## Effort Estimate
|
||||
|
||||
| Component | Effort |
|
||||
| ------------------------------------- | ------------- |
|
||||
| FastAPI backend | 1-2 days |
|
||||
| React scaffold + routing + API client | 0.5 day |
|
||||
| Dashboard page | 0.5 day |
|
||||
| Monitoring page + charts | 1 day |
|
||||
| Media page + AG Grid | 1 day |
|
||||
| File browser page | 1 day |
|
||||
| Polish + testing + deployment | 1-2 days |
|
||||
| **Total** | **~6-9 days** |
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Polling over WebSocket initially** — simpler, matches current behavior; upgrade path exists for later.
|
||||
- **Auth deferred** — rely on network access control for now; add API key or JWT later.
|
||||
- **CORS enabled** — for Vite dev server and production origin.
|
||||
- **Path resolution stays server-side** — frontend sends Jellyfin paths, backend resolves to SSH paths.
|
||||
- **Both can coexist** — Streamlit and FastAPI can run simultaneously during transition since they share the same clients/services.
|
||||
|
||||
---
|
||||
|
||||
## Optional Post-Migration Enhancements
|
||||
|
||||
- WebSocket push for real-time monitoring/now-playing
|
||||
- JWT authentication
|
||||
- Background index build with SSE progress
|
||||
- Dark/light theme
|
||||
- Persistent user preferences (localStorage + optional backend sync)
|
||||
- Docker Compose (backend + frontend + nginx reverse proxy)
|
||||
Reference in New Issue
Block a user