# openframe-oss-lib: the shared Spring Boot modules behind the OpenFrame platform

> openframe-oss-lib is a monorepo of reusable Spring Boot modules for the OpenFrame platform, a multi-tenant MSP infrastructure built by Flamingo. It ships a reactive gateway, an OAuth2 and OIDC authorization server, a GraphQL layer, MongoDB domain and repositories, Kafka streaming and a Rust device agent. The repository is a library collection, not a service you can deploy.

**flamingo-stack/openframe-oss-lib** — Shared libraries between all services

- Repository: https://github.com/flamingo-stack/openframe-oss-lib
- Stars: 1,224 · Forks: 7
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/flamingo-stack-openframe-oss-lib

## This is a library collection, and the README says so first

OpenFrame OSS Lib is the core backend shared library collection of the OpenFrame platform, which is described as the AI-driven unified MSP, managed service provider, infrastructure built by Flamingo. The monorepo provides the reusable Spring Boot modules that power every OpenFrame service, delivered as independently versionable Maven artifacts.

The note under the title is the first thing to read. This repository contains shared library modules, not a standalone deployable service, and it is intended for use by openframe-oss-tenant and the related OpenFrame services.

That distinction changes what you do with it. There is no docker-compose to run, no port to open and no admin UI. What you get is a set of Maven artifacts under the com.openframe.oss group, and the question to ask is whether they are useful to you outside the platform they were written for.

The scale is visible in the top-level directory listing, which lists nearly forty modules. Beyond the headline ones there are openframe-exception for the exception hierarchy, openframe-core for utilities and validation, openframe-core-crypto, openframe-security-core and openframe-security-oauth, openframe-graphql-relay, openframe-idp-configuration, openframe-config-core, openframe-fe-feature-flags, openframe-notification-core and openframe-notification-mail, openframe-presence, openframe-machine-delivery, openframe-management-service-core, openframe-test-service-core, and a family of data modules for Cassandra, Kafka, Loki, NATS, Pinot and Redis, plus aspect modules for devices and time entry.

The licence badge points at a FLAMINGO AI Unified v1.0 licence file rather than a standard one, and that is worth understanding before anything else.

## Eight modules, eight layers, one architecture

The README gives a module summary table that is the fastest way to understand the platform, and it is worth reading as a request flow.

The edge module is openframe-gateway-service-core, a reactive JWT and API key gateway. The identity module is openframe-authorization-service-core, an OAuth2 and OIDC authorization server with MongoDB persistence, SSO and invitation-based registration. The API module is openframe-api-service-core, the internal GraphQL and REST API, and the external API module is openframe-external-api-service-core, the public REST surface with versioned /api/v1/** endpoints and OpenAPI documentation.

The agent module is openframe-client-core, which handles agent registration and the remote monitoring and management side. The domain module is openframe-data-mongo-common, the MongoDB document model covering devices, organisations, scripts, tickets and notifications, and the repositories module is openframe-data-mongo-sync, the synchronous repositories over that model. The streaming module is openframe-stream-service-core, which does the Kafka event processing.

The architecture diagram shows how they connect. A browser, an agent or an external system hits the gateway, which fans out to the authorization service, the API service, the external API and the client agent service. Those three data-facing services all read through the MongoDB repositories into the domain model, and the domain model sits on MongoDB. The client agent service publishes to Apache Kafka, the gateway publishes to Kafka, and the stream processing core consumes from Kafka and writes back to MongoDB. Separately, the client agent service talks over NATS and JetStream in both directions.

That is a coherent design for an event-driven MSP platform, and the layering is strict enough that a module can be understood on its own.

## Multi-tenancy is a cross cutting concern, not a filter you add later

The first feature in the list is multi-tenant by design, and the way the README describes it explains why it is first. Every module respects tenant isolation via TenantContext, scoped repositories and JWT claims.

Three mechanisms, then. A tenant context object carries the current tenant through the call. The repositories are scoped, so a query in one tenant's context cannot accidentally reach another tenant's documents. And the JWT carries the tenant claim, so the identity of the tenant is established at the token rather than inferred from a request parameter.

This is the part of the library that decides whether an adoption is cheap or expensive. If your application already has a tenant model, you either align with it or you keep a translation layer that will be a source of bugs. If you are starting fresh and the platform's model fits, the scoped repositories remove an entire category of security review.

The rest of the feature list is the rest of a platform. There is a reactive API gateway on Spring Cloud Gateway with WebFlux and Netty, handling JWT and API key authentication, rate limiting and WebSocket proxying. There is a GraphQL layer built on Netflix DGS with a Relay compliant API, cursor pagination and DataLoaders for N+1 elimination, which is a detail that says whoever wrote it has dealt with a real GraphQL data loading problem. There is a Rust device agent client at clients/openframe-client built on the Tokio async runtime, and a React and TypeScript component library for the OpenFrame UI with Storybook included.

The agent lifecycle management is the most concrete piece. It covers full agent registration, heartbeat over NATS, RMM script scheduling, an execution watchdog and Kafka publishing, which is the machinery of remote monitoring and management.

## Building it means four toolchains, three of them optional

The prerequisites are listed precisely, and it matters which ones are optional.

You need JDK 21, Maven 3.9 or newer, and Docker 24 or newer for the integration tests. Node.js 18 or newer is needed for the frontend modules but is marked optional, and Rust stable is needed for the agent client and is also marked optional.

The clone and build is three commands.

```bash
git clone https://github.com/flamingo-stack/openframe-oss-lib.git
cd openframe-oss-lib

mvn clean install -DskipTests
```

And then a verification step, which is the kind of detail that saves an afternoon when a module does not resolve.

```bash
mvn dependency:resolve -DincludeArtifactIds=openframe-core
```

For day to day work on a single module, the -pl and -am flags build that module and its upstream dependencies, which in a monorepo this size saves building every module.

```bash
mvn clean install -pl openframe-data-mongo-sync -am -DskipTests
```

The optional toolchains have their own build steps. The frontend library is a Node project.

```bash
cd openframe-frontend-core
npm install
npm run build
```

And the agent client is a Cargo project that produces a release binary.

```bash
cd clients/openframe-client
cargo build --release
```

The Docker requirement is worth flagging separately, because it is the one that catches people. Testcontainers is in the stack at 1.21.4, so the integration tests start real database and broker containers. Without Docker available the Maven build still works, but the integration tests cannot run, and the failure will look like a test failure rather than a missing prerequisite.

## Consuming a module, and the 999-SNAPSHOT placeholder

After a local install, a service picks up a module as a normal Maven dependency, with the groupId com.openframe.oss. The README shows the data layer module as the example.

```xml
<dependency>
    <groupId>com.openframe.oss</groupId>
    <artifactId>openframe-data-mongo-sync</artifactId>
    <version>999-SNAPSHOT</version>
</dependency>
```

The same pattern applies to openframe-api-service-core for the API service infrastructure and to openframe-gateway-service-core for the gateway, each with the same version string.

That version string is the interesting part, and it deserves a sentence. 999-SNAPSHOT is a placeholder, not a published version, and the repository publishes no GitHub releases. So the documented workflow is install from source and depend on the locally installed artifact, and the README's dependency block is a shape to copy rather than a coordinate to paste.

If you are considering this library outside the OpenFrame platform, that is the first thing to establish. Nothing in the documentation describes a published artifact repository for com.openframe.oss, so a consumer outside the platform would be building from source and publishing the artifacts into a repository of their own, which means taking on the versioning and the upgrade policy that the platform presumably handles centrally.

The repository does carry the pieces a larger operation needs. There is a renovate.json for dependency updates, a .trivyignore for the container vulnerability scanner, SECURITY.md and CONTRIBUTING.md, a docs/ directory, an sdk/ directory, and a react-embedding-example/ for the front end embedding story.

## A platform licence, not an open source one

The licence is the first thing to settle, and it is not a standard one. The badge in the README points at a licence file called LICENSE.md described as FLAMINGO AI Unified v1.0, and the repository is classified under a custom licence that GitHub cannot categorise.

That is a materially different situation from an Apache or MIT dependency, and the difference is not one of degree. An open source licence grants you rights. A custom platform licence grants whatever its text grants, and platform licences commonly restrict use to the platform, restrict redistribution, and impose terms on modification. The README does not summarise the terms, so the file is the only source, and reading it is a prerequisite rather than a formality.

The context matters too. This is the shared library layer of a commercial product, an AI-driven MSP infrastructure platform, with a companion tenant service and a paid offering behind it. The code is public so that the platform's services can be built and so that integrators can see what they are depending on, and the licence reflects that arrangement.

The maintenance picture is fine on its own terms. The repository is not archived, the last push was on 2026-10-15, and the project has a CI setup, a security policy and a dependency update configuration. There are no GitHub releases, which is consistent with a repository whose artefacts are consumed through a platform pipeline rather than published for general use.

## Conclusion

openframe-oss-lib fits a team building services inside the OpenFrame platform, or a team that wants to lift its multi-tenant gateway, authorization server and MongoDB domain model wholesale rather than design them. It does not fit a team that wants to adopt one small library, since the modules are built to work together around a shared tenant model, and it does not fit anyone needing a standard open source licence, because the repository is under the Flamingo AI Unified licence rather than an OSI one. Verify three things before you start: that the licence lets you do what you intend with these modules, since a custom platform licence is not a permissive grant, that the version you depend on is a released version rather than the 999-SNAPSHOT placeholder the README uses, and that your tenant isolation assumptions match the TenantContext and scoped repository model the modules assume, because retrofitting that onto an existing application is the expensive part of the adoption.

## FAQ

### Is openframe-oss-lib a service I can run?

No. The README states that the repository contains shared library modules and not a standalone deployable service, and that it is intended for use by openframe-oss-tenant and related OpenFrame services. What you get are independently versionable Maven artifacts under the com.openframe.oss group.

### What do I need to build openframe-oss-lib?

JDK 21, Maven 3.9 or newer, and Docker 24 or newer for the integration tests, which use Testcontainers 1.21.4 and therefore start real containers. Node.js 18 or newer is required for the frontend modules and Rust stable for the agent client, and both are optional for a Java-only build.

### How do I build a single module from the monorepo?

Use the -pl and -am flags so Maven builds that module and its upstream dependencies, for example mvn clean install -pl openframe-data-mongo-sync -am -DskipTests. A full build is mvn clean install -DskipTests, and mvn dependency:resolve -DincludeArtifactIds=openframe-core is used to verify that the build produced the expected artifact.

### What licence is openframe-oss-lib under?

A custom licence named the FLAMINGO AI Unified v1.0, in the LICENSE.md file, which GitHub cannot classify. It is not one of the standard permissive open source licences, so read the file before depending on the modules, particularly if you plan to use them outside the OpenFrame platform.

### What does the Rust agent client do?

It is the device agent, at clients/openframe-client, built on the Tokio async runtime, and it is part of the agent lifecycle management that includes full agent registration, heartbeat over NATS, RMM script scheduling, an execution watchdog and Kafka publishing. It is built with cargo build --release, and the binary is target/release/openframe-client.

## Sources

- [flamingo-stack/openframe-oss-lib on GitHub](https://github.com/flamingo-stack/openframe-oss-lib)
- [Issues](https://github.com/flamingo-stack/openframe-oss-lib/issues)
- [README](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flamingo-stack-openframe-oss-lib