# Project Constraints

## Delivery sequencing

- Start with `apps/control-plane` first.
- Deliver the core backend in 2 steps, not 3:
  1. `control-server` plus `node-service` contract and runtime loop
  2. web control plane on top of that stable backend seam
- Do not start web UI work until the `control-server` and `node-service` contract is stable.

## Architecture

- `control-server` is the clean backend contract that other parts consume.
- `apps/node-agent` reports into `apps/control-plane`.
- `apps/web` reads from `apps/control-plane`.
- Local mount UX is issued by `apps/control-plane`.

## Backend contract priorities

- The first backend seam must cover:
  - node enrollment
  - node heartbeats
  - node export reporting
  - control-server persistence of nodes and exports
  - mount profile issuance for one export
- `control-server` should own:
  - node auth
  - user auth
  - mount issuance

## Mount profile shape

- Prefer standard WebDAV username and password semantics for Finder compatibility.
- The consumer-facing mount profile should behave like:
  - export id
  - display name
  - mount URL
  - username
  - password
  - readonly
  - expires at

## Service boundary

- Keep `node-service` limited to the WebDAV mount surface.
- Route admin and control actions through `control-server`, not directly from browsers to `node-service`.

## User-scoped auth requirements

- Remove the bootstrap token flow for v1.
- Use a single user-provided username and password across the entire stack:
  - `apps/node-agent` authenticates with the user's username and password from environment variables
  - web app sessions authenticate with the same username and password
  - WebDAV and Finder authentication use the same username and password
- Do not generate separate WebDAV credentials for users.
- Nodes and exports must be owned by users and scoped so authenticated users can only view and mount their own resources.
- Package the node binary for user download and distribution.

## V1 simplicity

- Keep the implementation as simple as possible.
- Do not over-engineer the auth or distribution model for v1.
- Prefer the smallest change set that makes the product usable and distributable.

## Live operations

- If modifying the live Netcup deployment, only stop the `betternas` node process unless the user explicitly asks to modify the deployed backend service.
- When setting up a separate machine as a node in this session, access it through `computer ssh hiromi`.

## Node availability UX

- Prefer default UI behavior that does not present disconnected nodes as mountable.
- Surface connected and disconnected node state in the product when node availability is exposed.

## Product docs UX

- Remove operational setup instructions from the main control-plane page when they are better represented as dedicated end-to-end product docs.
- Prefer a separate clean docs page for simple end-to-end usage instructions.
- Keep the root `README.md` extremely minimal: no headings, just 5-6 plain lines that explain the architecture simply and cleanly.
- Make the default root route land on the main landing page instead of the auth-gated app.
- Add a plain `Docs` button to the left of the sign-in button on the main landing page.