Skip to main content

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​

FormKiQ v1.19.2 architecture: API authentication and shared Lambda handler, S3 storage, DynamoDB metadata, SNS and SQS processing, and configured capabilities. Full description in the Text view.FormKiQ v1.19.2 architecture: API authentication and shared Lambda handler, S3 storage, DynamoDB metadata, SNS and SQS processing, and configured capabilities. Full description in the Text view.

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

  1. 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.
  2. Authorize the operation. The API Lambda checks site access and operation permissions, with Open Policy Agent (OPA) policy checks when enabled.
  3. 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.
  4. 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.
  5. 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.
  6. 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 areaSource
API endpoints and shared handlerCore API stack and API key authorizer
S3, metadata, SNS, queues, handlers, and retriesCore storage stack
EventBridge actionCore EventBridge action handler
Commercial audit-event processingPlatform storage overlay
Search indexing and secretsCore Typesense stack and Platform OpenSearch stream processor
Version-specific capabilitiesv1.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.

AreaResponsibility
AWS account and regionChosen and controlled by the customer.
FormKiQ infrastructureDeployed through CloudFormation into the customer's AWS account.
Document contentStored in customer-controlled Amazon S3 buckets.
Document metadataStored in customer-controlled DynamoDB tables.
Identity and accessConfigured through Cognito, IAM, API keys, SSO, or commercial access-control options.
AWS managed servicesOperated 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​

ComponentRole
Amazon API GatewayExposes the FormKiQ APIs and supports JWT, IAM, and API key access patterns.
Amazon CognitoProvides the default user pool, admin user flow, console login, and JWT authentication.
AWS IAMEnables signed AWS-authenticated API access for backend services and AWS workloads.
API keysSupports controlled service access when API key authentication is enabled.

For details, see Security.

Storage and Metadata​

ComponentRole
Amazon S3Stores document content and supports versioning, lifecycle rules, and durable object storage.
Amazon DynamoDBStores document metadata, attributes, indexes, site data, audit data, and operational state.

For details, see Document Storage and DynamoDB Schema.

Processing and Automation​

ComponentRole
AWS LambdaRuns event-driven processing, API handlers, document actions, and lightweight automation.
Amazon ECS on FargateSupports container-based workloads where longer-running or specialized runtime processing is needed.
Rulesets and workflowsRoute 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 AttributeValuesDescription
typecreate, update, deleteDocument operation.
siteIddefault, customSite 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:

  1. A user or service calls the FormKiQ API through API Gateway.
  2. API Gateway authenticates the request using JWT, IAM, or API key authentication.
  3. FormKiQ validates access to the target site.
  4. Document content is stored in Amazon S3, either inline for smaller files or through a presigned S3 upload flow.
  5. Document metadata, attributes, path, and state are stored in DynamoDB.
  6. Document lifecycle events are emitted through the event system.
  7. Optional rulesets, workflows, OCR, classification, or module actions process the document.
  8. Search indexes are updated when search features are enabled.
  9. 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 modelCommon use
JWTInteractive users, FormKiQ Web, and first API tests.
AWS IAMServer-side AWS workloads, automation, and service-to-service access.
API keyControlled service access where API keys are enabled.
SSO and custom identity optionsCommercial 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 typePrimary serviceCommon recovery control
Document contentAmazon S3S3 versioning, lifecycle rules, replication, and backup strategies.
Document metadataAmazon DynamoDBPoint-in-time recovery and table backups.
Users and groupsAmazon CognitoExport and account recovery planning.
Search indexesTypesense or OpenSearch, when enabledReindexing, snapshots, or service-specific backup strategy.
InfrastructureCloudFormationTemplate 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:

  • ThrottledRequests
  • ConsumedReadCapacityUnits
  • ConsumedWriteCapacityUnits
  • SuccessfulRequestLatency
  • ReadThrottleEvents
  • WriteThrottleEvents

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, or KeyApiUrl.
  • 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​