OpenFrame Documentation
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
Flamingo Raises $4.5M Seed Round Β· Led by Vertex Ventures, bringing total funding to $6.7M to build the open, AI-native layer for IT and security.
Deployment guides, the CLI reference, architecture and admin guides for OpenFrame
ic# Contributing Guidelines
OpenFrame OSS Tenant is a service repository (bash, java, rust) that assembles Spring Boot entry points, shared configuration, and Kubernetes/Argo CD manifests into the deployable OpenFrame tenant stack. Most domain logic is consumed from the OpenFrame OSS Library (pinned at 7.0.11 for Maven artifacts, v0.0.5 for the Rust agent library). This repository itself publishes nine Maven artifacts (com.openframe:openframe-api, openframe-authorization-server, openframe-client, openframe-config, openframe-external-api, openframe-gateway, openframe-management, openframe-stream, openframe-test) and one Cargo crate (openframe_client). No other repository is recorded as a downstream consumer of these artifacts, so changes here are evaluated primarily against the automated review rules and against the services that live in this repository.
This document describes how to propose, format, and get a change merged. For environment setup, see Development and Environment Setup. For the system's overall shape, see Architecture Overview and the generated Ecosystem reference.
This project does not use GitHub Issues or GitHub Discussions. Planning, support, and feature discussion happen on the OpenMSP Slack community.
Code style in this repository is enforced by an automated reviewer (𦩠Flamingo Code Review) running against a published rule catalog. The rules below are the ones most relevant to day-to-day contributions; they are drawn from the active, CI-enforced catalog for this repository and apply across the Java services under openframe/services, the Rust client under clients/openframe-client, and the CI workflows under .github/workflows.
openframe/services/**)The parent pom.xml targets Java 25 and Spring Boot 4.1.1 (via spring-boot-starter-parent), with Spring Cloud 2025.1.3 and Lombok 1.18.48. Keep these conventions when touching Java code:
@Service, @Component, @DgsComponent) must declare dependencies as private final fields with Lombok's @RequiredArgsConstructor, and must use @Slf4j for logging. Field injection via @Autowired and hand-rolled Logger fields are not permitted.null is never returned or passed. Exceptions must be unchecked (RuntimeException subclasses), with no throws clauses in signatures. Domain errors get dedicated exception types, handled centrally in one @RestControllerAdvice.Optional is a return type only, consumed as a pipeline (map/filter/ifPresent/orElseThrow), never stored in a field or accepted as a parameter, and .get() is never called directly.private static final constants.NoMethodCallAsArgument, priority 1, fails the build). Exemptions are limited to logger arguments, annotation values, and enum constants, and any per-call suppression needs a @SuppressWarnings("PMD.NoMethodCallAsArgument") plus a justification comment.&&, ||, a ternary, or a stream chain must be extracted into a named private predicate method.@Value properties never have inline defaults (@Value("${openframe.timeout}"), not @Value("${openframe.timeout:30}")) β missing configuration must fail fast at startup. Prefer @ConfigurationProperties with Lombok @Data for grouped configuration.TenantAwareMongoTemplate, TenantScopedCassandraTemplate, etc.) must carry @ConditionalOnProperty(name = "openframe.tenant-isolation.enabled", havingValue = "true"). Spring Data repository interfaces are exempt from this gate.openframe.oss-tenant.kafka.topics.{inbound|outbound}.<logical-name> in the service's configs/base/*.yml file, never hardcoded; @KafkaListener methods in openframe-stream must specify containerFactory = "ossTenantKafkaListenerContainerFactory".TenantScoped marker interface, and @Document classes need the full Lombok quartet: @Data @Builder @NoArgsConstructor @AllArgsConstructor.@TestConfiguration classes must mock every infrastructure bean (MongoTemplate, RedisTemplate, KafkaTemplate, CassandraTemplate, Pinot Connection, etc.) with @Bean @Primary and Mockito.mock(). PasswordEncoder is the one exception that should stay a real BCryptPasswordEncoder.Reuse existing Spring/JDK utilities (CollectionUtils.isEmpty, StringUtils.hasText, Objects.requireNonNull) instead of hand-rolled null/empty checks, and when duplication starts to form, refactor it as part of the current change rather than deferring it.
pom.xml)The OpenFrame OSS Library dependency (com.openframe.oss:*, currently 7.0.11) is centralized in the <openframe.libs.version> property in the root pom.xml. When developing against an unreleased library change, use the local 999-SNAPSHOT handshake: build and install the library locally as 999-SNAPSHOT, point <openframe.libs.version> at 999-SNAPSHOT for local testing, and never commit a version bump, a new snapshot release, or a rewritten dependency coordinate for that workflow.
clients/openframe-client)clients/openframe-client/Cargo.toml defines the openframe-client binary (crate openframe_client, edition 2021), which depends on openframe-agent-lib pinned to tag v0.0.5 from openframe-oss-lib. Use the VS Code tasks in .vscode/tasks.json for local iteration: rust-build (debug build), rust-build-release, rust-test, rust-check, and rust-clippy. .vscode/settings.json configures rust-analyzer to check on save using clippy with all features enabled β keep code clippy-clean before pushing.
.github/workflows/**)Changes to GitHub Actions workflows in this repository are themselves reviewed against the catalog:
actions/checkout step must set persist-credentials: false.docker buildx build steps must run inside nick-fields/retry@v4 with max_attempts: 3, retry_wait_seconds: 5, timeout_minutes: 30, and the build command passed via command:, not run: β see the build_images job in .github/workflows/release.yml for the established pattern.--platform linux/amd64,linux/arm64 and release builds add --provenance=false --sbom=true (the GHCR OCI layout this org uses does not support provenance attestation manifests).release job in .github/workflows/release.yml must stay gated so that GitHub Release creation happens only on workflow_dispatch, never automatically from a push; the file must keep the name release.yml..github/workflows/flamingo-code-review.yml is generated by the Flamingo hub and is byte-identical across every reviewed repository β never edit it by hand; it carries its own "do not edit by hand" header.download_and_verify function, checked against the hub's manifest digest β never curl | bash, and never a hash pinned directly in workflow YAML.Run get_code_rules (or ask the reviewer via @flamingo-review, see below) for the full, current rule set before large changes β the catalog evolves and this document only summarizes the rules most commonly hit.
Branch names are not constrained by a fixed enum in this repository, but align with ownership boundaries defined in .github/CODEOWNERS:
/openframe/ (all backend services) is owned by @flamingo-stack/backend-engineers./clients/openframe-client/ (the Rust agent) is owned by @flamingo-stack/client-engineers./configs/ is owned by @flamingo-stack/backend-engineers, with /configs/base/ requiring sign-off from @flamingo-stack/tech-leads and @flamingo-stack/tech-heads-of (last-match-wins: more specific patterns listed below broader ones)./manifests/ (Kubernetes/Argo CD) is owned by @flamingo-stack/devops-engineers..github/CODEOWNERS itself is owned by @flamingo-stack/devops-engineers.Name your branch so the area it touches and the author's intent are clear, for example backend/<short-description> for an openframe/services change, client/<short-description> for the Rust agent, or manifests/<short-description> for Helm/Argo CD work. Avoid branch names starting with ai-fix/, setup/, or code-documentation/ β these prefixes are reserved by the automated documentation and review tooling in .github/workflows/code-documentation.yml.
main (the repository's default branch).flamingo-stack/openframe-oss-tenant at github.com/flamingo-stack/openframe-oss-tenant/pulls.docs/** and **.md) triggers the code-graph rebuild in .github/workflows/code-documentation.yml, which keeps the generated Ecosystem reference current for every PR opened afterward.manifests/**, openframe/**, integrated-tools/**, pom.xml, or clients/** on main trigger .github/workflows/release.yml, which builds images, the Rust client binaries, and the Helm chart, and can cut a tagged release via workflow_dispatch.This repository runs 𦩠Flamingo Code Review (.github/workflows/flamingo-code-review.yml) against every pull request. Key things to know as a contributor:
@flamingo-review on the PR, or apply the flamingo-review label from the sidebar. @flamingo-review full (or checking "Review the whole diff again") re-reads the whole cumulative diff instead of only the delta since the last review.flamingo-review-always label subscribes a PR to review on every push (synchronize) β useful for a large or risky refactor.OWNER, MEMBER, or COLLABORATOR association can trigger a review via comment; checkbox edits must come from a human, not a bot.get_code_rules), scoped to the languages and paths your PR touches..github/workflows/cleanup.yml runs on a schedule and deletes unprotected branches with no commits in the last 60 days. Delete or merge your branch promptly after merge to avoid relying on this; it is a safety net, not a workflow step to depend on.
There is no commit-lint enforcement visible in this repository's workflows, but keep commits reviewable and bisectable:
Gate tenant-scoped repository with ConditionalOnProperty rather than Fixed stuff).openframe-gateway: add route for /clients/** or clients/openframe-client: bump openframe-agent-lib to v0.0.5.configs/base change and an unrelated manifests/tenant change) in a single commit β CODEOWNERS reviews by path, and mixed commits make scoped review harder.Before requesting review (or checking the reviewer's invitation box), verify:
Scope and ownership
openframe/, clients/openframe-client/, configs/, or manifests/), matching .github/CODEOWNERS.configs/base/, you understand it needs sign-off from @flamingo-stack/tech-leads or @flamingo-stack/tech-heads-of.Java services
@Autowired) or manual Logger fields β constructor injection via @RequiredArgsConstructor and @Slf4j.null returned or passed; Optional used only as a pipeline return type.@Value property has an inline default; grouped configuration uses @ConfigurationProperties.@ConditionalOnProperty(name = "openframe.tenant-isolation.enabled", havingValue = "true") where applicable.openframe.oss-tenant.kafka.topics.* configuration, not hardcoded strings; openframe-stream listeners use ossTenantKafkaListenerContainerFactory.@Document Mongo classes implement TenantScoped (if tenant data) and carry the full Lombok quartet.@RestControllerAdvice.@TestConfiguration classes mock infrastructure beans with @Bean @Primary.Rust client
cargo clippy is clean for the files you touched.openframe-agent-lib version bump in clients/openframe-client/Cargo.toml is intentional and matches a real tagged release of openframe-oss-lib.CI workflows
actions/checkout steps you added or touched set persist-credentials: false.docker buildx build step is wrapped in nick-fields/retry@v4 with the standard retry configuration, uses command: (not run:), and targets linux/amd64,linux/arm64..github/workflows/flamingo-code-review.yml.download_and_verify, never curl | bash.release job still gates GitHub Release creation on workflow_dispatch only.Shared library consumption
<openframe.libs.version> in pom.xml, it points to a real published version of openframe-oss-lib (not a lingering 999-SNAPSHOT from local development).General
For broader context on how this repository fits the rest of the platform β the gateway's routes, the datasources it depends on, and the services it publishes β see Architecture Overview and the Ecosystem reference. For environment setup before your first contribution, see Environment Setup and Local Development.