Architecture

This page explains how a request to the public API is processed, how events and asynchronous work are handled, and how organizations and environments are separated. These are the assumptions about how Hane behaves that are useful to know when you design a business app.

Overall structure

 Clients (business apps, Console, hanectl, Hane Cowork)
        │  Authorization: Bearer <API key or access token>
        ▼
 ┌──────────────────────┐
 │ Entry (gateway)       │ verify credentials, fix organization/project/environment, rate limits
 └──────────┬───────────┘
            ▼
 ┌──────────────────────┐
 │ Common API            │ pick the owner of the state by path
 └──┬─────────┬─────────┬┘
    ▼         ▼         ▼
 Organization  Business data           Audit
 (per org)     (per org × environment) (per org)
               │ outbox
               ▼
          Queues ──▶ append to audit, send email, deliver webhooks, process documents
               │
               ▼
          Durable execution engine ──▶ advance a case to its next wait or completion

How a request flows

1. The client attaches an API key or an access token to every request. The organization, project, and environment are not part of the URL.
2. The entry verifies the credential and determines the organization, project, and environment bound to it. It also checks roles and scopes, the policy epoch, and the suspension state, and counts the request against rate limits. The result is passed on as a trusted execution context; header values sent by the client are not trusted.
3. The common API routes the request to the owner of the state based on its path: /v1/platform/* goes to the organization state, /v1/audit/* to audit, and the other business APIs (/v1/data, /v1/definitions, /v1/workflows, /v1/approvals, and so on) go to the business data owner.
4. The owner checks scopes and then saves the change. The business change and the record of the events it produces (the outbox) are written in one transaction, so a state where data has changed but no event was emitted cannot occur.

Write APIs follow these common rules. See each service page and the API reference for details.

Rule	What it means
Idempotency	Send Idempotency-Key on POST requests with side effects. A retry with the same key and the same content returns the first response; different content returns 409 IDEMPOTENCY_CONFLICT. The SDK adds a key if you forget
Optimistic locking	Mutable resources have a version. To update, send the ETag you received in If-Match. A missing header returns 428, a mismatch returns 412
Errors	Returned as RFC 9457 Problem Details with code, request_id, and retryable added

Events and asynchronous work

Events recorded by changes to business data are processed asynchronously through queues.

• Queue processing first appends to the audit log and then performs side effects (such as sending email).
• Delivery is at least once. Consumers drop duplicates by event ID, so a side effect happens once even if an event arrives twice. Global ordering is not guaranteed.
• Events reach your systems as signed webhooks sent to the endpoints registered as event subscriptions. See Webhooks for subscriptions and deliveries.
• Heavy work such as scanning documents or extracting their text also runs from queues, outside the business data owner.

Note

If appending to the audit log stops, business continues and events are held. When the number of held events reaches a limit, high-impact operations such as issuing API keys, activating definitions, and executing external operations are refused with 503 (AUDIT_UNAVAILABLE, retryable: true). Reads and safe-side operations such as revoking API keys or suspension are not stopped. Operations resume automatically when audit recovers.

Long-running work

A case can wait across days for a person’s decision or a reply. The business data owner holds the workflow interpretation and the state of cases and waits, while a durable execution engine advances the steps. When a case enters a wait, execution ends for the moment and starts again when a task completes or an event arrives. Hane does not keep calling an LLM or keep an agent’s CLI running while it waits. See Workflows and cases for details.

An agent’s CLI runs in a sandbox container with its network closed and touches business data only through the tool endpoints Hane provides. See Agents for details.

Runtime platform

Hane runs on Cloudflare’s global network. Your business apps do not need to be aware of this, but knowing its characteristics helps with design decisions.

Component	Role in Hane
Workers	The entry and the common API. Started per request and stateless
Durable Objects	The owners of organization state, business data, and audit. Each has its own SQLite database and processes requests one at a time, so writes within the same owner are protected by transactions
D1	Cross-organization indexes (organization names, API key hashes, user memberships and invitations)
R2	Document originals, ReleaseBundle bodies, and audit record bodies
Queues	Event delivery, document processing, and webhook delivery. Undeliverable messages stay in a dead letter queue
Workflows	The durable execution engine that advances cases
Containers	Sandboxes for agent CLIs, and disposable jobs such as document conversion and OCR

Organization isolation

Data is isolated between organizations by separating where it is stored.

• There is one business data owner per organization × environment. Data never shares a database with another organization.
• Organization information (members, groups, projects, service accounts, suspension) lives in one owner per organization.
• Which owner receives a request is decided only from the execution context verified by the entry, never from the request body or headers.
• Projects are separated by keys and authorization within the same owner. Every table includes the project ID in its key, and every read and write is restricted to the current project.

Environments

Each project has three environments: dev, stage, and prod.

Aspect	Per-environment behavior
Business data	Stored in a separate owner per environment. Data in dev and prod never mixes
Credentials	A service account and its API keys are bound to one environment of one project. Access tokens are also issued for a specific organization, project, and environment
Definitions	Can be applied only in dev. A ReleaseBundle created in dev is promoted to stage and prod with the same content
Settings	Values that differ by environment (connection targets, senders, and so on) go in a per-environment EnvironmentBinding applied in that environment

The flow for applying and promoting definitions is described in Managing definitions as code.

Read next

Organizations, projects, and environmentsMembers, roles, service accounts, and API keys

Managing definitions as codeManifests, ReleaseBundles, and activation

SecurityHow authorization, secrets, and audit work

Audit and usageSearching the audit log and viewing usage