* feat: migrate tooling and runtimes to bun * fix: serialize act installs and adapt backup checks * fix: finish bun scripts and rootless act setup * fix: support bun images in runtime benchmarks * fix: keep a single bun toolchain configuration * fix: include docs mascot sources in workshop build * docs: use bun in remaining tool commands * fix: complete bun sqlite development tooling * docs: explain sqlite development adapter * fix: align remaining commands and local ci validation * fix: use renovate regex fallback with bun * fix: finalize bun sqlite connections during cleanup * fix: preserve sqlite foreign key enforcement * fix: align docker build frontends * fix: prepare release versions with bun * Add Bun benchmarks and preserve SQLite connection defaults * Benchmark Bun installs, conflicts and production workloads * Force Bun workspace tools and HTTP/1.1 upstream streaming * Exclude benchmark evidence from Docker contexts * Expose branch benchmarks through CI * Verify hydrated widget data in production benchmarks * Measure image archives and document benchmark protocol * Audit dependency sharing across every workspace * Pin pnpm for nested baseline benchmark scripts * Preserve nested manager pinning on benchmark resume * Include application and runtime image footprints * Fail benchmark gates on candidate command errors * Report complete build overhead and sampled memory bounds * Validate migration comparisons across pinned revisions * Record configurable runtime memory budgets * Retain out-of-memory kills in runtime budget probes * Reject OOM events consistently across runtime metrics * Record complete Bun migration benchmarks * Record memory diagnosis and correct Turbo caching * Use Bun package management while preserving Node runtimes * Keep native build fallbacks and exclude development artifacts * Fix Node ESM metadata and isolate local CI configuration * Measure development performance and isolate act environment * Support isolated environment files in rootless act * Validate the full migration range with act * Preserve native SQLite binding for bundled migrations * Use documented dev defaults and report benchmark scope * Validate dev defaults and isolate restart measurements * Record package-manager and development benchmarks * Keep benchmark measurements and link full command artifacts * Clean up temporary act environment files * Validate Node runtimes in package-manager comparisons * Validate every workspace in manual CI runs * Retain patched nested brace expansion versions * Complete package-manager and Node performance report * Normalize archived benchmark logs * Record final hosted validation * Cache both Next builds with platform isolation * Prime cache with write-only mode * Split Next artifacts below Cloudflare upload limit * Assemble coherent standalone cache outputs * Preserve traced middleware entrypoints * Assemble traced directory links before files * Separate cached dependencies from assembled output * Record signed Turbo cache benchmarks * Remove archived benchmark captures Full benchmark evidence is preserved at 8f7d3bcd14109bfb13fa664d31710b88d820ad66. * Remove migration benchmark harness * fix: correct migration launch and local Act prerequisites * Consolidate Turbo caches and production artifacts * Exclude generated files from Docker cache inputs * fix: address Bun migration review findings * fix: check restored compiler bundle manifests
111 lines
7.0 KiB
Markdown
111 lines
7.0 KiB
Markdown
# Homarr architecture
|
|
|
|
## Contents
|
|
|
|
- [Applications and runtimes](#applications-and-runtimes)
|
|
- [Package map](#package-map)
|
|
- [Dependency direction](#dependency-direction)
|
|
- [Core patterns](#core-patterns)
|
|
- [Commands and conventions](#commands-and-conventions)
|
|
|
|
## Applications and runtimes
|
|
|
|
| Path | Role |
|
|
| ---------------- | ---------------------------------------------------------------------------------------- |
|
|
| `apps/nextjs` | Main Next.js application and HTTP APIs on port 3000 |
|
|
| `apps/docs` | Next.js and Fumadocs documentation site on port 3003 |
|
|
| `apps/tasks` | Cron-job initialization and scheduling runtime; it does not expose the old port-3002 API |
|
|
| `apps/websocket` | tRPC WebSocket subscriptions on port 3001 |
|
|
| `apps/workshop` | Go/PocketBase Workshop service and provider integration |
|
|
|
|
`bun run dev` runs only `@homarr/nextjs`. Use `bun run --filter @homarr/tasks dev`, `bun run --filter @homarr/websocket dev`, or `bun run dev:docs` when a task needs those runtimes.
|
|
|
|
In production, `apps/nextjs/src/instrumentation-node.ts` starts the tasks and WebSocket runtimes inside the Bun process. Nginx listens on port 7575, proxies `/websockets` to port 3001, and sends other traffic to port 3000. Redis can run internally or externally.
|
|
|
|
## Package map
|
|
|
|
### Foundation and domain
|
|
|
|
- `core`: environment validation, database and Redis factories, logging, infrastructure.
|
|
- `definitions`: domain enums, integration definitions, widget kinds, permissions.
|
|
- `common`: shared utilities with environment-specific entrypoints. Search it before adding helpers.
|
|
- `validation`: shared Zod schemas.
|
|
- `server-settings`: typed server-setting keys and access.
|
|
|
|
### Data, identity, and transport
|
|
|
|
- `db`: Drizzle schemas, queries, migrations, and SQLite and PostgreSQL drivers.
|
|
- `auth`: Auth.js/NextAuth configuration, sessions, providers, and API keys.
|
|
- `api`: tRPC routers, contexts, MCP metadata extraction, OpenAPI, and client/server entrypoints.
|
|
- `redis`: Redis clients, pub/sub channels, and caches.
|
|
- `cron-jobs-core`, `cron-jobs`, `cron-job-status`: scheduling primitives, job implementations, and status transport.
|
|
|
|
### Backends and external systems
|
|
|
|
- `integrations`: typed clients for external applications.
|
|
- `request-handler`: shared server request flows.
|
|
- `docker`, `ping`, `image-proxy`, `icons`, `analytics`: bounded infrastructure capabilities.
|
|
- `custom-widgets`: Custom JSX v2 schema, validation, runtime, and security contracts.
|
|
- `workshop`: TypeScript Workshop client, backend contracts, and schemas used by Homarr.
|
|
|
|
### UI and composed features
|
|
|
|
- `ui`: shared Mantine components, theme, and hooks. Search here before creating a primitive.
|
|
- `form`, `forms-collection`: Zod-backed form setup and reusable forms.
|
|
- `modals`, `modals-collection`: modal primitives and feature modals.
|
|
- `boards`: board state, edit mode, and cache coordination.
|
|
- `settings`, `spotlight`, `notifications`, `onboarding`: cross-feature UI flows.
|
|
- `widgets`: widget definitions, dynamic component loaders, and shared widget UI.
|
|
- `translation`: next-intl configuration and locale catalogs.
|
|
- `cli`: Bun operations CLI. `tools/homarr-dev` is the separate Go developer CLI.
|
|
|
|
## Dependency direction
|
|
|
|
Prefer these directions; verify the exact dependency in package manifests before changing a boundary.
|
|
|
|
1. Put infrastructure in `core` and stable domain names in `definitions`.
|
|
2. Put reusable, dependency-light helpers in `common`; use its public environment-specific entrypoints.
|
|
3. Build persistence in `db`, identity in `auth`, transport in `redis`, and external clients in `integrations`.
|
|
4. Compose server behavior in `api`, `cron-jobs`, and request-handler packages.
|
|
5. Build primitives in `ui`, `form`, and `modals`; compose product surfaces in widgets and collection packages.
|
|
6. Keep app entrypoints in `apps/*` thin. Avoid moving reusable behavior into `apps/nextjs` when a package already owns it.
|
|
|
|
## Core patterns
|
|
|
|
### tRPC and MCP
|
|
|
|
`packages/api/src/root.ts` lazily composes the application router. Server components use `@homarr/api/server`; client components use `@homarr/api/client`. MCP extraction requires the eager router in `packages/api/src/mcp.ts`, so MCP-enabled subrouters must be imported and registered there directly. Use the `mcp-integration` skill for exposure and security rules.
|
|
|
|
### Databases
|
|
|
|
Drizzle schemas live in `packages/db/schema/`. `DB_DRIVER` selects `better-sqlite3` or `node-postgres`; MySQL and MariaDB are no longer runtime drivers in v2. Existing MySQL installations must use the documented converter before upgrading. Migrations live under `packages/db/migrations/sqlite/` and `packages/db/migrations/postgresql/`.
|
|
|
|
### Widgets
|
|
|
|
`packages/widgets/src/registry.ts` owns the explicit widget-module and component-loader registries. `packages/widgets/src/manifest.ts` caches those loaders and exposes definitions, components, and combined resources. Widget modules use `createWidgetDefinition` and typed option builders. Data commonly comes from tRPC queries or Redis-backed cron results. Use existing shared widget components before creating local variants.
|
|
|
|
### Integrations
|
|
|
|
`packages/definitions/src/integration.ts` owns `integrationDefs` and `IntegrationKind`. `packages/integrations/src/base/creator.ts` owns `createIntegrationAsync`; concrete integrations implement the shared base contract. Keep credentials and permission checks on server-owned paths.
|
|
|
|
### Cron jobs
|
|
|
|
Jobs live in `packages/cron-jobs/src/jobs/` and use `createCronJob`. `apps/tasks` initializes and starts the job group. Job results and status can flow through Redis and tRPC; the retired port-3002 management-API model is no longer part of the architecture.
|
|
|
|
### Routing and localization
|
|
|
|
User routes live below `apps/nextjs/src/app/[locale]/`; the locale segment does not add a URL prefix. Route groups organize home and board surfaces. Administrative routes live under `manage`, Custom Widget configuration has a token route, and Workshop has a management surface.
|
|
|
|
### Custom Widgets and Workshop
|
|
|
|
`packages/custom-widgets` owns the Custom JSX v2 contract. `packages/workshop` is the Homarr-side client/contract package; `apps/workshop` is the separate Go/PocketBase service. Use the `homarr-custom-widget` skill for authoring and security constraints.
|
|
|
|
## Commands and conventions
|
|
|
|
- Read current scripts from the root or package `package.json`; avoid caching commands that do not exist.
|
|
- Use `bun run dev` for Next.js, `bun run dev:docs` for docs, and `bun run dev:cli -- <args>` for the Go developer CLI.
|
|
- Use `bun run docker:dev:up` for the Redis development dependency.
|
|
- Follow the Testing section in `AGENTS.md` for test creation and validation scope.
|
|
- Use `~/*` only inside the Next.js app. Use public `@homarr/*` entrypoints across package boundaries.
|
|
- Keep Mantine application styles separate from the Tailwind-based docs app.
|