Skip to content

README.md

Latest commit

 

History

History
138 lines (98 loc) · 7.64 KB

README.md

File metadata and controls

138 lines (98 loc) · 7.64 KB
Raw

OpenFrame OSS Lib — Documentation

Welcome to the documentation for OpenFrame OSS Lib (flamingo-stack/openframe-oss-lib), the core backend shared library collection of the OpenFrame platform.

This monorepo provides reusable Spring Boot modules that power every OpenFrame service: multi-tenant authentication, reactive API routing, event-driven stream processing, agent lifecycle management, and more.

📚 Table of Contents

🚀 Getting Started

New to OpenFrame OSS Lib? Start here:

Guide Description
Introduction What is OpenFrame OSS Lib, key features, and target audience
Prerequisites Required software (JDK 21, Maven, Docker, Node.js, Rust)
Quick Start Clone, build, and use modules in under 5 minutes
First Steps Explore the module hierarchy, domain model, and key patterns

🛠 Development

Guides for developing, extending, testing, and contributing to the library:

Guide Description
Development Overview Technology stack, repository structure, documentation map
Environment Setup IDE configuration (IntelliJ, VS Code), plugins, editor extensions
Local Development Clone, build, hot-reload patterns, debug configuration
Architecture Overview System design, component diagrams, data flow, key design decisions
Security Best Practices Auth patterns, tenant isolation, secrets management
Testing Overview Test structure, running tests, Testcontainers, coverage guidelines
Contributing Guidelines Code style, branch naming, PR process, commit format

📖 Reference Architecture

Detailed technical documentation for each core module:

Module Description
Authorization Service Core OAuth2/OIDC authorization server, JWT issuance, tenant resolution
Authorization — Tenant Context Tenant context filter, TenantContext ThreadLocal, scoping
Authorization — OAuth Persistence MongoDB-backed OAuth2 state persistence
Authorization — Controllers Registration, invitation, password reset controllers
Authorization — Configuration & Security Security filter chain, Spring Authorization Server config
Authorization — Registration & Utilities Registration flows and utility helpers
Gateway Service Core Reactive gateway, JWT validation, API key auth, rate limiting
API Service Core — GraphQL Netflix DGS GraphQL API, Relay pagination, DataLoaders
API Service Core — REST Controllers Internal REST endpoints, agent secrets, API key management
API Service Core — DataLoaders Batching and N+1 elimination with DataLoaders
API Service Core — Config & Security Security config, JWT resource server setup
API Contracts and Mapping DTOs, mappers, and API contract definitions
External REST API Service Core Public versioned REST API, tool proxying, OpenAPI docs
Client Agent Service Core Agent registration, heartbeat, RMM execution, watchdog
Data Mongo Domain Model MongoDB document definitions across all domains
Data Mongo Sync Repositories Tenant-aware repositories, cursor pagination, aggregations
Stream Processing Core Kafka event ingestion, enrichment, and state projection

🗂 Architecture Diagrams

Visual documentation is available as Mermaid diagram files in:

docs/diagrams/architecture/

Diagrams cover all major modules including:

  • authorization-service-core — OAuth2 flows, tenant context
  • gateway-service-core — Edge security flow
  • api-service-core-graphql — GraphQL execution model
  • client-agent-service-core — Agent lifecycle
  • stream-processing-core — Kafka pipeline
  • data-mongo-domain-model — Domain document relationships
  • data-mongo-sync-repositories — Repository query patterns
  • configuration-and-security — Security filter chain

🖥 CLI Tools

The OpenFrame Main CLI tool for self-hosted deployment is maintained in a separate repository:

Note: CLI tools are NOT located in this repository. Always refer to the external repository for installation and usage.

🔗 Related Projects

Project Description
openframe-oss-tenant Main OpenFrame platform application — see how these modules are assembled
openframe-cli CLI tool for self-hosted deployment
OpenFrame Unified AI-driven MSP platform
Flamingo Commercial MSP platform powered by OpenFrame

💬 Community & Support

Questions, ideas, and discussions live in 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 coordination happens on Slack.

📎 Quick Links

Documentation generated by 🦩 Flamingo AI Technical Writer