Files
homarr/.agents/skills/codebase-context/references/architecture.md
T
Thomas 229bd4b3ed chore: use Bun package management and Turbo remote caching (#6978)
* 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
2026-10-07 16:38:14 +02:00

7.0 KiB

Homarr architecture

Contents

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.