> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> How the CLI, agent, metastructure, and plugins fit together.
Two design choices set formae apart from traditional infrastructure tooling:
* **Active components** automate work that usually needs manual intervention,
reducing the operational burden on you.
* **Automatic state management** tracks every infrastructure change regardless of
where it came from, and keeps state current so an up-to-date
infrastructure-as-code representation is available on request at any time.
Together they improve maintainability, change tracking, and operational
efficiency across the whole infrastructure lifecycle.
## CLI and API
The CLI and API are the front end of the system: a consistent interface for
people and applications to drive the platform. The API currently lives inside the
agent and will be extracted into its own component later. The CLI runs wherever
you need it, on your local machine or on a node in your CI/CD system.
## Metastructure
The **metastructure** is formae's internal representation that combines your
infrastructure configuration with the operational logic to manage it. It enables:
* **Active monitoring** of infrastructure changes in real time.
* **Asynchronous application** of changes that converge to your desired state.
* **Complete version history**, so you can take any infrastructure state (past or
present), modify it, and apply it to any environment.
* **Automatic tracking** of changes made both inside and outside formae.
Traditional IaC tools store only static configuration. The metastructure holds
both the *what* (your infrastructure) and the *how* (the operations to manage it),
which is what lets formae continuously reconcile your actual infrastructure with
your code. This design moves complexity into the agent and keeps the plugins
simple.
## Agent
The agent is the actively running backend of the platform, responsible for
executing core operations. formae currently supports single-agent operation, with
multi-agent distribution planned for the future.
The agent:
* Is the central execution engine for platform operations.
* Maintains state and handles resource management.
* Processes requests from the CLI through the API.
* Manages the metastructure implementation.
You can deploy the agent in several ways:
* **Cloud deployment** runs the agent in a cloud account as a service. This is the
standard approach for production.
* **Local operation** runs the agent entirely on a local computer, whether a
developer's machine or a CI/CD node.
* **Container or Kubernetes** runs the agent in a container, or in a Kubernetes
pod with a few extra prerequisites such as storage.
The agent manages the lifecycle of the technology plugins shipped with formae and
any you implement yourself. Plugins always run as separate processes and are never
embedded.
**A single target must be managed by exactly one agent.** Two agents managing
overlapping targets conflict: each has its own datastore, which leads to
conflicting discovery, duplicate resource tracking, and unpredictable behaviour.
The correct pattern is one agent per target, with multiple team members pointing
their CLIs at the same agent so there is a single source of truth. When you design
targets across agents, make sure no piece of infrastructure is managed by more
than one agent.
## Datastore
The agent uses a datastore for persistence. The implementation varies with your
deployment:
* **SQLite** (default): an embedded database on the agent's local disk, no setup
required.
* **Postgres**: an external PostgreSQL server, typically managed or highly
available.
* **Aurora Data API**: reaches Aurora through the AWS RDS Data API instead of a
direct connection, so no VPC access is needed.
* **Microsoft SQL Server**: an external SQL Server instance, with SQL or workload
identity authentication.