> For the complete documentation index, see [llms.txt](https://help.form.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.form.io/platform-architecture.md). # Platform Architecture Form.io is a fully containerized platform. Everything runs as Docker containers that can be deployed on-premise, in the cloud, or even locally to a single machine. At the core, an environment is a handful of services connected over a Docker network, each handling a distinct responsibility.
A diagram of the Form.io Platform Architecture. A load balancer connects to three instances of the Form.io Multi-container Docker Service. Each Multicontainer instance is comprised of an Enterprise container and a PDF container. The collection of Multicontainers feeds the DB cluster.

An overview of the Form.io Platform

## **The Enterprise Container** **The Enterprise API server** (`formio/formio-enterprise`, port 3000) is the heart of the platform. It serves the REST APIs for creating and managing forms, manages the storage and retrieval of submissions, and handles user authentication. When enabled, it hosts the **Developer Portal**, a web-based UI where form builders visually design forms, manage projects, configure roles, and promote forms across stages. Whether the portal is enabled or not is controlled by an environment variable configured at deployment. Production instances often run without the portal, keeping it as a pure API endpoint for applications. ## **The PDF Container** **The PDF server** (`formio/pdf-server`, port 4005) is a separate container dedicated to rendering PDFs. It handles uploading existing PDF documents and overlaying Form.io web forms on top of them, as well as generating PDF exports of form submissions. It uses a headless browser (Puppeteer) internally to render forms into PDF format. Both the API server and the PDF server connect to the same database where data is ultimately stored. ## DB Layer **MongoDB** is the database layer. All form definitions (stored as JSON), submissions, user accounts, project configurations, and the Portal Base project data live here. In production deployments, this is typically a managed MongoDB service (MongoDB Atlas, Azure Cosmos DB, AWS DocumentDB), but for local development it can run as a simple Docker container with a mounted volume. ## Additional External Services ### Storage **S3-compatible file storage** handles binary files, like file uploads from form users, or stored PDF documents. Form.io supports a variety of storage options: * AWS S3, directly * Azure Blob Storage * Self-hosted S3-compatible servers, like SeaweedFS or MinIO. The PDF server in particular relies on this for storing generated PDF files. ### NGINX **NGINX** (or another reverse proxy) sits in front of the API and PDF containers, routing all incoming HTTP/HTTPS traffic to the correct service. Requests to the root path go to the API server, requests to `/pdf/` are rewritten and forwarded to the PDF server, and file storage traffic can be routed to the desired storage service or domain. This lets the entire environment sit behind a single URL. ## What lives on the client side The **Form Renderer** is a JavaScript SDK (available for vanilla JS, Angular, and React) that is embedded directly into an application. It takes the JSON form definition from the API and transforms it into a fully interactive, validated form in the browser. All rendering, validation logic, and conditional behavior run client-side. The renderer talks back to the API server only to fetch form definitions and submit completed data. ### Multi-environment deployments A typical enterprise setup uses a **3-environment license**: Development, Test/Authoring, and Production. The Test environment is where the Developer Portal lives, providing a stable place for form builders to work. Stages within a project let teams promote forms from one environment to the next. Each environment has an independent API server, PDF server, and database, all connected through the portal UI using remote connections secured by a shared portal secret. This architecture means form builders work in the portal, developers embed the renderer in their apps, and the Enterprise and PDF servers handle everything in between. This effectively separates Form.io platform development, form building, and application development, preventing issues in one from bottlenecking another. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.form.io/platform-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.