From 27c5031e3bb9c0be83fa5feed4538b1ffe1662cb Mon Sep 17 00:00:00 2001 From: Mike Friesen Date: Fri, 21 Nov 2025 16:24:15 -0600 Subject: [PATCH] Updated README / added AI Agent --- AGENTS.md | 32 +++++++++++++ README.md | 139 +++++++++++++++++++++++------------------------------- 2 files changed, 91 insertions(+), 80 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..5adcc3516 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index 4ff4d4a2a..c20274046 100644 --- a/README.md +++ b/README.md @@ -11,98 +11,77 @@ -## 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. - -
-Multi-tier architecture diagram -
- -## 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.
FormKiQ architecture diagram
-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. \ No newline at end of file +MIT License - © 2020-2025 FormKiQ, Inc. See [LICENSE](LICENSE.txt) for full details.