mystuff_frontend/README.md

![Omnyx Logo](img/logo.png)

# Omnyx - Media Discovery Platform

![Omnyx Banner](img/banner.png)

A modern web application for browsing, managing, and discovering media across multiple categories. Omnyx provides a unified interface for your media library with support for importing from external sources like Playnite, StashAPP, and XBVR.

## Features

- **Multi-Category Media Management**: Browse and organize Anime, Movies, TV Series, Music, Books, Consoles, Games, and Adult content
- **Detailed Media Views**: Rich information display including descriptions, genres, studios, cast, and ratings
- **Cast & Staff Directory**: Explore actors, directors, and other staff across your media library
- **Search & Filter**: Quickly find media by title, year, genre, or studio
- **Custom Media**: Add your own media entries manually
- **External Importers**: Import libraries from popular media managers:
  - **Playnite**: Import your game library with playtime, achievements, and metadata
  - **StashAPP**: Import adult content with scene and performer details
  - **XBVR**: Import VR content with scene information
- **Category Toggles**: Enable/disable categories to customize your view
- **Responsive Design**: Beautiful UI built with Tailwind CSS and shadcn/ui components

## Tech Stack

- **Frontend Framework**: React 19 with TypeScript
- **Build Tool**: Vite 6
- **Styling**: Tailwind CSS 4
- **UI Components**: shadcn/ui, Base UI
- **Icons**: Lucide React
- **Animations**: Motion (Framer Motion)
- **Fonts**: Geist Variable Font

## Prerequisites

- Node.js (v18 or higher)
- npm or yarn
- Backend API server (configured via environment variables)

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd frontend
```

2. Install dependencies:
```bash
npm install
```

3. Configure environment variables:
```bash
cp .env.example .env
```

Edit `.env` and configure your settings (see [Configuration](#configuration) below).

4. Start the development server:
```bash
npm run dev
```

The app will be available at `http://localhost:3000`

## Configuration

Create a `.env` file based on `.env.example`:

```env
# App URL (auto-injected by AI Studio in production)
APP_URL="http://localhost:3000"

# XBVR Importer
VITE_XBVR_URL="http://localhost:9999"

# StashAPP Importer
VITE_STASHAPP_URL="http://localhost:9999"
VITE_STASHAPP_API_KEY="your-api-key"

# Playnite Importer
VITE_PLAYNITE_IP="localhost"
VITE_PLAYNITE_PORT="19821"
VITE_PLAYNITE_API_TOKEN="your-api-token"
```

### Importer Configuration

#### Playnite
1. Install the [Playnite Bridge extension](https://github.com/JosefNemec/PlayniteExtensions) in Playnite
2. Enable the HTTP API server in Playnite settings
3. Generate an API token in the Playnite Bridge settings
4. Configure the IP, port, and token in your `.env` file
5. See [playnite_skill.md](playnite_skill.md) for detailed API documentation

#### StashAPP
1. Ensure StashAPP is running and accessible
2. Generate an API key in StashAPP settings
3. Configure the URL and API key in your `.env` file

#### XBVR
1. Ensure XBVR is running and accessible
2. Configure the URL in your `.env` file

## Desktop App (Tauri) — Vollständig offline nutzbar

Omnyx ist eine einzige Desktop-App — der Nutzer installiert sie und bekommt ein Fenster mit der Benutzeroberfläche. Backend und Frontend sind in einer Anwendung vereint, **kein externer Server nötig**.

> ⚠️ **Wichtig:** Es entstehen *zwei* verschiedene `.exe`-Dateien (Tauri-Shell + Backend-Sidecar), aber **der Nutzer startet nur die Omnyx-App**. Das Backend läuft automatisch unsichtbar im Hintergrund.

### Architektur (Entwickler-Perspektive)

```
┌───────────────────────────────────────────┐
│           Omnyx Desktop App               │
│                                           │
│  ┌─────────────────────┐                  │
│  │ Tauri-WebView       │  ← Nutzer sieht │
│  │ (React-Frontend)    │    DAS           │
│  │                     │                  │
│  │ API → localhost:3001│                  │
│  └────────┬────────────┘                  │
│           │ (unsichtbar)                  │
│  ┌────────▼────────────┐                  │
│  │ Bun-Sidecar         │  ← läuft im     │
│  │ (Backend, Port 3001)│    Hintergrund   │
│  │                     │                  │
│  │ SQLite-Datenbank    │                  │
│  │ data/omnyx.db       │                  │
│  └─────────────────────┘                  │
└───────────────────────────────────────────┘
```

Für den **Endnutzer** sieht es so aus: Doppelklick auf "Omnyx" → ein Fenster öffnet sich → fertig.

### Voraussetzungen (zum Bauen)

- [Bun](https://bun.sh/) ≥ 1.3 (Backend-Kompilierung)
- [Rust](https://rustup.rs/) ≥ 1.77 (Tauri-Build)
- Node.js ≥ 18

### One-Click-Build

```bash
cd frontend
npm run desktop:build
```

Macht alles automatisch: Backend kompilieren → Binary kopieren → Tauri-App bauen → Installer erzeugen.

### Schritt für Schritt

#### 1. Backend-Binary kompilieren

```bash
cd backend
bun install
bun run compile:tauri
```

Erzeugt `backend/dist-exe/omnyx-backend.exe` (~50 MB Single-File) und kopiert es automatisch in `frontend/src-tauri/binaries/`.

Der Dateiname muss dem [Tauri-Target-Triple](https://v2.tauri.app/develop/sidecars/#target-triples) entsprechen:
- Windows: `omnyx-backend-x86_64-pc-windows-msvc.exe`
- Linux: `omnyx-backend-x86_64-unknown-linux-gnu`

#### 2. Desktop-App bauen (Produktion)

```bash
cd frontend
npm install
npm run tauri build
```

Erzeugt Installer in `src-tauri/target/release/bundle/`:
- `nsis\Omnyx_0.1.0_x64-setup.exe` — Windows-Installer
- `msi\Omnyx_0.1.0_x64_en-US.msi` — MSI-Paket

#### 3. Desktop-App testen (Dev-Modus)

```bash
cd frontend
npm install
npm run tauri dev
```

Startet ein natives Fenster, Vite-Dev-Server (Port 3000) und Backend-Sidecar (Port 3001) — mit Hot-Reload.

### Konfiguration

Für Tauri wird automatisch die Datei `.env.tauri` verwendet (via `--mode tauri`):

```env
# Lokaler Backend-Port
VITE_API_URL=http://localhost:3001
# Externe Importer (optional — nur bei Netzwerk-Zugriff)
VITE_XBVR_URL=http://localhost:4080
VITE_STASHAPP_URL=http://localhost:10001
```

Alle Datenbanken und Konfigurationen liegen **lokal** — kein Internet oder Server erforderlich.

## Usage

### Browsing Media
- Navigate between categories using the header navigation
- Toggle categories on/off using the category buttons
- Search for media using the search bar
- Click on any media item to view detailed information

### Managing Media
- **Add Media**: Click the "+" button to add custom media entries
- **Import**: Use the import feature to bring in libraries from Playnite, StashAPP, or XBVR
- **View Cast**: Browse the cast directory to see all staff across your library

### Importing from External Sources
1. Click the import button in the header
2. Select the importer you want to use
3. Follow the on-screen instructions to configure and run the import
4. Progress will be displayed in real-time

## Available Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build
- `npm run tauri` - Run Tauri desktop app
- `npm run lint` - Run TypeScript type checking
- `npm run clean` - Remove build artifacts

## Project Structure

```
src/
├── components/          # React components
│   ├── ui/             # shadcn/ui components
│   ├── AddMediaView.tsx
│   ├── BrowseView.tsx
│   ├── CastDetailView.tsx
│   ├── CastView.tsx
│   ├── DetailView.tsx
│   └── ImporterView.tsx
├── lib/                # Utility functions
│   ├── playniteImporter.ts
│   ├── stashappImporter.ts
│   └── utils.ts
├── App.tsx             # Main application component
├── api.ts              # API client functions
├── data.ts             # Mock data
└── types.ts            # TypeScript type definitions
```

## API Documentation

For detailed API documentation, see [api.md](api.md).

## License

SPDX-License-Identifier: Apache-2.0

## Support

For issues, questions, or contributions, please refer to the project repository.