Skip to content

📚 Automated Documentation Update #1113

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
github-actions wants to merge 7 commits into
base: main
Choose a base branch
from
Open

📚 Automated Documentation Update #1113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
98ef2d5
docs: Initialize documentation pipeline [skip ci]
github-actions[bot] Jun 4, 2026
a56d51f
chore(docs): Clean slate - remove all documentation (251 files) [skip…
github-actions[bot] Jun 4, 2026
391a015
docs: Stage 1 - Inline documentation (402 files) [skip ci]
github-actions[bot] Jun 4, 2026
4d00e9d
chore(docs): Remove 2 orphaned inline files [skip ci]
github-actions[bot] Jun 4, 2026
3aa6d9d
docs: Stage 2 - Architecture analysis (9 files) [skip ci]
github-actions[bot] Jun 4, 2026
8461ab6
docs: Stage 3 - Tutorial generation (11 files) [skip ci]
github-actions[bot] Jun 4, 2026
1f57181
docs: Stage 4 - Repository documentation (4 files) [skip ci]
github-actions[bot] Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
460 changes: 255 additions & 205 deletions CONTRIBUTING.md
View file
Open in desktop

Large diffs are not rendered by default.

268 changes: 156 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,82 +10,105 @@
<a href="LICENSE.md"><img alt="License" src="https://img.shields.io/badge/LICENSE-FLAMINGO%20AI%20Unified%20v1.0-%23FFC109?style=for-the-badge&labelColor=white"></a>
</p>

# openframe-oss-lib
# OpenFrame OSS Lib

**openframe-oss-lib** is the foundational backend library powering the [OpenFrame](https://openframe.ai) platform — the AI-driven, open-source MSP infrastructure stack built by [Flamingo](https://flamingo.run).
**`openframe-oss-lib`** is the modular backbone of [OpenFrame](https://openframe.ai) — Flamingo's AI-powered MSP platform that replaces expensive proprietary software with open-source alternatives enhanced by intelligent automation.

This repository provides the **shared Spring Boot libraries** that every OpenFrame service is built upon: multi-tenant authentication, API layers (REST + GraphQL), reactive gateway routing, event streaming, real-time messaging, polyglot persistence, and distributed management workflows.
This library provides the shared, composable building blocks that power the entire OpenFrame stack: from multi-tenant identity and OAuth2 authorization, to reactive APIs, event-driven stream processing, and an embeddable AI chat engine.

[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/maxresdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps)
> This repository does **not** ship a standalone application — it provides libraries and service-core modules that are embedded into deployable OpenFrame-compatible services.

---

## Features

- **Multi-Tenant by Default** — Every module implements strict tenant isolation: per-tenant RSA key pairs, tenant-scoped cache keys, tenant-scoped scheduler locks, and tenant ID embedded in every JWT
- **Multi-Tenant OAuth2 Authorization Server** — Per-tenant RSA key pairs, JWT issuance, PKCE support, dynamic client registration, SSO integration (Google, Microsoft), and invitation-based onboarding
- **Relay-Compliant GraphQL + REST APIs** — Netflix DGS GraphQL with DataLoaders for N+1 prevention alongside versioned REST controllers; cursor-based pagination throughout
- **Reactive Edge Gateway** — Spring Cloud Gateway + WebFlux + Netty; multi-issuer JWT validation, API key rate limiting, WebSocket proxying, and tool upstream resolution
- **Event Ingestion & Streaming** — Kafka / Debezium CDC processing pipeline with tool-specific deserialization, event enrichment, unified event type normalization, and Kafka Streams enrichment
- **Real-Time Messaging** — NATS JetStream publish/subscribe for device and tool notifications; persist-first notification strategy with read-state tracking
- **Polyglot Persistence** — MongoDB (sync + reactive), Redis (tenant-aware caching), Apache Pinot (analytics), Apache Cassandra (log storage)
- **Distributed Schedulers** — ShedLock + Redis for cluster-safe distributed job scheduling; offline device detection, API key stats sync, MDM fleet setup
- **External REST API** — API key–authenticated integration surface for third-party tools with OpenAPI documentation
- **Tool SDKs** — First-class Java clients for Tactical RMM, Fleet MDM, and MeshCentral
- **Modular Maven Structure** — 30+ independent modules; include only what your service needs
- **Spring Boot 3.3 / Java 21** — Modern LTS Java with Spring Security OAuth2 and virtual thread readiness
[![Watch What's New in OpenFrame 0.7.8](https://img.youtube.com/vi/BQAjDB4ED2Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=BQAjDB4ED2Y)

---

## Architecture
[![OpenFrame: 5-Minute MSP Platform Walkthrough - Cut Vendor Costs & Automate Ops](https://img.youtube.com/vi/er-z6IUnAps/hqdefault.jpg)](https://www.youtube.com/watch?v=er-z6IUnAps)

---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| **Multi-Tenant Identity** | OAuth2 Authorization Server with per-tenant RSA key pairs and OIDC support |
| **Reactive API Layer** | REST + GraphQL (Netflix DGS) with Relay-style pagination and DataLoader batching |
| **Gateway & WebSocket Routing** | Spring Cloud Gateway with JWT validation, rate limiting, and tool proxying |
| **MongoDB Data Layer** | Reactive + sync repositories, cursor pagination, multi-tenant scoping |
| **Kafka Stream Processing** | Debezium CDC ingestion, event normalization, and Kafka Streams enrichment |
| **Management & Operations** | Distributed schedulers, migration support (Mongock), NATS initialization |
| **Frontend UI & AI Chat** | Embeddable React AI assistant (Guide + Mingo modes), Kanban, Notifications |
| **Integrated Tool SDKs** | Native SDKs for MeshCentral, Tactical RMM, and Fleet MDM |
| **Shared API Contracts** | Centralized DTOs, filters, and pagination primitives for all services |

---

## 🏗️ Architecture

The platform is structured as an event-driven, reactive microservice stack with strict multi-tenant isolation:

```mermaid
flowchart TD
Client["Client / Browser / Agent"] --> Gateway["Gateway Service Core"]
Gateway --> ExternalAPI["External API Service Core"]
Gateway --> ApiCore["API Service Core (GraphQL + REST)"]

ApiCore --> Authz["Authorization Service Core (OAuth2 / JWT)"]
ApiCore --> Stream["Stream Service Core (Kafka / Debezium)"]
ApiCore --> Management["Management Service Core (Schedulers)"]

Authz --> Mongo["MongoDB"]
ApiCore --> Mongo
ApiCore --> Redis["Redis"]
ApiCore --> Pinot["Apache Pinot"]
Stream --> Kafka["Apache Kafka"]
Stream --> Cassandra["Apache Cassandra"]
Management --> NATS["NATS JetStream"]
Frontend["Frontend Core UI and Chat"]
Gateway["Gateway Service Core"]
Auth["Authorization Service Core"]
API["API Service Core (HTTP + GraphQL)"]
Management["Management Service Core"]
Data["Data Models and Repositories (MongoDB)"]
Stream["Stream Processing (Kafka)"]
Cassandra["Cassandra (Unified Event Log)"]
Tools["Integrated Tools (MeshCentral / Tactical RMM / Fleet MDM)"]
Redis["Redis (Cache + Distributed Locks)"]
NATS["NATS (Agent Messaging)"]

Frontend --> Gateway
Gateway --> Auth
Gateway --> API
Gateway --> Tools
API --> Data
API --> Stream
Stream --> Cassandra
Stream --> Data
Management --> Data
Management --> Redis
Management --> NATS
Tools --> Stream
```

---

## Technology Stack

| Layer | Technology |
|-------|-----------|
| Language | Java 21 |
| Framework | Spring Boot 3.3 |
| Build Tool | Apache Maven 3.9+ |
| Auth | Spring Authorization Server, Spring Security OAuth2 |
| API | Netflix DGS (GraphQL), Spring MVC (REST) |
| Gateway | Spring Cloud Gateway + WebFlux + Netty |
| Persistence | MongoDB (sync + reactive), Redis, Cassandra, Apache Pinot |
| Messaging | Apache Kafka / Debezium CDC, NATS JetStream |
| Testing | JUnit 5, Testcontainers, RestAssured |
| Distributed Locking | ShedLock + Redis |
| Multi-tenancy | ThreadLocal tenant context, per-tenant RSA keys |
### Service Modules

| Module | Role |
|--------|------|
| `openframe-gateway-service-core` | Reactive edge — JWT validation, rate limiting, WebSocket proxying, tool routing |
| `openframe-authorization-service-core` | Multi-tenant OAuth2/OIDC — JWT issuance, SSO (Google/Microsoft) |
| `openframe-api-service-core` | REST + GraphQL (Netflix DGS) — DataLoader batching, Relay pagination |
| `openframe-api-lib` | Shared DTOs, filter criteria, pagination primitives |
| `openframe-data-mongo-common` | MongoDB document models and base repositories |
| `openframe-data-mongo-sync` | Synchronous MongoDB repositories with custom cursor pagination |
| `openframe-data-mongo-reactive` | Reactive MongoDB repositories for auth flows |
| `openframe-data-redis` | API key stats, rate limiting, ShedLock distributed locking |
| `openframe-data-kafka` | Kafka producers with retry and recovery |
| `openframe-data-nats` | NATS pub/sub, agent notifications, command dispatch |
| `openframe-stream-service-core` | Debezium CDC ingestion, event normalization, Kafka Streams |
| `openframe-management-service-core` | Cluster coordination, tool lifecycle, schedulers, migrations |
| `openframe-client-core` | Device registration, authentication, tool installation |
| `openframe-security-core` | JWT primitives, `AuthPrincipal`, cookie service |
| `openframe-frontend-core` | React component library, AI chat engine (Guide + Mingo modes) |

---

## Quick Start
## 🚀 Quick Start

### Prerequisites

- Java 21 JDK ([Eclipse Temurin 21](https://adoptium.net/) recommended)
- Apache Maven 3.9+
- Docker 24.x (for integration tests)
- GitHub Personal Access Token (PAT) with `read:packages` scope
| Tool | Version |
|------|---------|
| **Java (JDK)** | 21+ |
| **Apache Maven** | 3.8+ |
| **Git** | 2.x+ |
| **Docker** | 24.x+ |
| **Node.js** | 18+ (for frontend-core only) |

### 1. Clone the Repository

Expand All @@ -94,7 +117,7 @@ git clone https://github.com/flamingo-stack/openframe-oss-lib.git
cd openframe-oss-lib
```

### 2. Configure GitHub Packages
### 2. Configure GitHub Packages Access

Add your GitHub credentials to `~/.m2/settings.xml`:

Expand All @@ -104,45 +127,45 @@ Add your GitHub credentials to `~/.m2/settings.xml`:
<server>
<id>github</id>
<username>YOUR_GITHUB_USERNAME</username>
<password>YOUR_GITHUB_PAT</password>
<password>YOUR_GITHUB_TOKEN</password>
</server>
</servers>
</settings>
```

### 3. Build the Library
Generate a GitHub Personal Access Token (PAT) with `read:packages` scope from [GitHub Settings → Developer Settings](https://github.com/settings/tokens).

### 3. Build All Modules

```bash
# Build all modules (skip tests for speed)
mvn install -DskipTests
```

### 4. Add a Module as a Dependency
### 4. Use a Module as a Dependency

```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.openframe.oss</groupId>
<artifactId>openframe-oss-lib</artifactId>
<version>5.79.3</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<dependency>
<groupId>com.openframe.oss</groupId>
<artifactId>openframe-api-service-core</artifactId>
</dependency>
</dependencies>
<artifactId>openframe-core</artifactId>
<version>6.0.10</version>
</dependency>
```

Or inherit the parent POM for aligned dependency management:

```xml
<parent>
<groupId>com.openframe.oss</groupId>
<artifactId>openframe-oss-lib</artifactId>
<version>6.0.10</version>
</parent>
```

### 5. Run Tests

```bash
# Unit tests for a specific module
# Unit tests (no Docker required)
mvn test -pl openframe-core

# Integration tests (requires Docker)
Expand All @@ -151,50 +174,71 @@ mvn verify -pl openframe-data-mongo-sync

---

## Module Overview

| Module | Description |
|--------|-------------|
| `openframe-core` | Core utilities, pagination, validation |
| `openframe-exception` | Standard exception hierarchy |
| `openframe-core-crypto` | Encryption utilities |
| `openframe-security-core` | JWT, PKCE, cookie service |
| `openframe-security-oauth` | OAuth2 BFF layer |
| `openframe-authorization-service-core` | Multi-tenant OAuth2 authorization server |
| `openframe-api-lib` | API contracts, filter DTOs, cursor pagination |
| `openframe-api-service-core` | REST + GraphQL API service layer |
| `openframe-gateway-service-core` | Reactive gateway, routing, security |
| `openframe-data-mongo-common` | MongoDB domain documents |
| `openframe-data-mongo-sync` | Synchronous MongoDB repositories |
| `openframe-data-mongo-reactive` | Reactive MongoDB repositories |
| `openframe-data-redis` | Redis tenant-aware cache |
| `openframe-data-kafka` | Kafka multi-tenant configuration |
| `openframe-data-nats` | NATS real-time messaging |
| `openframe-data-cassandra` | Cassandra log storage |
| `openframe-data-pinot` | Apache Pinot analytics queries |
| `openframe-management-service-core` | Distributed schedulers, startup initializers |
| `openframe-stream-service-core` | Kafka streams, Debezium event enrichment |
| `openframe-external-api-service-core` | External REST API for integrations |
| `sdk/fleetmdm` | Fleet MDM Java SDK |
| `sdk/tacticalrmm` | Tactical RMM Java SDK |
## 🧰 Technology Stack

### Backend

| Technology | Version | Role |
|-----------|---------|------|
| **Java** | 21 | Primary language |
| **Spring Boot** | 3.3.0 | Application framework |
| **Spring Cloud** | 2023.0.3 | Cloud-native patterns |
| **Netflix DGS** | 9.0.3 | GraphQL framework |
| **MongoDB** | Reactive + Sync | Primary data store |
| **Apache Kafka** | 3.x | Event streaming |
| **NATS** | 0.6.2+3.5 | Lightweight messaging |
| **Redis** | Spring Data Redis | Caching + distributed locks |
| **Apache Cassandra** | – | Event log storage |
| **Apache Pinot** | 1.2.0 | Analytics |
| **Lombok** | 1.18.30 | Boilerplate reduction |
| **Testcontainers** | 1.21.4 | Integration testing |

### Frontend (`openframe-frontend-core`)

| Technology | Role |
|-----------|------|
| **React** | UI component library |
| **TypeScript** | Type-safe UI development |
| **Tailwind CSS** | Utility-first styling |
| **NATS WebSocket** | Real-time chat transport |
| **SSE** | Guide mode AI chat transport |
| **Storybook** | Component development and documentation |
| **Vitest** | Unit testing |

---

## Documentation
## 📚 Documentation

📖 See the [Documentation](./docs/README.md) for comprehensive guides including:

📚 See the [Documentation](./docs/README.md) for comprehensive guides covering architecture, setup, development workflows, and reference documentation.
- [Getting Started](./docs/getting-started/introduction.md) — Introduction and platform overview
- [Prerequisites](./docs/getting-started/prerequisites.md) — Environment setup
- [Quick Start](./docs/getting-started/quick-start.md) — Up and running in 5 minutes
- [First Steps](./docs/getting-started/first-steps.md) — Key things to explore
- [Architecture Overview](./docs/development/architecture/README.md) — System design and data flows
- [Contributing Guidelines](./docs/development/contributing/guidelines.md) — How to contribute

---

## Community
## 🤝 Community

All discussions, questions, and support happen on the **[OpenMSP Slack Community](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)**. We do not use GitHub Issues or GitHub Discussions.
All discussions, questions, and feature requests are managed on the **OpenMSP Slack** community.

[![Join OpenMSP Slack](https://img.shields.io/badge/Slack-OpenMSP-blue?logo=slack)](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA)

- **Questions**: `#dev-questions` channel
- **Feature Requests**: `#roadmap` channel
- **Bug Reports**: `#bugs` channel

> We do **not** use GitHub Issues or GitHub Discussions. Everything is managed on [OpenMSP Slack](https://www.openmsp.ai/).

---

- 🌐 **OpenFrame Platform:** [https://openframe.ai](https://openframe.ai)
- 💬 **OpenMSP Slack:** [https://www.openmsp.ai/](https://www.openmsp.ai/)
- 🦩 **Flamingo:** [https://flamingo.run](https://flamingo.run)
## 🔗 Links

[![OpenFrame v0.5.2: Autonomous AI Agent Architecture for MSPs](https://img.youtube.com/vi/PexpoNdZtUk/maxresdefault.jpg)](https://www.youtube.com/watch?v=PexpoNdZtUk)
- [OpenFrame Platform](https://openframe.ai)
- [Flamingo](https://flamingo.run)
- [OpenMSP Community](https://www.openmsp.ai/)

---

Expand Down
Loading
Loading