# 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