Overview
FormKiQ is a flexible, API-first document management platform deployed into your AWS account. It uses AWS managed services for document storage, metadata, APIs, identity, events, automation, and optional search so teams can build document-centric workflows without operating a traditional document management stack.
At a high level, FormKiQ stores document content in Amazon S3, stores document metadata and indexes in Amazon DynamoDB, exposes APIs through Amazon API Gateway, authenticates users and services through multiple auth models, and emits document lifecycle events for automation.
Architecture


Platform architecture in text
FormKiQ v1.19.2 runs in your AWS account. AWS CloudFormation provisions the infrastructure, and Amazon CloudWatch provides monitoring and logs. The FormKiQ Console is served through Amazon CloudFront and Amazon S3. The Console, other applications, SDKs, FormKiQ CLI, and AWS workloads access the platform through the FormKiQ API.
API access and document processing
- Authenticate through Amazon API Gateway. Callers use a JWT endpoint with Amazon Cognito by default, an IAM endpoint with AWS Signature Version 4, or an API key endpoint supporting custom claims. All three invoke the same FormKiQ API Lambda.
- Authorize the operation. The API Lambda checks site access and operation permissions, with Open Policy Agent (OPA) policy checks when enabled.
- Store content and metadata. Amazon S3 stores document content. Amazon DynamoDB stores metadata, JSON attributes, and operational state. The API coordinates access to these stores and publishes document or action notifications through Amazon SNS.
- Handle object events. S3 object events trigger FormKiQ event handlers. Lambda functions and staging or update queues support ingestion and document-state updates. The handlers also publish events to SNS.
- Process document actions. An SNS action subscription sends work to an Amazon SQS queue. The action Lambda processes that work and updates document state in DynamoDB.
- Handle processing failures. Staging, update, and action work that exhausts its configured queue retries is sent to the SQS dead-letter queue for investigation and recovery.
Configured capabilities
- Amazon EventBridge: document actions can send events to EventBridge. The commercial platform also supports audit-event routing.
- Processing modules: configured features and modules support OCR, AI processing, antivirus scanning, document generation, e-signatures, workflows, and reviews.
- OpenSearch or Typesense: DynamoDB streams feed an indexing Lambda that updates the configured search engine. This indexing path is separate from the document-action queue.
The diagram's orange connectors identify configured capabilities; availability depends on the deployment, edition, and installed modules. This is a logical API view. See Document Storage for file-transfer details and Security for access-control configuration.
This logical diagram follows the v1.19.2 source baseline. JWT, IAM, and API key endpoints invoke the same FormKiQ API Lambda. The API handles site access and operation permissions, document metadata, and content requests, with OPA policy checks when enabled. The diagram shows the API as the application entry point; file-transfer details are covered in Document Storage.
S3 event handlers update document state and publish document or action events to SNS. An action-event subscription feeds SQS and the document-action Lambda. EventBridge is a configured integration path: explicit EVENTBRIDGE actions can send events to a selected bus, and the commercial platform can route audit events through its document event bus. Optional search uses indexing Lambdas and DynamoDB streams; it does not receive raw S3 object events directly.
The diagram highlights operation-specific permissions, custom API key claims, JSON attributes, and document-processing capabilities. Orange connectors identify capabilities that depend on configuration and edition. Console hosting appears with the callers, while CloudFormation deployment and CloudWatch monitoring apply across the AWS account. The view groups related resources and omits response arrows, some state updates, and individual module internals; it is not a VPC or subnet topology.
Diagram sources
The source snapshots are pinned so the diagram can be reviewed independently of later changes to the development branches. The Core snapshot is the submodule commit recorded by the commercial Platform v1.10.2 branch used with FormKiQ v1.19.2.
| Diagram area | Source |
|---|---|
| API endpoints and shared handler | Core API stack and API key authorizer |
| S3, metadata, SNS, queues, handlers, and retries | Core storage stack |
| EventBridge action | Core EventBridge action handler |
| Commercial audit-event processing | Platform storage overlay |
| Search indexing and secrets | Core Typesense stack and Platform OpenSearch stream processor |
| Version-specific capabilities | v1.19.2 release notes source |
Deployment Boundary
FormKiQ runs in the customer's AWS account. This is a core architectural difference from vendor-hosted SaaS document systems.
| Area | Responsibility |
|---|---|
| AWS account and region | Chosen and controlled by the customer. |
| FormKiQ infrastructure | Deployed through CloudFormation into the customer's AWS account. |
| Document content | Stored in customer-controlled Amazon S3 buckets. |
| Document metadata | Stored in customer-controlled DynamoDB tables. |
| Identity and access | Configured through Cognito, IAM, API keys, SSO, or commercial access-control options. |
| AWS managed services | Operated by AWS under the customer's AWS account and service configuration. |
This model gives teams control over data residency, AWS region selection, security posture, networking, monitoring, backup strategy, and integration patterns.
Who FormKiQ Is For
FormKiQ is designed for:
- Developers building document-centric applications using APIs and SDKs
- Architects seeking scalable AWS-native document infrastructure
- IT teams that want deployment control and managed AWS services
- Operations teams automating document-heavy workflows
- Organizations that need secure, auditable, and extensible document storage
What Makes FormKiQ Different
Unlike traditional document management systems, FormKiQ is:
- API-first: designed for integration and embedded document workflows
- AWS-native: built on AWS managed services and deployed in the customer's AWS account
- Event-driven: document actions can trigger workflows, queues, and downstream integrations
- Composable: capabilities such as search, OCR, workflows, and modules can be enabled as needed
- Serverless-oriented: core services use managed, elastic infrastructure; optional components may use ECS/Fargate or search services when required
Core Capabilities
- Document storage and retrieval through APIs and FormKiQ Web
- Metadata management with tags, attributes, schemas, and classifications
- Search by metadata, attributes, tags, and optional full-text indexes
- Document processing workflows, rulesets, queues, OCR, and classification
- Event-driven automation through document lifecycle events
- Multi-tenant support through sites and access-control boundaries
- API integration through JWT, IAM, and API key authentication models
Core Components
API and Identity
| Component | Role |
|---|---|
| Amazon API Gateway | Exposes the FormKiQ APIs and supports JWT, IAM, and API key access patterns. |
| Amazon Cognito | Provides the default user pool, admin user flow, console login, and JWT authentication. |
| AWS IAM | Enables signed AWS-authenticated API access for backend services and AWS workloads. |
| API keys | Supports controlled service access when API key authentication is enabled. |
For details, see Security.
Storage and Metadata
| Component | Role |
|---|---|
| Amazon S3 | Stores document content and supports versioning, lifecycle rules, and durable object storage. |
| Amazon DynamoDB | Stores document metadata, attributes, indexes, site data, audit data, and operational state. |
For details, see Document Storage and DynamoDB Schema.
Processing and Automation
| Component | Role |
|---|---|
| AWS Lambda | Runs event-driven processing, API handlers, document actions, and lightweight automation. |
| Amazon ECS on Fargate | Supports container-based workloads where longer-running or specialized runtime processing is needed. |
| Rulesets and workflows | Route documents into processing, review, approval, or automation paths. |
Event System
Document Events
FormKiQ emits events when documents are created, updated, deleted, or processed. These events allow teams to extend FormKiQ without tightly coupling custom code to the core document API.
Common event attributes include:
| Message Attribute | Values | Description |
|---|---|---|
type | create, update, delete | Document operation. |
siteId | default, custom | Site or tenant identifier. |
Event-driven architecture uses:
- Amazon SNS for event distribution and fan-out
- Amazon SQS for reliable processing, buffering, and dead-letter queue handling
- Amazon EventBridge for event routing and broader AWS integration patterns, where configured
For failure handling, see Dead Letter Queue.
Search and Indexing
FormKiQ supports basic metadata search through DynamoDB-backed access patterns. Optional enhanced search capabilities can use search engines such as Typesense or OpenSearch, depending on deployment and commercial module configuration.
Search capability affects:
- Installation choices, especially whether a VPC stack is required
- Runtime cost, because search clusters or containers may have dedicated capacity
- Query behavior, because full-text search differs from tag or attribute lookup
- Scaling strategy, because indexing and query throughput depend on the search backend
For search behavior, see Search. For cost impact, see Costs.
FormKiQ Web
FormKiQ Web provides a web interface for document access, administration, and user workflows. In most AWS regions it is deployed with the main FormKiQ stack. AWS GovCloud (US) has separate console deployment considerations.
For details, see FormKiQ Web.
Request and Document Flow
A typical API-driven document flow looks like this:
- A user or service calls the FormKiQ API through API Gateway.
- API Gateway authenticates the request using JWT, IAM, or API key authentication.
- FormKiQ validates access to the target site.
- Document content is stored in Amazon S3, either inline for smaller files or through a presigned S3 upload flow.
- Document metadata, attributes, path, and state are stored in DynamoDB.
- Document lifecycle events are emitted through the event system.
- Optional rulesets, workflows, OCR, classification, or module actions process the document.
- Search indexes are updated when search features are enabled.
- Users or systems retrieve the document, metadata, content URL, audit data, or search results through the API.
Identity and Access
FormKiQ supports multiple authentication models because different integrations need different access patterns.
| Authentication model | Common use |
|---|---|
| JWT | Interactive users, FormKiQ Web, and first API tests. |
| AWS IAM | Server-side AWS workloads, automation, and service-to-service access. |
| API key | Controlled service access where API keys are enabled. |
| SSO and custom identity options | Commercial deployments with enterprise identity requirements. |
Access is commonly scoped by site. The default site is named default, and additional sites can be used for multi-tenant or segmented document spaces.
For details, see Security and Multi-Tenant vs Multi-Instance.
Networking and Optional VPC
Core FormKiQ deployments use AWS managed services and do not require customers to operate application servers. Some optional capabilities, such as Typesense, OpenSearch, private networking, or enterprise-specific integrations, may require VPC resources.
The optional VPC stack is installed separately and then attached to the main FormKiQ stack through the VpcStackName parameter.
For installation steps, see Quick Start (AWS).
Observability and Operations
FormKiQ uses AWS-native operational tooling:
- CloudFormation stack events for deployment and update status
- Amazon CloudWatch Logs for Lambda and service logs
- Amazon CloudWatch Metrics for API Gateway, Lambda, DynamoDB, queues, and other AWS services
- Amazon SQS dead-letter queues for failed asynchronous processing
- Amazon SNS alerts for DLQ and operational notifications, where configured
- Audit and user activity data stored by FormKiQ for governance and reporting use cases
For operational guidance, see Updates, Upgrades, and Rollbacks, Backup and Recovery, and Dead Letter Queue.
Backup and Recovery
FormKiQ relies on AWS-native durability and recovery controls.
| Data type | Primary service | Common recovery control |
|---|---|---|
| Document content | Amazon S3 | S3 versioning, lifecycle rules, replication, and backup strategies. |
| Document metadata | Amazon DynamoDB | Point-in-time recovery and table backups. |
| Users and groups | Amazon Cognito | Export and account recovery planning. |
| Search indexes | Typesense or OpenSearch, when enabled | Reindexing, snapshots, or service-specific backup strategy. |
| Infrastructure | CloudFormation | Template history, stack updates, and rollback behavior. |
For details, see Backup and Recovery.
FormKiQ Concepts
These concepts appear throughout FormKiQ APIs, security rules, workflows, and architecture documentation.
Documents
A document is the primary entity in FormKiQ. It includes:
- Binary content stored in Amazon S3
- Metadata and attributes stored in DynamoDB
- A unique
documentId - A virtual path
- Optional tags, attributes, actions, versions, and workflow state
Sites
A site represents an isolated namespace within a FormKiQ deployment.
- Documents belong to exactly one site
- Sites support multi-tenant architectures
- Access control is enforced at the site level
- The default site is named
default
Attributes
Attributes are structured metadata fields attached to documents.
- Used for filtering, querying, validation, and automation
- Can be used with schemas and classifications
- Support richer document models than simple tags
Rulesets and Workflows
Rulesets and workflows automate document handling. They can route documents, trigger processing, assign review queues, or connect document events to downstream business processes.
Architecture Principles
FormKiQ follows AWS Well-Architected Framework principles.
Operational Excellence
- Infrastructure as Code through CloudFormation
- Event-driven architecture
- CloudWatch-based logging and metrics
- Designed update and rollback paths
Security
- Encryption in transit and at rest
- JWT, IAM, and API key authentication options
- Site-level access boundaries
- Role-based and advanced access-control options
- Customer-controlled AWS account and region
Reliability
- Managed AWS services with built-in durability
- Decoupled asynchronous processing
- Dead-letter queues for failed message handling
- DynamoDB point-in-time recovery and S3 versioning
Performance Efficiency
- Elastic managed services
- Presigned S3 upload paths for larger files
- DynamoDB access patterns for metadata and attributes
- Optional search engines for full-text search needs
Cost Optimization
- Serverless and managed-service pricing for core components
- S3 lifecycle and storage-tier options
- DynamoDB on-demand capacity by default
- Optional search and module costs based on enabled capabilities
Scaling FormKiQ Components
FormKiQ scales through the AWS services that make up the deployment. For large imports, high API volume, search-heavy workloads, or document processing bursts, review each service boundary rather than treating the platform as a single capacity pool.
Amazon S3
Document content is stored in S3. S3 is highly scalable, but workload design still matters.
- Use presigned upload flows for larger files.
- Use lifecycle policies to control storage cost over time.
- Monitor request patterns and data transfer for large migrations.
- Consider replication or backup requirements for recovery and data residency.
Amazon DynamoDB
Document metadata, attributes, and indexes are stored in DynamoDB.
By default, FormKiQ uses on-demand capacity mode, which provides:
- Automatic scaling based on traffic
- No capacity planning for normal traffic patterns
- Pay-per-request pricing
Although on-demand capacity is fully managed, it is not unlimited. DynamoDB tables and global secondary indexes scale independently based on recent traffic patterns. Extremely sharp increases or sustained bursts can still be throttled if they exceed service limits or adaptive scaling windows.
Key considerations:
- Each table and each global secondary index has its own throughput behavior.
- High-cardinality access patterns scale better than hot partitions.
- Large migrations should use controlled concurrency.
- Throttling can surface as elevated API latency or failed writes.
Monitor DynamoDB capacity pressure using CloudWatch metrics such as:
ThrottledRequestsConsumedReadCapacityUnitsConsumedWriteCapacityUnitsSuccessfulRequestLatencyReadThrottleEventsWriteThrottleEvents
AWS Lambda
Lambda scales concurrently as events and API requests increase, subject to account and regional concurrency limits.
- Confirm Lambda concurrency quotas before high-volume deployments or imports.
- Monitor duration, errors, throttles, and iterator age where applicable.
- Long-running or specialized workloads may be better suited to ECS/Fargate.
Amazon API Gateway
API Gateway handles request routing, throttling, authentication integration, and logging.
- Watch request count, latency, integration latency, and 4xx/5xx errors.
- Use the correct API URL for the authentication model:
HttpApiUrl,IamApiUrl, orKeyApiUrl. - For high-volume integrations, review API throttling and client retry behavior.
Amazon SQS and SNS
Queues and topics decouple document processing from API requests.
- Monitor queue depth, message age, processing errors, and DLQs.
- Use DLQ redrive carefully after fixing the underlying processing issue.
- For high-volume event consumers, use filtering and batching where appropriate.
Search Backends
Full-text search scaling depends on the configured backend, such as Typesense or OpenSearch.
- Plan capacity based on document volume, indexing rate, query rate, and retention needs.
- Monitor indexing failures and query latency.
- Reindexing may be required after schema, analyzer, or backend changes.
Migration and Import Workloads
Large imports should be treated as controlled workloads.
- Start with a small batch and validate metadata, permissions, and search behavior.
- Increase concurrency gradually.
- Monitor API Gateway, Lambda, DynamoDB, SQS, and search metrics.
- Account for source-system limits as well as FormKiQ and AWS service limits.
For migration guidance, see Migration and Data Import.
Where to Go Next
- Install FormKiQ: Quick Start (AWS)
- Make the first API request: API Walkthrough
- Review security and access: Security
- Understand storage: Document Storage
- Plan tenancy: Multi-Tenant vs Multi-Instance
- Estimate AWS usage: Costs
- Prepare operations: Updates, Upgrades, and Rollbacks