Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Inflow.ai Platform Architecture
Practical guide and worked examples
Follow one request through the platform
The module map below answers where responsibilities live; the worked paths answer how they collaborate. Begin with the HTTP/MCP/UI adapter, identify the native command and its current actor/workspace context, locate the secured domain boundary, then follow only the direct port/adapter and transaction needed by the operation. A Java package name is not a reliable module locator during extraction.
For a reader building the People Operations application, model/rule/interface publication, runtime execution, task effects and deployment are different domains with explicit handoffs. A controller's existence does not prove a complete user journey. A declaration, catalog entry or generated JSON schema likewise does not certify provider availability or production authorization.
| Boundary | What to inspect | What it does not imply |
|---|---|---|
| HTTP/MCP adapter | Route/tool, request/response shape, current context | A second implementation of domain authorization. |
| Secured service | Actor, action, workspace/object and state checks | Every record/task is eligible because its parent is visible. |
| Domain service | Validation, state transition, version/transaction invariant | All remote effects roll back with the local DB. |
| Port and adapter | Repository/gateway contract and concrete implementation | A direct dependency from every domain to the monolith or JDBC. |
| Composition root | Actual production bean graph | An isolated test constructor is the production runtime. |
| Build chain | Reactor POM plus satellite invoker/packaging | A focused module test produced every application/plugin artifact. |
Use the workspace walkthrough, security guide and plugin development guide to turn these paths into concrete tasks. Current source/POMs are authoritative; the extraction plan is historical rationale.
The examples below use synthetic teaching data. They are grounded in the cited source contracts; this documentation change did not execute these operations against a running Inflow deployment. Use normal authenticated sessions and the actual returned identifiers, revisions and versions from an authorized environment.
Example ROOT-ARCH-01 — Trace workspace creation from API to atomic domain state
Scenario and inputs. A developer receives a report that workspace creation succeeded but the expected organizational function is unavailable. The selected operation is POST /api/workspaces; its request contains key/name/description. The investigation should follow the exact creation path without expanding into unrelated BPMN, connector or Studio modules.
Procedure. Start at WorkspaceController.create and identify CreateWorkspaceCommand. Follow the injected WorkspaceService to the secured composition, checking creation permission and authoring admission before the delegate runs. Read the domain's workspace insert, creator Admin seed and general function seed, then locate the relevant repository ports/adapters through focused symbol references. Inspect the production wiring to ensure the transactional secured boundary is actually used; a simplified domain constructor in a unit test can intentionally omit collaborators.
Expected result. The reader identifies a thin HTTP adapter, native secured boundary and domain persistence invariant, including which related writes commit together. This is enough to choose a focused regression boundary or correct documentation. It is not evidence that a deployed database, API or browser workflow was executed by this source trace.
Failure and recovery. If a package name suggests the wrong module, use actual files and POM dependency direction instead of moving code to satisfy that assumption. Do not add a controller-to-JDBC shortcut or bypass the secured service while reproducing a domain issue. Preserve the failing candidate/evidence and investigate its actual wiring before changing behavior.
Sources. WorkspaceController.java:109, SecuredWorkspaceService.java:80, DefaultWorkspaceService.java:148.
Example ROOT-ARCH-02 — Separate application administration from application runtime
Scenario and inputs. Nadia can review an Employees application grant, while Mohammad should only use the resulting published Leave requests application. Both touch application access, but they are different entry points and principals. The architecture must not confuse an administrative preview with a normal user's business authorization or a navigation destination.
Procedure. Follow ApplicationRuntimeAccessController through its preview/apply management service and the original plan/digest/revision inputs. Separately inspect ApplicationEntryController, which derives the authenticated subject and asks the destination resolver for safe choices. Then follow the specific runtime screen/task/record request into its own current service guard. Draw these as separate edges: administration configures a scoped source; login resolves navigation; the domain action enforces current eligibility.
Expected result. The architecture explains why saved contributions, sign-in destinations, Studio policy and row/task rules cannot be collapsed into one “application user” boolean. The HTTP and MCP surfaces can reuse the same native service contracts without creating a parallel permissions model. A source citation or model-selected app key is not an access grant.
Failure and recovery. When a missing action is reported, inspect the intended boundary: stale reviewed scope, destination conflict, domain eligibility or policy outage. Do not solve the symptom by letting an assistant call a lower-level repository or by copying an administrator's actor context into the end-user request. A permitted parent page is not sufficient evidence for a consequential business effect.
Sources. ApplicationRuntimeAccessController.java:1, ApplicationEntryController.java:1, ApplicationRuntimeManagementService.java:1.
Example ROOT-ARCH-03 — Understand what a complete application artifact includes
Scenario and inputs. A developer has passed one platform module's focused tests and wants to hand a deployable application to another operator. Inflow also packages Studio, the isolated runner, first-party plugins and an example plugin through the declared build chain. A single module JAR or a successful skipped-test Maven command is not automatically the complete distribution.
Procedure. Read the root pom.xml module inventory and its build/invoker configuration, then the application, SDK and satellite POMs. Follow the documented frontend locked production build and root package sequence in the repository README, using an admitted isolated lane when actually building. Inspect the intended plugin bundle/distribution resources instead of guessing where a runner JAR belongs. Record which chain ran, which artifacts/hashes were produced and which tests were skipped.
Expected result. The reader distinguishes reactor libraries and the executable application from satellite packaging and the Studio distribution. Current source defines the inventory; hardcoded old module counts are unnecessary. Focused validation can be reported accurately without claiming that all application/plugin/frontend artifacts or all backend cohorts passed.
Failure and recovery. If a required artifact is missing, determine whether its packaging/invoker phase was omitted or an actual build failed. Do not weaken the POM, remove a bundle or present a copied old JAR as a fresh candidate. Preserve current CI/resource holds and use the authorized build owner when execution is outside the documentation task's scope.
Sources. pom.xml:1, pom.xml:1, pom.xml:1, README.md:1.
Example ROOT-ARCH-04 — Find the actual source owner before proposing a dependency
Scenario and inputs. A developer needs to explain a workspace object-grant request and sees the package com.inflowai.platform.workspace.security. The package can span extracted modules, so its name alone does not tell the developer whether a controller, policy contract, implementation or test belongs in kernel, workflow-app or monolith.
Procedure. Locate WorkspaceSecurityController, then its direct GrantService, scope/role contracts and concrete secured implementation using focused file/symbol searches. Read the owning POMs to establish allowed dependency direction. Trace the request's actual object type, principal, scope and expected revision through the native command. Use the current architecture gate for a real boundary change; do not rebuild a retired navigation index or begin a broad package move merely to make the names appear uniform.
Expected result. The reader can draw a source-backed neighborhood: adapter, stable contract, secured service, repository/gateway port and composition. This gives a credible change-impact and review boundary. It does not imply that every class in the same package shares one module or that a reverse dependency is acceptable because it compiles locally.
Failure and recovery. If the proposed lower domain needs an application controller or servlet detail, reconsider the port/adapter boundary before adding the dependency. Preserve current public contracts and record the affected callers/tests. A stale architecture plan or copied module list cannot override the actual reactor and current source.
Sources. WorkspaceSecurityController.java:1, GrantScope.java:1, modularization-plan.md:1, pom.xml:1.
Document status: Current architecture reference, source-audited against
b5861dc4f73fb3165ee77dd35d17a6a85edd8229. This is not runtime certification. For historical extraction decisions, use the modularization plan; dated plans and certification reports are evidence for their stated candidate, not this document's source of current truth.
Inflow.ai is a modular Java 17 and Spring Boot workflow and application platform with a React 19 Studio. BPMN 2.0 execution remains a central domain, but the running application also includes human work, forms, rules, governed data, Fabric, connectors, integrations, AI services, agents, documents, screens, records, identity, workspaces, API management, durable messaging, plugins, and operations.
Architectural Shape
The repository builds as a Maven reactor containing the plugin SDK, test kit,
platform libraries and the platform-monolith application module. The
root POM is the authoritative module inventory; module POMs
define dependencies. Test-support and certification modules are build tooling,
not additional runtime services.
flowchart TB
Clients["Studio · API clients · workers · integrations"]
App["platform-monolith · Spring Boot composition root"]
Domains["Extracted platform domain modules"]
Ports["Repository · gateway · security contracts"]
Adapters["JDBC · Kafka · connector · AI · filesystem adapters"]
Runtime["PostgreSQL · Redpanda · Plugin Runner · Gotenberg · AI providers"]
Clients --> App
App --> Domains
Domains --> Ports
Ports --> Adapters
Adapters --> Runtime
The code follows these rules:
- controllers and filters are HTTP adapters, not owners of domain behavior;
- domain services own validation, lifecycle, and invariants;
- secured and audited decorators enforce cross-cutting policy around services;
- repository and gateway ports isolate persistence and external systems;
- JDBC backs major runtime paths; in-memory adapters remain for focused tests and deliberately local compositions;
- workspace context and current-actor context cross module boundaries through foundation and kernel contracts;
- the monolith assembles modules and retains integrations that genuinely bind several domains or the servlet runtime.
Module Map
The old single source root no longer represents the platform. Production code is distributed across the following reactor modules.
| Module | Responsibility |
|---|---|
inflow-plugin-sdk |
Public expression-function plugin contract. |
inflow-plugin-test-kit |
Plugin author verification helpers. |
platform-foundation |
Shared value types and utilities with no platform dependencies. |
platform-kernel |
Audit, access contracts, workspace security contracts, connector ports, plugin host bridges, and other low-level contracts. |
platform-impact |
Publication impact assessment, fencing, repair orchestration, and change sets. |
platform-deployment |
Workspace deployment domain and asset-family contracts. |
platform-security-testkit |
Shared test builders for security guards with their object checks reachable. |
platform-data |
Data models, publication, data actions and their runtime endpoints, record-type inputs, and screen data contracts. |
platform-datamodel-certification |
Shared data-model certification corpus and database-dialect matrix tests. |
platform-fabric |
Fabric schemas, bindings, materialization, synchronization, governance, integrity, datasets, and graph metadata. |
platform-rule |
Rule definitions, authoring, InflowEL, decision/query execution, API keys, and generated rule behavior. |
platform-form |
Form definitions, versions, validation, and submissions. |
platform-operations |
Operational read models, readiness, metrics, retention, and log-retention contracts. |
platform-services-runtime |
Connectors, AI Gateway, durable messaging, node workers, notifications, activities, agents, and agent memory. |
platform-integration |
Connected systems, integrations, connector templates, contract import, credential vault, and call metering. |
platform-execution-core |
BPMN/process lifecycle, workflow engine, durable runtime, timers, and execution contracts. |
platform-workflow-app |
Human tasks, workspaces, contracts, transfers, documents, assignment, escalation, and workspace AI policy. |
platform-screen-engine |
Screen definitions, validation, rendering plans, and data controls. |
platform-record |
Record operations, generated form bundles, generation, and record API glue. |
platform-identity-core |
Identity contracts, users, groups, passwords, authentication, and authorization. |
platform-identity-mfa |
Multi-factor authentication and recovery behavior. |
platform-identity-scim |
SCIM provisioning surface. |
platform-identity-apikey |
Identity-bound API key behavior. |
platform-identity-login |
Login/session-facing identity behavior. |
platform-identity-admin |
Identity provider services and administration APIs. |
platform-api-management |
Managed machine keys, published APIs, request logs, and their JDBC/service layers. |
platform-mcp |
MCP application-builder transport, tools, and checked domain adapters. |
platform-communications |
Inbound and outbound notification delivery adapters. |
platform-monolith |
Spring Boot application, servlet filters, cross-domain adapters, assembly configuration, Studio packaging, and executable JAR. |
Some Java packages are intentionally split while extraction is completed. A package name alone therefore does not identify its module. Use the root POM, module POMs and the architecture gate when changing dependency boundaries. The modularization plan preserves the extraction history; its old census is not the current inventory.
Runtime Environment
docker-compose.yml defines the supported local development topology.
| Service | Purpose |
|---|---|
java-dev |
Maven/JDK 17 development container and long-lived build environment. |
api-dev |
Spring Boot API and packaged Studio surface. |
postgres-dev |
PostgreSQL development database and durable repositories. |
postgres-runtime-role |
One-shot initialization of the development API's restricted database login. |
redpanda-dev |
Kafka-compatible broker for outbox/inbox messaging. |
plugin-runner-init |
One-shot permissions initialization for plugin IPC. |
plugin-runner |
Healthy, isolated expression-function runner. |
gotenberg-dev |
DOCX-to-PDF conversion service. |
The minimum API dependency stack is:
docker compose up -d postgres-dev redpanda-dev plugin-runner gotenberg-dev java-dev
docker compose ps plugin-runner
.\scripts\migrate.ps1 -Command up
docker compose up -d api-dev
Run this only in an authorized development lane with its own Compose project,
names and ports. The migration wrapper executes inside the running java-dev;
starting only PostgreSQL is insufficient. Renderer preparation and production
source/data holds remain governed by the document-conversion guides.
The runner must be healthy before API readiness is claimed. Ollama is needed
only when a flow executes the local provider; model readiness, not a static
catalog entry, determines whether that execution can run.
Application and API Layer
platform-monolith is the executable application and composition root. It
contains the boot class, app/config assembly, servlet security and logging
filters, cross-domain adapters, and controllers that cannot live in a lower
module without introducing an invalid dependency.
Controllers also live in extracted modules when the HTTP surface belongs to that module, notably data-action, record, identity administration, and API management endpoints. Component scanning assembles both monolith and module controllers into one API.
Major API families cover:
- process definitions, instances, timers, incidents, tasks, forms, and service-task runs;
- data models, records, data actions, Fabric, connectors, integrations, and approved queries;
- rules, expression authoring, AI Gateway, agents, and agent memory;
- screens, generated form bundles, documents, workspaces, and contracts;
- identity administration, SCIM, operations, audit, messaging, and API management.
Do not maintain a hand-written exhaustive controller count here. The code and generated API surfaces change more frequently than this architectural map.
Security, Identity, and Workspace Context
Requests enter through the authentication filter chain, establish a current actor, resolve workspace context, and then call secured services.
flowchart LR
Request --> Authentication
Authentication --> Actor["Current actor"]
Actor --> Workspace["Workspace context"]
Workspace --> Secured["Secured service/decorator"]
Secured --> Domain["Domain service"]
Domain --> Audit["Audit and persistence"]
The platform supports local credentials, browser sessions, user API keys, managed API keys, external providers, MFA/passkeys, groups, role permissions, SCIM, workspace membership, inherited object access, and business functions. Production startup validates that development credentials and unsafe runtime database posture have not leaked into a production configuration.
Workspaces isolate definitions and runtime state. Background workers restore the owning workspace before resolving definitions or executing work. Contracts provide explicit cross-workspace publication and consumption instead of allowing callers to bypass workspace boundaries.
See Identity Configuration, External Authentication Providers, Workspaces, and Workspace Functions and Security.
Workflow and Human Work
BPMN XML is the canonical stored process representation. Publishing validates and versions a definition; the execution core maps it into the internal model and persists process instances, tokens, work items, timers, events, and incidents.
Node handlers delegate human work, service tasks, AI tasks, rules, timers, gateways, subprocesses, and other activity types through explicit runtime contracts. Human tasks project workflow work items into a rich task model with ownership, candidates, delegation, comments, forms, attachments, completion output, assignment, escalation, SLA, and calendar behavior.
Durable workers use leases and recovery rather than assuming one application node. Runtime state changes and messages use transactional boundaries where required. See Durable Runtime State, Process Definition Persistence, Task Persistence, and Service Task Execution.
Rules and InflowEL
The rule module owns constant, expression, decision-table, and query rule lifecycle and execution. Published rules are immutable versioned contracts. InflowEL provides parsing, typing, evaluation, tracing, serialization, and the function catalog used by backend and Studio authoring surfaces.
Query rules resolve governed data sources and push supported filtering, projection, joins, sorting, paging, and aggregation into database engines. Generated CRUD rule packs connect published data models to no-code interface patterns. Rules can also be exposed through rule keys or the governed API management registry.
See Rule Types, Expression Language, and Query Builder.
Data, Fabric, Screens, and Records
Data models are versioned and published into physical or governed runtime contracts. The data domain owns dialect-aware schema generation, publication, record-type catalogs, mutations, and data actions. Connector contracts keep engine-specific access out of lower-level domains.
Fabric adds schemas, bindings, materialization, synchronization, governance, integrity, datasets, graph relationships, and security. The screen engine turns ISL documents into validated render and query plans for forms, collections, DataGrid, charts, metrics, pivots, trees, data sources, and other controls. The record module sits above screen-engine for record operations and generated form bundles.
See Data Model Publishing, Connectors, Fabric, the Interface Builder manual, and the Screen Language.
AI and Agents
AI Gateway owns routing over administrator-connected providers and models (no built-in catalog), readiness, redaction, token-usage recording, and provider clients. Workspace AI policy constrains allowed providers/models and attributes usage. AI tasks and agents call the gateway through platform services rather than binding workflow code directly to a provider SDK.
Agent definitions are loaded from governed XML catalogs. Agent runs snapshot
their policy, persist attempts/logs and leases, and are executed by the
ai-worker role through AI Gateway or connector executors. Runs can wait for
human input and resume. Agent memory has a durable JDBC adapter and workflow
service-task surface.
See AI Gateway, Agent Catalog, Agent Execution, and Agent Memory.
Documents
The document domain manages cabinets, folders, versions, storage, extraction, conversion, attachments, and workspace-aware access. Gotenberg supplies the local DOCX-to-PDF boundary. Storage and conversion are ports so deployment adapters can change without rewriting document lifecycle behavior.
See Document Management and Document Conversion.
Messaging and Operations
The durable outbox/inbox layer separates transactional state changes from Kafka-compatible publication and consumption. Node heartbeat and worker-role services coordinate runtime, timer, service-task, agent, and maintenance work.
Operations surfaces expose readiness, dashboards, metrics, maintenance, audit, and retention. Logs are separated by purpose and sanitized at the application boundary. API management additionally records and streams published-API request logs.
See Scalable Messaging, Logging and Retention, API Management, and Active-Active Deployment.
Plugins and Extension Catalogs
Configuration under conf/ describes agent catalogs, connectors, service
tasks, implementation manifests, expression functions, identity settings and
related platform policy. AI providers and enabled models come from
administrator-created connections, not a built-in provider/model catalog.
Trusted Java expression-function plugins use inflow-plugin-sdk, can be
tested with inflow-plugin-test-kit, and execute outside the API JVM through
plugin-runner. The runner is an isolation and resilience boundary, not a
hostile-code sandbox; plugins remain administrator-approved executable code.
See the Plugin Developer Guide, Plugin Runner, and First-Party Expression Functions.
Persistence and Migrations
PostgreSQL is the application runtime database in the reference deployment.
Migrations under migrations/postgres/ are the schema source of truth. Do not
copy a numeric "current migration level" into architecture prose: inspect the
ordered migration files for the candidate being deployed.
Many data connectors and publication dialects target additional engines, but that does not make the application repository layer database-independent at runtime. Database certification is engine-, capability-, and candidate- specific.
See Database Migrations.
Build and Validation Boundaries
The root Maven reactor is the supported backend build boundary. Extracted
module dependencies resolve from the reactor in full builds and from the
container's local Maven repository in focused -pl builds after installation.
Satellite plugin artifacts have a separate invoker build contract because
their packaged JARs are consumed by platform tests and the application.
platform-foundation runs that chain during initialize: it installs the SDK
and test kit before packaging/verifying the example, runner and first-party
plugins. Skipping the invoker is a bounded iteration aid, not a complete
artifact build. Maven copies an already-built studio/frontend/dist; build
Studio separately using its lockfile before packaging a distribution. See the
root build recipe.
Use the change-impact planner for iteration:
.\scripts\validate-change.ps1 -Base origin/master
.\scripts\validate-change.ps1 -Base origin/master -Execute
The canonical full backend suite is executed by the
full-container-validation workflow for the exact candidate:
.\scripts\container-test.ps1
Its fresh-database/marker admission requires a genuine CI attempt; local canonical invocation refuses before provisioning. Do not fabricate CI identity or adopt a lane database. Current human CI holds still apply. Focused checks, held-campaign runs and producer-only probes do not establish backend-green. See fresh validation admission.
Architecture or module-boundary changes also run:
.\scripts\engineering\architecture-gate.ps1
Studio requires Node 22.22.0 or newer and has separate guard, typecheck, Vitest, build, and Playwright boundaries. A focused pass proves only its named scope. Historical counts are not evidence for a new candidate.
See the Fast Engineering Workflow.
Source-of-Truth Order
When documentation disagrees, use this order:
- current code, migration files, configuration, and executable tests;
- dated certification reports for the exact candidate and boundary;
- current manuals such as this one;
- implementation plans and historical completion records;
- recovered requirements or conversations, which preserve intent but do not prove implementation.
Keep exact counts, dates, and certification language in generated or dated evidence. Keep this manual focused on durable structure and direct readers to the owning manual for changing operational detail.