ADR-004 — Native Mac Application and Docs-Only Website

From the Burrow™ specification set.

ADR-004 — Native Mac Application and Docs-Only Website

Status

Accepted. Supersedes ADR-001 for the application only. The Swift engine and SQLite catalog decisions in ADR-001 remain in force.

Context

Release 0.1 proved that a hosted Next.js console cannot inventory this Mac. A browser on HTTPS cannot call 127.0.0.1. Fixture tables on /dashboard, /files, /storage, and /activity were layout only. Approving a scan root is a local, permissioned action (security-scoped bookmarks, volume and cloud-provider discovery). That work belongs in a native app.

ADR-001 chose Swift for the engine and Next.js for the management UI. The engine choice still holds. The management-UI choice does not: wrapping Next.js in WKWebView would keep the same local-network and permission problems.

The product targets macOS 27 Golden Gate (Liquid Glass, security-scoped bookmarks, App Intents / Spotlight). The public website remains useful for specifications, brand, and operator docs.

Decision

  1. The application is a SwiftUI Mac app that embeds BurrowEngine on this Mac. Discovery, root approval, and read-only scan run in-process. There is no hosted inventory API.
  2. The website (apps/web on Vercel) is documentation and marketing only. Retired console routes redirect to /.
  3. Do not embed the Next.js site as the Mac app UI.

Consequences

Positive

  • Root approval and scanning use native macOS permissions.
  • The public site cannot be mistaken for a live catalog.
  • BurrowEngine stays the single inventory implementation.

Negative

  • Console layout shipped on the website is removed; native Files / Storage / Activity views are a later sprint.
  • Two UI toolkits remain: SwiftUI for the app, Next.js for docs.

Alternatives

Keep a hosted console with fixtures

Rejected. Fixtures are not inventory. The hosted chrome implied a working product surface the site cannot provide.

WKWebView wrapping Next.js

Rejected. The site still cannot hold security-scoped bookmarks or talk to a loopback engine from a hosted origin.

Revisit

Revisit only if Apple ships a supported way for a public HTTPS origin to perform local inventory. That is not available now.