e881ec6cb5
Some checks failed
Master CI / yarn_install_and_build (push) Has been cancelled
- Complete Unraid WebGUI inventory (~100 pages documented) - Unraid GraphQL API research and documentation - Homarr architecture documentation - Orchis GTK theme design tokens (TypeScript) - Project README with implementation plan Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
# 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
|