homeio

Shape: Modular Monolith

• Runtime: Next.js Node runtime.
• Modules: system, apps, files, network, notifications, scheduled-tasks, shared db and cache infrastructure.
• Realtime:
  • SSE at /api/v1/system/stream for one-way live metrics.
  • SSE at /api/v1/network/events/stream for live network state updates.
  • SSE at /api/v1/docker/stats/stream, /api/v1/store/operations/[operationId]/stream, /api/v1/notifications/stream, and /api/v1/files/usb/stream for module-specific updates.

Why this works on Pi 4

• Single deployable process reduces memory and orchestration overhead.
• Postgres handles durable state and future growth without immediate migration.
• In-memory LRU cache absorbs hot reads and smooths CPU usage.
• SSE is lightweight for dashboards and state updates.
• Large file uploads stream through the Next route and, on bare-metal installs, can be handled by the Go upload sidecar over a local Unix socket.

API Endpoints

• GET /api/health
• POST /api/auth/register (enabled when no users exist, or when AUTH_ALLOW_REGISTRATION=true)
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me
• POST /api/auth/unlock
• GET /api/auth/status
• GET /api/v1/system/metrics
• GET /api/v1/system/stream (SSE)
• GET /api/v1/system/info
• GET/POST /api/v1/system/disks*
• GET /api/v1/network/events/stream (SSE)
• GET /api/v1/apps
• GET/POST /api/v1/files*
• GET/POST/PATCH/DELETE /api/v1/files/google-drive*
• GET/PUT/DELETE /api/v1/settings/google-oauth
• POST /api/v1/terminal/execute
• GET /api/v1/logs

Auth Flow

• Single-user flow with bootstrap redirect:
  • If no users in DB: /register is the entry route.
  • If users exist: /login is the entry route.
• users and sessions are persisted in Postgres.
• App routes and protected API routes call shared auth helpers such as requireApiSession(); there is no central middleware auth layer for all /api/v1/** routes.
• Lock screen uses the same authenticated session and validates password via POST /api/auth/unlock.

Observability & Performance Logging

• Structured JSON logs are emitted to terminal and LOG_FILE_PATH.
• Every API, DB query, and realtime connection is logged with:
  • timestamp, runtime, level, layer, action, status
  • durationMs (where applicable), requestId, and meta
  • serialized error payload on failures
• Hook/client actions use the same structure and are ingested through /api/v1/logs.
• Useful env flags:
  • LOG_LEVEL and NEXT_PUBLIC_LOG_LEVEL for verbosity
  • LOG_TO_FILE to enable/disable file sink
  • NEXT_PUBLIC_CLIENT_LOG_INGEST to enable/disable hook log ingestion

Client Data Strategy

• TanStack Query is configured in AppProviders.
• useSystemMetrics fetches baseline metrics.
• useSystemSse pushes live metric updates into query cache.
• Terminal commands are executed via the terminal API route and rendered by the desktop terminal window.

Setup

1. Copy .env.example values into your runtime env.
2. Initialize DB schema:
   • run npm run db:init
3. Install dependencies and run:
   • npm install
   • npm run dev