# NODE.DC Device Core

Device Core is the product-owned source repository for the universal NODE.DC
device control plane. It owns the Device Manager UI/BFF, provider-neutral
device runtime, adapters, edge channel, deployment descriptors and canonical
artifact builders for the `device-plane` and `device-edge-vps` components.

The repository boundary does **not** change the production boundary:

- Synology live root remains `/volume1/docker/nodedc-device-plane`;
- Compose project remains `nodedc-device-plane`;
- deploy artifacts keep `component=device-plane` or `component=device-edge-vps`;
- runtime databases, volumes, secrets, mTLS identity and edge registrations are
  preserved and are never stored in Git;
- the root-owned `nodedc-deploy` runner and component registry remain owned by
  `NODEDC_PLATFORM`;
- Hub/Authentik authorization, Launcher service grants and the platform public
  reverse-proxy route remain owned by `NODEDC_PLATFORM`;
- the shared UI canon remains owned by `NODEDC_DESIGN_GUIDELINE`.

## Source layout

- `apps/device-manager` — Device Manager browser app and server-owned BFF;
- `packages/*` — protocol, adapter and edge-channel contracts;
- `services/*` — control core, gateway and edge runtimes;
- `deployment/*` — immutable release/bootstrap descriptor templates;
- `vps/*` — reviewed VPS process, firewall and systemd definitions;
- `infra/deploy-runner/*` — Device Core artifact builders and builder tests;
- `docker-compose.*.yml` — reviewed runtime topologies.

## Canonical checkout topology

The Device Manager consumes the canonical UI packages directly from the
sibling Design Guideline repository; their source is intentionally not copied
here:

```text
NODEDC/
├── NODEDC_DEVICE_CORE/
├── NODEDC_DESIGN_GUIDELINE/
└── platform/
```

Install and verify from this repository root:

```bash
npm install
npm run build
npm run typecheck
npm test
```

`npm run test:deploy` validates the product-owned artifact builders. The
platform runner registry is validated separately in `NODEDC_PLATFORM`.

## Deployment ownership

Artifact builders in `infra/deploy-runner` emit data-only tarballs. They never
orchestrate Docker or mutate a live host. Promotion remains the established
two-step workflow:

```bash
sudo /usr/local/sbin/nodedc-deploy plan /volume1/docker/nodedc-deploy/inbox/<artifact>.tgz
sudo /usr/local/sbin/nodedc-deploy apply /volume1/docker/nodedc-deploy/inbox/<artifact>.tgz
```

See [Repository boundary](docs/REPOSITORY_BOUNDARY.md) and
[Implementation baseline](docs/IMPLEMENTATION_BASELINE.md) for the security,
runtime and rollout constraints. The provider-neutral VPS/host expansion is
tracked as an explicit
[ontology candidate](docs/DEVICE_INFRASTRUCTURE_HOST_ONTOLOGY_CANDIDATE.md)
until the official ontology owner publishes canonical host, deployment,
service and health concepts.