archy/docs/developer-guide.md

Archipelago developer guide

Start with the root README, repository working rules and contribution guide. 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/ and dispatcher.rs
App runtime and reconciliation	core/archipelago/src/container/ and container lifecycle
Manifest schema and Podman support	core/container/src/manifest.rs and manifest spec
Frontend	neode-ui/src/, rpc-client.ts, and router/
App packages	apps/ and app developer guide
Installer and host integration	image-recipe/ and OS updates
Release scope and evidence	Release & Testing

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 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.

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:

cd core
cargo check --locked

On a machine with installed apps, execute backend tests only through 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, 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 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 and its open gates. The public roadmap records direction, not a live task list.