Knowledge Hub

openframe-oss-tenant Module Documentation

OpenFrame OSS Tenant — Architecture Documentation

Overview

OpenFrame OSS Tenant is the multi-service, multi-tenant open-source foundation of the OpenFrame platform — an AI-powered MSP (Managed Service Provider) platform that replaces expensive proprietary software with intelligent automation. It integrates device management, real-time messaging, AI-assisted support (Mingo AI for technicians, Fae for clients), and event-driven automation across a polyglot microservice architecture built on Spring Boot (Java) and Rust.

Architecture

High-Level System Architecture

graph TB
    subgraph Clients["Client Layer"]
        FrontendUI["openframe-frontend\n(Web UI)"]
    end

    subgraph Gateway["Edge Layer"]
        GW["Gateway Service\n:8081\nSpring Cloud Gateway"]
    end

    subgraph CoreServices["Core Services"]
        API["API Service\n:8080\nSpring Boot + GraphQL"]
        AuthServer["Authorization Server\n:8082\nOAuth2/OIDC"]
        ExtAPI["External API\n:8083\nSpring Boot REST"]
        StreamSvc["Stream Service\n:8085\nKafka Streams"]
        ClientSvc["Client Service\n:8084\nSpring Boot + NATS"]
    end

    subgraph AgentLayer["Agent Layer"]
        OFClient["openframe-client\n(Rust Agent)\nSystem Service"]
    end

    subgraph DataLayer["Data Layer"]
        Mongo[("MongoDB\nTransactional Storage")]
        Cassandra[("Cassandra\nTime-Series / Logs")]
        Pinot[("Apache Pinot\nReal-Time Analytics")]
        Redis[("Redis\nCache / Sessions")]
        Kafka[("Apache Kafka\nEvent Streaming")]
        NATS[("NATS/JetStream\nAgent Messaging")]
    end

    FrontendUI --> GW
    GW --> API
    GW --> AuthServer
    GW --> ExtAPI
    API --> Mongo
    API --> Pinot
    API --> Kafka
    StreamSvc --> Kafka
    StreamSvc --> Cassandra
    StreamSvc --> Pinot
    ClientSvc --> Mongo
    ClientSvc --> NATS
    AuthServer --> Mongo
    OFClient --> NATS
    OFClient --> API

Core Components

Component Relationships

Service Dependency Graph

graph LR
    subgraph FE["Frontend Clients"]
        Frontend["openframe-frontend\n(Web)"]
    end

    subgraph Backend["Backend Services"]
        GW["Gateway\n:8081"]
        API["API Service\n:8080"]
        Auth["Auth Server\n:8082"]
        Ext["External API\n:8083"]
        Stream["Stream Service\n:8085"]
        ClientSvc["Client Service\n:8084"]
    end

    subgraph Agent["Agent"]
        OFC["openframe-client\n(Rust)"]
    end

    subgraph Lib["Shared Libraries"]
        CoreLib["openframe-frontend-core\n(TypeScript npm lib)"]
    end

    Frontend --> CoreLib
    Frontend --> GW
    GW --> Auth
    GW --> API
    GW --> Ext
    API --> Stream
    ClientSvc --> NATS[("NATS")]
    OFC --> NATS
    Stream --> Kafka[("Kafka")]
    API --> Kafka

Data Flow

Agent Registration and Authentication

sequenceDiagram
    participant Agent as openframe-client
    participant GW as Gateway
    participant Auth as Auth Server
    participant API as API Service
    participant Mongo as MongoDB
    participant NATS as NATS JetStream

    Agent->>GW: POST /clients/api/agents/register (X-Initial-Key)
    GW->>API: Forward registration request
    API->>Mongo: Persist machine record
    API-->>Agent: {machineId, clientId, clientSecret}
    Agent->>GW: POST /clients/oauth/token (client_credentials)
    GW->>Auth: Forward token request
    Auth->>Mongo: Lookup OAuth2 client
    Auth-->>Agent: JWT access_token + refresh_token
    Agent->>NATS: Subscribe machine.{machineId}.* subjects
    NATS-->>Agent: Tool install / update / script execution messages

Multi-Tenant OAuth2 Security Flow

sequenceDiagram
    participant Browser as Browser
    participant GW as Gateway
    participant Auth as Auth Server
    participant API as API Service
    participant DB as MongoDB

    Browser->>Auth: OAuth2 login (tenant-scoped PKCE)
    Auth->>DB: Lookup tenant OAuth2 client
    Auth-->>Browser: JWT (tenant_id + RSA signed)
    Browser->>GW: API request with Bearer JWT
    GW->>GW: Validate issuer + RSA signature
    GW->>GW: Attach identity context headers
    GW->>API: Forward with X-Tenant-Id, X-Machine-Id
    API->>API: Enforce tenant isolation filter
    API->>DB: Query with tenantId scope
    DB-->>API: Tenant-scoped results
    API-->>Browser: Response

Key Files

Dependencies

The repository consumes ../deps/openframe-oss-lib/ as a monorepo dependency workspace.

openframe-frontend-core (TypeScript npm package @flamingo-stack/openframe-frontend-core)

This is the shared UI library consumed by openframe-frontend (the web UI). It provides chat UI surfaces, NATS streaming hooks, ODS design tokens, and UI primitives.

The library ships two tsup build configurations: a server-safe entry (pure types, configs, platform domains — no React) and a client-side entry (React components with "use client" banner).

openframe-client in ../deps/openframe-oss-lib/clients/openframe-client

The agent implementation lives there as the openframe-agent-lib crate; the in-repo clients/openframe-client is a thin binary that depends on it via a pinned git tag and calls openframe::run(). The library's build.rs requires OPENFRAME_VERSION at build time (optional tool/agent version env vars can be injected at compile time).

CLI Commands

The openframe-client Rust binary exposes the following subcommands:

openframe-client install \
  --serverUrl <https://your-server> \
  --initialKey <key> \
  --orgId <org-id> \
  [--localMode] \
  [--tag key=value ...]

openframe-client uninstall

openframe-client run

openframe-client doctor

Command Reference

Doctor Check Categories

[+] Pass    [x] Fail    [!] Warn    [i] Info

Pre-install checks:
  Command   — all required CLI args present
  Admin     — running as root/Administrator
  Disk      — install path writable, 200MB free, log/secured dirs writable
  Network   — DNS resolves server URL, TCP connects :443, HTTPS handshake succeeds

Health check (post-install):
  Command   — initial_config.json readable, server_host present
  Admin     — elevated privileges
  Network   — same DNS/TCP/TLS checks against persisted server_host

Install Flags

Community & Links

• Community (Slack): OpenMSP Community
• Platform: flamingo.run
• OpenFrame Product: flamingo.run/openframe
• OpenMSP: openmsp.ai
• Repository: flamingo-stack/openframe-oss-tenant
• Issues / PRs: github.com/flamingo-stack/openframe-oss-tenant/pulls
• Releases: github.com/flamingo-stack/openframe-oss-tenant/releases