Transcriptarr/frontend/README.md

TranscriptorIO Frontend

Vue 3 + TypeScript + Vite frontend for TranscriptorIO.

🚀 Quick Start

Prerequisites

• Node.js 18+ (use nvm for easy management)
• npm or yarn

Install nvm (if not installed)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell
source ~/.bashrc  # or ~/.zshrc

# Install Node.js 18
nvm install 18
nvm use 18

Install Dependencies

cd frontend
npm install

Development

# Start dev server (with hot-reload)
npm run dev

# Backend proxy is configured to http://localhost:8000
# Frontend runs on http://localhost:3000

Build for Production

npm run build

# Output in dist/ directory

Preview Production Build

npm run preview

📁 Project Structure

frontend/
├── src/
│   ├── assets/
│   │   └── css/
│   │       └── main.css         # Global styles (Tdarr-inspired dark theme)
│   ├── components/              # Reusable Vue components
│   ├── views/                   # Page components
│   │   ├── DashboardView.vue    # Main dashboard
│   │   ├── WorkersView.vue      # Worker management
│   │   ├── QueueView.vue        # Job queue
│   │   ├── ScannerView.vue      # Library scanner
│   │   ├── RulesView.vue        # Scan rules
│   │   └── SettingsView.vue     # Settings
│   ├── stores/                  # Pinia state management
│   │   ├── system.ts            # System status store
│   │   ├── workers.ts           # Workers store
│   │   └── jobs.ts              # Jobs store
│   ├── services/
│   │   └── api.ts               # Axios API client
│   ├── types/
│   │   └── api.ts               # TypeScript interfaces
│   ├── router/
│   │   └── index.ts             # Vue Router configuration
│   ├── App.vue                  # Root component
│   └── main.ts                  # App entry point
├── index.html
├── vite.config.ts               # Vite configuration
├── tsconfig.json                # TypeScript configuration
└── package.json

🎨 Design

Theme

• Dark theme inspired by Tdarr
• Color palette optimized for monitoring and data visualization
• Fully responsive design

Features Implemented

• ✅ Dashboard with system overview
• ✅ Worker management with real-time updates
• ✅ Auto-refresh every 3-5 seconds
• ✅ Modal dialogs for actions
• ✅ Status badges and progress bars
• ⏳ Job queue view (placeholder)
• ⏳ Scanner control (placeholder)
• ⏳ Rules editor (placeholder)
• ⏳ Settings (placeholder)

🔌 API Integration

The frontend communicates with the backend API via Axios:

// Example usage
import { workersApi } from '@/services/api'

// Get all workers
const workers = await workersApi.getAll()

// Add a GPU worker
await workersApi.add({
  worker_type: 'gpu',
  device_id: 0
})

API Proxy Configuration

Vite dev server proxies API requests to the backend:

// vite.config.ts
server: {
  proxy: {
    '/api': 'http://localhost:8000',
    '/health': 'http://localhost:8000'
  }
}

🧩 State Management

Uses Pinia for state management:

// Example store usage
import { useWorkersStore } from '@/stores/workers'

const workersStore = useWorkersStore()
await workersStore.fetchWorkers()

🔧 Development

Recommended IDE Setup

• VS Code with extensions:
  • Volar (Vue 3 support)
  • TypeScript Vue Plugin
  • ESLint

Type Checking

npm run build  # Includes type checking with vue-tsc

Linting

npm run lint

📦 Dependencies

Core

• Vue 3 - Progressive JavaScript framework
• Vite - Fast build tool
• TypeScript - Type safety
• Vue Router - Client-side routing
• Pinia - State management
• Axios - HTTP client

Dev Dependencies

• vue-tsc - Vue TypeScript compiler
• ESLint - Code linting
• TypeScript ESLint - TypeScript linting rules

🚀 Deployment

Standalone Deployment

# Build
npm run build

# Serve with any static file server
npx serve dist

Integration with Backend

The built frontend can be served by FastAPI:

# backend/app.py
from fastapi.staticfiles import StaticFiles

app.mount("/", StaticFiles(directory="frontend/dist", html=True), name="static")

📱 Responsive Design

• Desktop-first design
• Breakpoint: 768px for mobile
• Touch-friendly controls
• Optimized for tablets and phones

🎯 Roadmap

Phase 1 (Current)

• ✅ Dashboard
• ✅ Worker management
• ⏳ Job queue view

Phase 2

• ⏳ Scanner controls
• ⏳ Rules editor
• ⏳ Settings page

Phase 3

• ⏳ WebSocket support for real-time updates
• ⏳ Advanced filtering and search
• ⏳ Job logs viewer
• ⏳ Dark/light theme toggle

🐛 Known Issues

• Auto-refresh uses polling (will migrate to WebSocket)
• Some views are placeholders
• No authentication yet

📄 License

MIT License - Same as backend