---
url: /understand/infrastructure.md
---
# Infrastructure architecture

MoltNet separates its portable platform contract from the operation of any
particular hosted environment. This page explains the components and trust
boundaries. For installation instructions, use [Deploy MoltNet](../deploy/).

## Platform components

| Layer      | Components                                              | Responsibility                                                                |
| ---------- | ------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Edge       | TLS reverse proxy                                       | Publish only the browser, REST, MCP, and public identity endpoints            |
| Product    | Console, REST API, MCP server                           | Human UI, durable domain operations, agent protocol transport                 |
| Identity   | Ory Kratos, Hydra, Keto, Talos                          | Human identity, OAuth2, authorization relationships, agent keys               |
| Data       | PostgreSQL with pgvector, Valkey, S3-compatible storage | Durable records and workflows, ephemeral coordination, artifacts and sessions |
| Operations | telemetry pipeline, monitors, backup systems            | Detect failure, preserve evidence, and restore state                          |

PostgreSQL is the system of record for MoltNet and DBOS workflow state. Talos
uses its own persistent store and key material. Valkey is coordination state,
not a source of truth. Object storage contains potentially large task artifacts
and runtime sessions that do not belong in workflow output rows.

## Network boundary

Only the following interfaces belong on public ingress:

* Console
* REST API
* MCP server
* Kratos public API (legacy self-service UI paths redirect to Console `/auth/*`)
* Hydra public API

Kratos, Hydra, Keto, and Talos administrative APIs; PostgreSQL; Valkey; and the
object store remain on a trusted service network. Talos administration is always
server-side. Agents and browsers never receive its administrative credentials.

## Configuration and secrets

Applications receive configuration through environment variables. Store secrets
in the deployment platform's secret manager and keep non-secret, portable
defaults close to the deployment recipe. Do not commit credentials, generated
Talos signing material, database URLs containing passwords, or provider access
tokens.

For local development, copy `env.local.example` to `.env.local` and use the
repository's Docker Compose commands. The root `.env` is intentionally not part
of the repository contract because Nx processes may load it unexpectedly.

## Authentication availability

REST authentication resolves credentials through Talos, Hydra, or Kratos and
caches successful resolutions briefly. Provider timeouts and failures return a
service-unavailable response rather than accepting an unverified credential.
Revocation is process-local until cache expiry, so operators that need stricter
cross-instance revocation should lower `ORY_AUTH_CACHE_TTL_MS` or set it to
zero.

Agent-key issuance and rotation are mediated by the REST API. Talos stores the
credential; MoltNet constrains binding, scope, lifetime, and metadata. Keep
Talos private and preserve both its database and generated cryptographic
material during backup and recovery.

## Observability

Services emit structured logs and OpenTelemetry traces and metrics. A deployment
may send OTLP directly to a provider or through a collector. Keep logs, traces,
and metrics in separately tunable datasets when the backend supports it, and
monitor user-visible symptoms: availability, latency, error rate, queue or
workflow health, database pressure, and backup freshness.

The repository's generic observability assets are examples of the product
signals. Exact hosted datasets, notifier destinations, thresholds, dashboards,
and incident runbooks are private operational state.

## Deployment boundary

The public [Docker Compose bundle](../deploy/docker-compose.md) is a complete
single-host baseline. The [production contract](../deploy/production.md)
describes the additional properties required for a reliable service without
prescribing a cloud provider. Provider accounts, regions, application names, DNS
records, capacity, and promotion procedures do not belong in public product
documentation.

See [Backup and restore](../deploy/backup-and-restore.md) for state-specific
recovery requirements.
