# Archipelago developer guide

Start with the root [README](../README.md), [repository working rules](../AGENTS.md)
and [contribution guide](../CONTRIBUTING.md). This page is a short map of the
current tree and safe local checks. Feature contracts and release acceptance
live in their linked documents; a passing build does not qualify an installed
node or a release.

## Source map

| Area | Start here |
| --- | --- |
| Backend API and RPC | [`core/archipelago/src/api/`](../core/archipelago/src/api/) and [`dispatcher.rs`](../core/archipelago/src/api/rpc/dispatcher.rs) |
| App runtime and reconciliation | [`core/archipelago/src/container/`](../core/archipelago/src/container/) and [container lifecycle](container-lifecycle.md) |
| Manifest schema and Podman support | [`core/container/src/manifest.rs`](../core/container/src/manifest.rs) and [manifest spec](app-manifest-spec.md) |
| Frontend | [`neode-ui/src/`](../neode-ui/src/), [`rpc-client.ts`](../neode-ui/src/api/rpc-client.ts), and [`router/`](../neode-ui/src/router/) |
| App packages | [`apps/`](../apps/) and [app developer guide](app-developer-guide.md) |
| Installer and host integration | [`image-recipe/`](../image-recipe/) and [OS updates](os-updates.md) |
| Release scope and evidence | [Release & Testing](../Release%20%26%20Testing/README.md) |

The backend Cargo workspace is under `core/`, not the repository root.
`core/Cargo.toml` lists its current members. Read the actual handler and its
callers before changing an RPC contract; the [API reference](api-reference.md)
is an orientation aid, not a generated compatibility guarantee.

## Local setup

Frontend development needs Node.js and npm. Linux with the target service and
container tooling is needed for host integration; a browser mock run does not
exercise Podman, systemd, wallets or an installed OS.

```bash
cd neode-ui
npm ci
npm start
```

`npm start` runs the repository's development script. For focused frontend
checks, run `npm test` with a relevant test path, `npm run type-check`, and
`npm run build` as appropriate. The package scripts in `neode-ui/package.json`
are authoritative when they change.

For a backend compile check:

```bash
cd core
cargo check --locked
```

On a machine with installed apps, execute backend tests only through
[`scripts/test-backend-isolated.sh`](../scripts/test-backend-isolated.sh) from
this repository. It separates test execution from live wallets, service buses,
container storage and host networking. An unrestricted `cargo test` can touch
installed state. `cargo test --no-run` is compilation only and must not be
reported as a test pass. Use disposable integration environments for lifecycle,
network, package or device tests, then qualify the exact artifact on its required
node and physical surfaces.

## Making a change

1. Start from a current canonical ngit ref in a clean branch or isolated
   worktree. Preserve dirty work in other checkouts.
2. Change the smallest relevant source and contract. For app packages, follow
   the [app developer guide](app-developer-guide.md), including launch,
   credentials, signer and HTTP-node acceptance.
3. Run focused checks appropriate to the change. Keep compile, unit,
   disposable integration, immutable artifact and installed-node evidence
   distinct. Record failures and exact source/artifact identities.
4. Open a focused proposal through ngit. Maintainers merge there once; Gitea
   mirrors the exact accepted commits. The [contribution guide](../CONTRIBUTING.md)
   describes the mirror gate. A local commit is not authority to push, merge,
   sign, publish or deploy.

For current work priorities, use the [release and testing index](../Release%20%26%20Testing/README.md)
and its open gates. The [public roadmap](ROADMAP.md) records direction,
not a live task list.