Build an Arqen backend

This is the main path through the docs. Follow it in order when creating a backend. Each step leaves you with a working application before you add the next capability.

The path

Step	Read	Outcome
1. Create the app	Getting started	A runnable Rust backend with health and agent endpoints
2. Understand the shape	Architecture	Know what belongs in Arqen, your app, and Thingd
3. Add a feature	Modules	Routes, tools, jobs, and checks grouped by domain
4. Add an agent capability	Typed tools	Typed inputs, outputs, permissions, and manifest metadata
5. Add background work	Durable jobs	Leases, retries, idempotency, and dead letters
6. Choose storage	Configuration	Memory, native Thingd, or HTTP Thingd selected explicitly
7. Define and validate data	Thingd schema	A versioned .thingd schema inspected before startup
8. Prepare production	Deployment	Secrets, health, backups, workers, and readiness checks

1. Create the project

Install or run the CLI from the Arqen checkout:

cargo install --path crates/arqen --features cli
arqen new catalog-api --yes
cd catalog-api
cargo run

The generator defaults to an HTTP app with memory storage and structured logging. In a terminal, remove --yes to choose native Thingd, starter examples, and optional Nice Code setup. Confirm that the service is running before writing application code:

curl http://127.0.0.1:8888/health
curl http://127.0.0.1:8888/ready
curl http://127.0.0.1:8888/agent/manifest
curl http://127.0.0.1:8888/docs

Use arqen dev for permissive local development and arqen start for the strict production path.

2. Organize the backend by modules

Create a module for a domain area such as catalog, accounts, or billing:

arqen generate module catalog

A module is the explicit place to register its routes, tools, health checks, and jobs. Declare dependencies by module name so startup order is visible and validated. Keep domain services and request models in your application; Arqen provides the composition and lifecycle support.

Read Modules and application composition before adding a large module graph.

3. Add tools and jobs

Generate the two common agent-facing boundaries:

arqen generate tool create_product
arqen generate job rebuild_search

For each tool, define a stable name, description, JSON input/output schema, required scopes, read/write effect, and idempotency behavior. If the operation will outlive the request, enqueue a job instead of doing the work inline.

Read Typed tools and Durable jobs for the contracts and worker rules.

4. Choose storage deliberately

Start with memory mode:

arqen dev --storage memory

Move to embedded native Thingd when one process owns the durable store:

[storage]
mode = "native"
persistent_path = "/var/lib/catalog-api/data"
schema_path = "schema.thingd"

Use HTTP Thingd when the data service should be separate from the backend:

[storage]
mode = "http"
http_url = "https://thingd.internal"
auth_token = "server-side-token"
schema_path = "schema.thingd"

The application-facing ThingdBackend contract stays the same across these modes. Read Thingd integration before using events, search, links, queues, or replication.

5. Add a schema before production

Keep the versioned schema file with the application and point Arqen at it:

export ARQEN_THINGD_SCHEMA_PATH="$PWD/schema.thingd"
arqen thingd schema-validate schema.thingd --url http://127.0.0.1:8770
arqen thingd schema-remote http://127.0.0.1:8770

The remote Thingd service is authoritative for compatibility and migration history. Arqen validates and reports; it does not silently apply migrations or rewrite data. See Thingd schema for the complete workflow.

6. Verify the backend

Before deployment, run the application checks and inspect the actual storage mode:

arqen check
arqen lint
arqen test
arqen build
arqen start --file arqen.toml

Then verify /health, /ready, /agent/manifest, storage connectivity, queue workers, logs, and the schema report. Use the production runbook as the final checklist.

What Arqen does not decide for you

Arqen does not invent your domain model, tenant ownership, authorization policy, backup schedule, provider credentials, or live migration cutover. Those decisions remain application and operations responsibilities. The application hardening guide explains the boundaries that become important once multiple users or services share data.