homarr/docs/unraid-ui-project/homarr-architecture.md

Homarr Architecture

Tech Stack

• Next.js 13+ (App Router), React 18, TypeScript
• Mantine UI (component library)
• Zustand (client state), React Query (server state)
• Prisma ORM (SQLite default / PostgreSQL)
• Turbo monorepo, pnpm workspaces

Project Structure

homarr/
├── apps/web/src/           # Main Next.js app
│   ├── app/                # App Router pages
│   ├── components/         # React components
│   ├── modules/            # Widgets & integrations
│   ├── stores/             # Zustand stores
│   └── styles/             # Themes & global CSS
├── packages/
│   ├── api-client/         # API client lib
│   ├── common/             # Shared types/utils
│   ├── definitions/        # Widget/integration defs
│   ├── auth/               # Auth logic
│   └── ui/                 # Shared UI components
├── prisma/                 # DB schema & migrations
└── turbo.json

Widget System

Each widget in apps/web/src/modules/:

• definition.ts - Metadata + Zod config schema
• component.tsx - React component
• settings.tsx - Config panel
• server-actions.ts - Backend operations
• Registered in module index, auto-discovered

Integration System

External service connectors with:

• API client abstraction, credential management
• URL/hostname config, SSL handling
• Error handling, retry, rate limiting, caching

Theming

• CSS variables + Mantine theming + Tailwind
• Light/dark mode, custom color palettes, accent colors
• Wallpaper/background, font size, border radius customization
• Theme persisted in database

Adding New Pages

1. Create in apps/web/src/app/(group)/page-name/page.tsx
2. Use Mantine UI components
3. Add API routes in src/app/api/
4. Create Zustand store or use React Query
5. Update navigation config

Key Patterns

• Server Components by default, 'use client' for interactive
• TRPC for type-safe RPC
• Zod schemas for validation
• Prisma for DB operations