# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Project Overview

Nontara is an alternative to Jellyfin designed to provide private media streaming services. It's a TypeScript-based monorepo built with:

- **Bun**: Runtime environment and package manager
- **Turborepo**: Monorepo build system
- **TanStack Start**: SSR framework for the frontend
- **Hono**: Backend server framework
- **tRPC**: Type-safe APIs
- **Drizzle**: TypeScript-first ORM with SQLite
- **Better-Auth**: Authentication system
- **Biome**: Code formatting and linting

## Development Commands

### Core Development
```bash
# Install dependencies
bun install

# Run all applications in development
bun dev

# Run specific applications
bun dev:web    # Frontend only (localhost:3001)
bun dev:server # Backend only (localhost:3000)

# Build all applications
bun build
```

### Database Operations
```bash
# Start local SQLite database (run from project root)
cd apps/server && bun db:local

# Push schema changes to database
bun db:push

# Open database studio UI
bun db:studio

# Generate migrations
bun db:generate

# Run migrations
bun db:migrate
```

### Code Quality
```bash
# Run Biome formatting and linting
bun check

# Check TypeScript types across all apps
bun check-types
```

### Testing and Single File Operations
```bash
# Run a specific test file (from workspace root)
cd packages/language-codes && bun test.ts

# Check types for specific app
cd apps/server && bun run check-types
cd apps/web && bun run check-types
```

## Architecture Overview

### Monorepo Structure
- `apps/web/` - React frontend with TanStack Start (SSR)
- `apps/server/` - Hono backend with tRPC API layer
- `packages/language-codes/` - Shared language utilities
- `extensions/tmdb-metadata/` - TMDB metadata provider extension

### Backend Architecture (apps/server)

**Service Container Pattern**: The server uses a dependency injection container that manages service lifecycle:
- `Service` class implements the container with registration, activation, and graceful shutdown
- All services extend `BaseService` and implement `IMountable`/`IDisposable`
- Services: OnboardService, ExtensionService, MetadataService, LibraryScannerService

**API Layer**:
- **Hono**: HTTP framework handling CORS, logging, auth endpoints
- **tRPC**: Type-safe API with three procedure types:
  - `publicProcedure`: No authentication required
  - `protectedProcedure`: Requires valid session
  - `onboardProcedure`: Special procedure for initial setup

**Data Layer**:
- **Drizzle ORM**: Type-safe database operations with SQLite
- **Better-Auth**: Authentication with session management
- Database schema in `src/db/schema/`

### Frontend Architecture (apps/web)

**Routing & State**:
- **TanStack Router**: File-based routing with type-safe navigation
- **TanStack Query**: Server state management with tRPC integration
- Route tree auto-generated in `routeTree.gen.ts`

**Component Architecture**:
- **shadcn/ui**: Reusable component library
- **TailwindCSS**: Utility-first styling with custom configuration
- **Radix UI**: Headless component primitives

### Key Patterns

**Type Safety**: End-to-end TypeScript from database schema to frontend components via tRPC

**Workspace Dependencies**: Uses `workspace:*` protocol for internal package references

**Extension System**: Modular extension architecture for metadata providers and other plugins

## Important Configuration Details

### Environment Setup
Both `apps/server/` and `apps/web/` have `.env.example` files that need to be copied to `.env` and configured.

### Database Configuration
- SQLite database with Drizzle migrations in `apps/server/src/db/migrations/`
- Schema definitions in `apps/server/src/db/schema/`
- Use `turso dev --db-file local.db` for local development database

### Code Style
- **Biome**: Enforces tab indentation, double quotes, and organized imports
- **TailwindCSS**: Classes sorted with custom functions (clsx, cva, cn)
- **TypeScript**: Strict type checking across all packages

### Extension Development
Extensions follow the pattern established in `extensions/tmdb-metadata/`:
- Must implement the service interface pattern
- Should be workspace packages with proper TypeScript configuration
- Can depend on the server workspace for shared types and utilities

## Troubleshooting

### Service Container Issues
If services fail to start, check the service activation order in `apps/server/src/services/setup/index.ts`. Services are activated sequentially and have automatic rollback on failure.

### Database Issues
- Ensure `cd apps/server && bun db:local` is running before starting the server
- Use `bun db:push` to sync schema changes
- Check `drizzle.config.ts` for database connection configuration

### Type Errors
- Run `bun check-types` to see all TypeScript errors across the monorepo
- Ensure route tree is up-to-date by restarting the dev server if routing types are incorrect