Merge branch 'main' into feature/jellyfin-invite-system

Author: mchestr

README.md

@@ -58,6 +58,8 @@ Plex Management System transforms your Plex experience by combining powerful man
 - **Client Configuration Guides** to ensure Direct Play and best quality
 - **Issue Reporting** workflow to streamline support requests
 - **Media Request** integration (via Overseerr)
+- **Discord Integration** for community engagement and announcements (optional)
+- **Service Status** monitoring for all connected platforms
 
 ### 📊 Plex Wrapped & Statistics
 - **Total watch time** breakdown (movies vs. shows)
@@ -73,10 +75,13 @@ Plex Management System transforms your Plex experience by combining powerful man
 - **Responsive design** that works on any device
 
 ### 🛠️ Admin Features
-- **User management** dashboard
+- **User management** dashboard with role-based access control
+- **Service management** - Monitor and configure Plex, Tautulli, Overseerr, Sonarr, Radarr
+- **Announcements system** - Server-wide notifications with markdown support
 - **LLM usage tracking** and cost monitoring
 - **Share analytics** to see what's popular
-- **Centralized configuration** for server integrations
+- **Audit logging** for security and compliance
+- **Centralized configuration** for all integrations
 
 ---
 
@@ -86,10 +91,12 @@ Plex Management System transforms your Plex experience by combining powerful man
 
 - **Node.js** 18+ (LTS recommended)
 - **npm** or **yarn**
+- **PostgreSQL** database (SQLite is no longer supported as of Prisma v7)
 - Access to:
   - A **Plex server** (with admin token)
   - **Tautulli** instance (for viewing statistics)
   - **Overseerr** (optional, for request stats)
+  - **Sonarr/Radarr** (optional, for media management features)
   - **OpenAI** API key (optional, for AI insights)
 
 ### Installation
@@ -111,7 +118,7 @@ cp example.env .env
 ```
 
 Edit `.env` and configure:
-- `DATABASE_URL` - SQLite database path (default: `file:./dev.db`)
+- `DATABASE_URL` - PostgreSQL connection string (e.g., `postgresql://user:password@localhost:5432/plex_manager`)
 - `NEXT_PUBLIC_APP_URL` - Your public application URL (e.g., `http://localhost:3000` for dev, `https://yourdomain.com` for production)
 - `NEXTAUTH_URL` - Your application URL for NextAuth callbacks (should match `NEXT_PUBLIC_APP_URL` in production)
 - `NEXTAUTH_SECRET` - Generate with: `openssl rand -base64 32`
@@ -146,26 +153,31 @@ On first launch, you'll be guided through configuring:
 
 ```
 plex-wrapped/
-├── app/                    # Next.js App Router routes
-│   ├── admin/              # Admin dashboard pages
-│   ├── api/                # API routes
+├── app/                    # Next.js App Router (pages, layouts, routes)
+│   ├── (app)/              # Authenticated app layout group
+│   ├── admin/              # Admin dashboard and management
+│   ├── api/                # API routes (webhooks, external integrations)
 │   ├── auth/               # Authentication pages
 │   ├── onboarding/         # User onboarding flow
-│   ├── setup/              # Initial server setup wizard
-│   └── wrapped/            # Wrapped viewer pages
-├── actions/                 # Server Actions
+│   ├── setup/              # Initial setup wizard
+│   └── wrapped/            # Wrapped viewer and sharing
+├── actions/                # Server Actions (mutations, data operations)
 ├── components/             # React components
 │   ├── admin/              # Admin-specific components
-│   ├── onboarding/         # User onboarding components
-│   ├── setup-wizard/       # Setup wizard components
-│   └── wrapped/            # Wrapped content sections
-├── hooks/                  # Custom React hooks
-├── lib/                    # Utilities and helpers
-│   ├── connections/        # Plex/Tautulli/Overseerr clients
-│   ├── wrapped/            # Wrapped generation logic
-│   └── validations/        # Zod schemas
-├── prisma/                 # Prisma schema and migrations
-└── types/                  # TypeScript type definitions
+│   ├── generator/          # Wrapped generation UI
+│   ├── onboarding/         # Onboarding components
+│   ├── setup-wizard/       # Setup wizard steps
+│   ├── ui/                 # Shared UI primitives
+│   └── wrapped/            # Wrapped display components
+├── lib/                    # Utilities, helpers, business logic
+│   ├── connections/        # External API clients (Plex, Tautulli, Overseerr, etc.)
+│   ├── security/           # Security utilities (rate limiting, CSRF, audit logging)
+│   ├── validations/        # Zod schemas for all services
+│   ├── wrapped/            # Wrapped generation and statistics
+│   └── utils/              # Shared utilities
+├── types/                  # TypeScript type definitions
+├── prisma/                 # Database schema and migrations
+└── e2e/                    # Playwright end-to-end tests
 ```
 
 ### Available Scripts
@@ -189,27 +201,39 @@ plex-wrapped/
 
 ### Development Guidelines
 
-#### **Architecture Principles**
+**📖 For comprehensive development guidelines, see [CLAUDE.md](CLAUDE.md)**
+
+The CLAUDE.md file contains detailed information about:
+- Architecture patterns and component design
+- Server Actions vs API routes
+- Database patterns with Prisma
+- Integration guides (Plex, Tautulli, Overseerr, Sonarr/Radarr)
+- Security best practices
+- Testing strategies
+- Code style conventions
+
+#### **Quick Reference**
+
+**Architecture Principles**
 - **Server Components by default** - Use Client Components (`'use client'`) only when needed
 - **Server Actions** - Prefer Server Actions over API routes for mutations
 - **TanStack Query** - Use for all client-side data fetching
-- **TypeScript strict mode** - Maintain type safety throughout
+- **TypeScript strict mode** - Maintain type safety with exhaustive checks
 
-#### **Code Style**
+**Code Style**
 - **Tailwind CSS** - Use utility classes over custom CSS
 - **Zod** - Validate all user inputs and API responses
 - **Error boundaries** - Implement proper error handling and loading states
-- **Component organization** - Keep components focused and reusable
+- **Component organization** - Keep components focused and reusable (max ~200-300 lines)
+- **Avoid over-engineering** - Implement exactly what's needed, no premature abstractions
 
-#### **Testing**
-- **Jest** - Unit and integration tests
+**Testing**
+- **Jest** - Unit and integration tests with comprehensive coverage
 - **Testing Library** - Component testing utilities
-- **Playwright** - End-to-end testing with authenticated sessions
-- **Coverage** - Aim for comprehensive test coverage
+- **Playwright** - E2E testing with authenticated sessions (use `data-testid` selectors)
+- See [E2E Testing Guide](e2e/README.md) for authenticated session patterns
 
-See [E2E Testing Guide](e2e/README.md) for details on writing Playwright tests with authenticated sessions.
-
-#### **Logging**
+**Logging**
 - Use the `createLogger` utility from `@/lib/utils/logger`
 - See [Logging Guide](docs/logging.md) for details on log levels, metadata, and best practices
 
@@ -259,9 +283,9 @@ When deploying to production, ensure the following environment variables are set
    - Generate with: `openssl rand -base64 32`
    - Keep this secret and never commit it to version control
 
-4. **`DATABASE_URL`** - Your production database connection string
-   - For SQLite: `file:./prisma/production.db`
-   - For PostgreSQL: `postgresql://user:password@host:port/database`
+4. **`DATABASE_URL`** - Your production PostgreSQL database connection string
+   - Example: `postgresql://user:password@host:port/database`
+   - SQLite is no longer supported (Prisma v7 requirement)
 
 ### Important Notes
 
@@ -285,7 +309,7 @@ The project includes a `Dockerfile` for containerized deployments. When deployin
 |----------|-----------|
 | **Framework** | Next.js 14+ (App Router) |
 | **Language** | TypeScript (strict mode) |
-| **Database** | Prisma + SQLite |
+| **Database** | Prisma v7 + PostgreSQL |
 | **Authentication** | NextAuth.js (Plex PIN-based authentication) |
 | **Data Fetching** | TanStack Query (React Query) |
 | **Styling** | Tailwind CSS |
@@ -305,14 +329,39 @@ The project includes a `Dockerfile` for containerized deployments. When deployin
 
 ---
 
+## Integrations
+
+The platform integrates with multiple services to provide a comprehensive Plex management experience:
+
+### Core Services
+- **Plex Media Server** - Primary media server integration (required)
+- **Tautulli** - Watch history and statistics tracking (required for Wrapped features)
+
+### Optional Services
+- **Overseerr** - Media request management and availability tracking
+- **Sonarr** - TV series management and monitoring
+- **Radarr** - Movie management and monitoring
+- **Discord** - Bot integration for server announcements and community features
+- **OpenAI/LLM Providers** - AI-powered insights for Wrapped summaries
+
+All integrations are configured through the setup wizard or admin panel, with validation and connection testing built-in.
+
+---
+
 ## Security
 
 - **PIN-based authentication** via Plex
-- **Server access verification** - only users with access to your Plex server can sign in
-- **Secure token generation** for sharing
+- **Server access verification** - Only users with access to your Plex server can sign in
+- **Secure token generation** for sharing features
 - **Admin-only actions** protected by role checks
-- **Input validation** with Zod schemas
-- **SQL injection protection** via Prisma
+- **Input validation** with Zod schemas on all user inputs and API responses
+- **SQL injection protection** via Prisma parameterized queries
+- **XSS prevention** - React escapes by default, no unsafe HTML rendering
+- **CSRF protection** - Built into Next.js Server Actions
+- **Rate limiting** - Protection for sensitive endpoints
+- **Audit logging** - Tracking of admin actions and security events
+
+See [CLAUDE.md](CLAUDE.md) for detailed security best practices.
 
 ---
 

__tests__/actions/chatbot.test.ts

@@ -2,7 +2,8 @@
  * Tests for actions/chatbot.ts - chatbot sources tracking functionality
  */
 
-import { chatWithAdminBot, type ChatMessage } from "@/actions/chatbot"
+import { chatWithAdminBot } from "@/actions/chatbot"
+import { type ChatMessage } from "@/actions/chatbot/types"
 import { callChatLLM } from "@/lib/llm/chat"
 import { prisma } from "@/lib/prisma"
 import { getServerSession } from "next-auth"

actions/chatbot/index.ts

@@ -9,8 +9,6 @@ import { type ChatMessage, type ChatResponse } from "./types"
 
 const logger = createLogger("CHATBOT")
 
-export type { ChatMessage, ChatResponse }
-
 export async function chatWithAdminBot(
   messages: ChatMessage[],
   conversationId?: string

components/__tests__/admin/chatbot/chat-window.test.tsx

@@ -6,7 +6,8 @@ import { Chatbot } from "@/components/admin/chatbot/chat-window"
 import { ChatProvider } from "@/components/admin/chatbot/chat-context"
 import { render, screen, waitFor } from "@testing-library/react"
 import userEvent from "@testing-library/user-event"
-import { chatWithAdminBot, type ChatMessage } from "@/actions/chatbot"
+import { chatWithAdminBot } from "@/actions/chatbot"
+import { type ChatMessage } from "@/actions/chatbot/types"
 
 // Mock the chatbot action
 jest.mock("@/actions/chatbot", () => ({

components/admin/chatbot/chat-window.tsx

@@ -1,6 +1,7 @@
 "use client"
 
-import { chatWithAdminBot, type ChatMessage } from "@/actions/chatbot"
+import { chatWithAdminBot } from "@/actions/chatbot"
+import { type ChatMessage } from "@/actions/chatbot/types"
 import { AnimatePresence, motion } from "framer-motion"
 import dynamic from "next/dynamic"
 import { useEffect, useRef, useState } from "react"