Skip to content

Updated README / added AI Agent #445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mfriesen wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated README / added AI Agent #445

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Repository Guidelines

## Project Structure & Module Organization
- Multi-module Gradle build (see `settings.gradle`): AWS adapters (`aws-*`), Lambdas (`lambda-*`, `lambda-*-graalvm`), shared libs (`fkq-*`, `http*`, `strings`), and UI (`console`).
- Source lives under each module’s `src/main/java` and `src/main/resources`; tests under `src/test/java` with fixtures in `src/test/resources`.
- Infrastructure templates and assets: `src/main/resources/cloudformation/`, `docs/`, `images/`, `docker/` and `docker-compose*.yml` for local stacks.

## Build, Test, and Development Commands
- `./gradlew clean build` — compile all modules, generate CloudFormation artifacts, and run unit tests.
- `./gradlew test` — run tests only; respects `-Ptestregion`, `-Ptestprofile`, `-Ptestappenvironment`, `-Ptestchatgptapikey` when AWS context is required.
- `./gradlew spotlessCheck` — verify formatting; use `spotlessApply` before pushing.
- `./gradlew licenseReport` — regenerate license inventory under `docs/licenses/`.

## Coding Style & Naming Conventions
- Java code formatted via Spotless/Eclipse profile (`spotless.eclipseformat.xml`); let the formatter decide indentation and wrapping.
- Use descriptive, AWS-aligned names for modules/resources (e.g., `lambda-s3`, `aws-dynamodb`), and keep package names consistent with service boundaries.
- Prefer immutable data where practical; validate inputs at module edges (API handlers, S3 triggers, event listeners).

## Testing Guidelines
- Default to JUnit tests in `src/test/java`; mirror package structure of the code under test.
- When tests hit AWS-dependent flows, supply Gradle properties (`-Ptestregion`, etc.) pointing to sandbox credentials/profiles.
- Mark slow/integration tests with JUnit tags to allow selective execution (e.g., `./gradlew test -DexcludeTags=integration`).
- Add fixtures in `src/test/resources`; avoid hardcoding secrets.

## Commit & Pull Request Guidelines
- Commit messages follow short, imperative summaries and often include issue references (e.g., `#443 - Enable a "Group" for API Keys`).
- PRs should describe scope, risks, and deployment impacts; link issues/tickets; add screenshots for `console` UI changes.
- Update docs or CloudFormation templates when behavior or contract changes; note backward-compatibility and migration steps.

## Security & Configuration Tips
- Do not commit AWS credentials; rely on `~/.aws/credentials` profiles or runtime environment vars.
- Keep generated CloudFormation outputs reproducible: run Gradle tasks instead of manual edits, and verify hashes produced by `ytt` specs.
139 changes: 59 additions & 80 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,98 +11,77 @@

</div>

## Enterprise-Grade Document Management Layer

FormKiQ is a production-ready document management platform built on AWS serverless infrastructure. Deploy a complete document layer alongside your application's data tier—handling storage, metadata, search, and access control without the complexity of building it yourself.

**Fully deployed in your AWS account** for complete control and security.

<div align="center" style="margin: 30px;">
<img src="https://raw.githubusercontent.com/formkiq/formkiq-core/master/docs/images/multi-tier-architecture.png" style="width:600px;" alt="Multi-tier architecture diagram" />
</div>

## Why FormKiQ?

Traditional approaches to document storage create technical debt and operational overhead:

**Database Storage Limitations:**
- Increased storage costs and database bloat
- Performance degradation under load
- Limited access control and audit capabilities

**Raw S3 Storage Gaps:**
- No built-in metadata management or tagging system
- Missing full-text search capabilities
- Lack of fine-grained access controls and versioning

**FormKiQ bridges these gaps** with a complete, API-first document management system built on proven AWS managed services—automatically scaling to handle enterprise workloads.

## Core Features

**Document Management**
- RESTful API with comprehensive document operations
- Advanced metadata and custom tagging
- Full-text search with OCR support
- Document versioning and audit trails

**Enterprise Ready**
- Serverless architecture (zero server management)
- Auto-scales to thousands of concurrent requests
- Multi-tenant and multi-instance deployment options
- SOC 2 compatible infrastructure

**Developer Experience**
- Official SDKs for Java and Python
- OpenAPI specification for custom integrations
- Comprehensive documentation and tutorials
- Web-based UI for document management
# FormKiQ Core

FormKiQ is a production-ready document management platform built on AWS serverless infrastructure that deployed in **your** AWS account. Deploy a complete API-first document layer alongside your application's data tier—handling storage, metadata, search, and access control without the complexity of building it yourself.

## Who it’s for
- Teams building secure file workflows that must remain in their AWS accounts.
- Regulated workloads needing auditability, retention, and least-privilege access.
- SaaS platforms delivering per-tenant document storage with isolation and signed links.
- Ops/support teams needing fast search over PDFs and images without custom pipelines.

## Capabilities at a glance
- Ingest via API Gateway, S3, or email; optional OCR pipeline for images/PDFs.
- Metadata and tagging for every document plus custom attributes.
- Full-text/OCR search and filters; show only what each user/tenant should see.
- Versioning, retention, and audit trails built-in; lifecycle controls via policies.
- Event hooks via Lambda/SNS/SQS/EventBridge to enrich, classify, notify.
- SDKs for Java and Python, plus OpenAPI for other languages.

## Why teams choose FormKiQ
- Data and keys stay in your AWS account; IAM-first access control and audit trails.
- Built-in metadata/tagging, OCR search, versioning, and retention—no custom boilerplate.
- Serverless stack that auto-scales; no servers to patch or capacity to size.
- Multi-tenant ready and SOC 2–aligned design for regulated workloads.

## Common use cases
- Records and retention vaults for HR, legal, and finance with audit trails and versioning.
- Intelligent ingestion: drop into S3/email/API, OCR + metadata tagging, and route via events.
- Compliance-focused file storage where data must remain in your AWS account with IAM-scoped access.
- Customer/partner file portals with per-tenant isolation and signed access links.
- Workflow enrichment: trigger Lambdas on uploads to classify, enrich metadata, notify via SNS/SQS/EventBridge.
- Searchable knowledge stores over PDFs/images for support and operations teams.

## Deployment options
- Deploy to your AWS account via CloudFormation (Quickstart below).
- Evaluate in the hosted demo environment (read-only).
- Inquire about managed workspaces if you prefer a turnkey setup.

## Quick Start

Get FormKiQ running in your AWS account in minutes:

1. **[Follow our Quickstart Guide](https://docs.formkiq.com/docs/getting-started/quick-start)** - Deploy via CloudFormation
2. **[Try the Demo](https://explore.tryformkiq.com/)** - Explore features with read-only access
- Email: `demo@formkiq.com`
- Password: `tryformkiq`
3. **[Walk through the API](https://docs.formkiq.com/docs/getting-started/api-walkthrough)** - Integration examples

Or **[sign up for a managed workspace](https://formkiq.com)** to evaluate FormKiQ without AWS setup.
1. **AWS deploy**: [Quickstart Guide](https://docs.formkiq.com/docs/getting-started/quick-start) (CloudFormation).
2. **Hosted demo**: [Explore](https://explore.tryformkiq.com/) — Email: `demo@formkiq.com`, Password: `tryformkiq`.
3. **API walkthrough**: [Step-by-step](https://docs.formkiq.com/docs/getting-started/api-walkthrough) to integrate quickly.
- Requirements: AWS account, CLI/CloudFormation access, Java/Gradle for local builds.

## Architecture

FormKiQ leverages AWS serverless services for reliability and scale:
Serverless on AWS: Lambda + API Gateway + S3 + DynamoDB + OpenSearch, with optional modules for OCR, Typesense, and event handling.

<div align="center" style="margin: 30px;">
<img src="https://raw.githubusercontent.com/formkiq/formkiq-core/master/docs/images/formkiq_architecture.png" style="width:600px;" alt="FormKiQ architecture diagram" />
</div>

Built on: Lambda, API Gateway, S3, DynamoDB, OpenSearch, and other AWS managed services.

## Client SDKs

Official SDKs generated from our OpenAPI specification:

- **[Java SDK](https://github.com/formkiq/formkiq-client-sdk-java)** - Full-featured Java client
- **[Python SDK](https://github.com/formkiq/formkiq-client-sdk-python)** - Pythonic interface for FormKiQ
## Project structure & commands
- Modules: `lambda-*` and `lambda-*-graalvm` functions, AWS adapters (`aws-*`), shared libs (`fkq-*`, `http*`, `strings`), console UI (`console`).
- Templates/assets: `src/main/resources/cloudformation`, `docs/`, `images/`, `docker/`.
- Build/test: `./gradlew clean build` (full build + tests), `./gradlew test` (tests only), `./gradlew spotlessCheck` (format), `./gradlew licenseReport` (license inventory).

Additional language support available via [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator).
## Security, compliance, and scale
- Data, encryption keys, and access policies remain in your AWS account; IAM secures every interaction.
- Versioning and audit trails support retention and evidence needs for SOC 2/HIPAA-style controls.
- Serverless footprint scales with demand; designed for thousands of concurrent requests.

## Resources

**Documentation**
- [Complete Documentation](https://docs.formkiq.com)
- [API Reference](https://docs.formkiq.com/docs/category/api-reference)
- [Tutorials](https://docs.formkiq.com/docs/category/tutorials)
- [How-To Guides](https://docs.formkiq.com/docs/category/how-to)
## Client SDKs
- **[Java SDK](https://github.com/formkiq/formkiq-client-sdk-java)** — best for JVM backends.
- **[Python SDK](https://github.com/formkiq/formkiq-client-sdk-python)** — scripting/data workflows.
- Other languages via [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) using the published spec.

**Community & Support**
- [Blog](https://blog.formkiq.com) - Updates and technical insights
- [GitHub Issues](https://github.com/formkiq/formkiq-core/issues) - Bug reports and feature requests
- [Enterprise Support](https://www.formkiq.com/pricing) - Professional support and SLAs
## Resources & support
- Docs: [Complete Documentation](https://docs.formkiq.com), [API Reference](https://docs.formkiq.com/docs/category/api-reference), [Tutorials](https://docs.formkiq.com/docs/category/tutorials), [How-To Guides](https://docs.formkiq.com/docs/category/how-to)
- Updates: [Blog](https://blog.formkiq.com)
- Issues/questions: [GitHub Issues](https://github.com/formkiq/formkiq-core/issues)
- Enterprise inquiries: [Contact](mailto:info@formkiq.com) or [formkiq.com](https://www.formkiq.com/pricing)

## License

MIT License - © 2020-2025 FormKiQ, Inc.

See [LICENSE](LICENSE.txt) for full details.
MIT License - © 2020-2025 FormKiQ, Inc. See [LICENSE](LICENSE.txt) for full details.
Loading