# meteroid-oss/meteroid architecture

> Architecture diagram of the GitHub repository meteroid-oss/meteroid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meteroid-oss/meteroid
- Repository: https://github.com/meteroid-oss/meteroid

## Overview

##### Project’s Main Components
- API & Service Layer: Multiple Rust crates (in the “crates” directory and “modules/meteroid”) encapsulate the business logic, domain model, and gRPC API. This layer includes common modules (for configuration, logging, error handling, event bus, authentication, etc.) that form the core billing engine.
- Message/ Event Bus: Notice the dedicated crates related to eventbus and Kafka (in “crates/common-eventbus” and “crates/kafka”). This shows the use of asynchronous messaging for event handling and inter-service communication.
- Data Layer: There are many Diesel migrations, database models (“crates/common-domain”, “modules/meteroid/crates/diesel-models”) which represent the persistent storage, including invoices, subscriptions, pricing plans, etc.
- Frontend: The “modules/web” directory contains a full-featured frontend (likely React/TypeScript driven) with UI components, routing, and theming. This acts as the user interface for billing dashboards, customer management, and other interactions.
- External Integrations & Adapters: Separate modules in “modules/adapters” for “openstack” and “slurm-collector” indicate integrations with external systems, while other crates (such as Stripe client, meteroid-mailer) show connectivity with payment systems, notifications, etc.
- Orchestration & Deployment: Directories such as “docker”, “k8s/meteroid”, and the extensive setup for CI/CD in “.github/workflows” indicate deployment and container orchestration is a key aspect.
- Developer and Shared Utilities: “crates/common-utils” and “crates/common-config” provide shared functionality across the project, while testing directories and seed generators (“extra/generator”) support maintainability and quality.

##### Relationships and Interactions
- The API layer exposes endpoints (both REST and gRPC) that accept customer usage data.
- Incoming data is processed by the core billing engine – which leverages domain logic from several crates – and then persisted in a relational database (accessed via Diesel).
- Event bus and Kafka components facilitate asynchronous communication (for example, triggering invoice generation or notifying other systems).
- The frontend interacts with API endpoints to display real-time dashboards, manage billing configurations, and allow customer interactions.
- The adapters interface with external services (openstack for cloud integrations, slurm-collector for usage metrics, etc.) ensuring that usage and billing data is consistently ingested.
- Distributed locking components help maintain data consistency, especially during concurrent invoice generation and subscriber updates.

##### Architectural Patterns and Design Principles
- The project is modular, with multiple small, focused Rust crates that implement different cross-cutting concerns (like logging, authentication, error handling) – which demonstrates a microkernel or plugin architecture.
- Use of gRPC and middleware layers in “crates/common-grpc” indicates a structured approach toward client/server abstraction.
- Separation between domain logic and infrastructure (e.g., common-domain vs. common-config or distributed lock) is clearly visible.
- The frontend is decoupled from the backend API, allowing for independent evolution.

##### Additional Notes
- Be as granular as necessary – it is often best not to oversimplify; include every major component (such as authentication layers, distributed locking mechanisms, different API strategies) to capture the full picture.
- Mention any CI/CD, deployment and operational concerns if they impact architectural behavior (given the Docker, Kubernetes and GitHub Workflows seen in the file structure).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    EXT["External Client"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["UI Client (React/TS)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        %% API & Service Layer
        subgraph "API & Service Layer"
            API["API Service (modules/meteroid)"]:::api
            GRPC["gRPC Module (crates/common-grpc)"]:::api
        end

        %% Core Billing Engine
        subgraph "Core Billing Engine"
            BILL["Billing Engine (Core Domain)"]:::api
            LOCK["Distributed Locking (crates/distributed-lock)"]:::utils
        end

        %% Data Layer
        subgraph "Data Layer"
            DB["Database (Diesel Models)"]:::db
        end

        %% Message & Event Bus
        subgraph "Message & Event Bus"
            EVENT["Event Bus (crates/common-eventbus)"]:::infra
            KAFKA["Kafka Integration (crates/kafka)"]:::infra
        end

        %% External Integrations & Adapters
        subgraph "External Integrations & Adapters"
            ADAPTERS["Adapters (openstack, slurm-collector) (modules/adapters)"]:::infra
            STRIPE["Stripe Client (modules/meteroid/crates/stripe-client)"]:::infra
            MAILER["Meteroid Mailer (modules/meteroid/crates/meteroid-mailer)"]:::infra
        end

        %% Deployment & Orchestration
        subgraph "Deployment & Orchestration"
            DOCKER["Docker (docker)"]:::infra
            K8S["Kubernetes (k8s/meteroid)"]:::infra
            CICD["CI/CD (.github/workflows)"]:::infra
        end

        %% Developer & Shared Utilities
        subgraph "Developer & Shared Utilities"
            UTIL["Shared Utilities (crates/common-utils)"]:::utils
            CONFIG["Shared Config (crates/common-config)"]:::utils
            GEN["Seed Generator (extra/generator)"]:::utils
        end
    end

    %% Data Flow Connections
    EXT --> FE
    EXT --> API
    FE --> API
    API --> GRPC
    API --> BILL
    BILL --> DB
    API --> EVENT
    EVENT --> KAFKA
    BILL --> LOCK
    GRPC --> DB
    ADAPTERS --> BILL
    ADAPTERS --> EVENT
    STRIPE --> BILL
    MAILER --> BILL
    CICD --> DOCKER
    CICD --> K8S
    DOCKER --> API
    DOCKER --> FE
    K8S --> API
    K8S --> FE

    %% Click Events
    click API "https://github.com/meteroid-oss/meteroid/tree/main/modules/meteroid"
    click GRPC "https://github.com/meteroid-oss/meteroid/tree/main/crates/common-grpc"
    click EVENT "https://github.com/meteroid-oss/meteroid/tree/main/crates/common-eventbus"
    click KAFKA "https://github.com/meteroid-oss/meteroid/tree/main/crates/kafka"
    click DB "https://github.com/meteroid-oss/meteroid/tree/main/crates/common-domain"
    click FE "https://github.com/meteroid-oss/meteroid/tree/main/modules/web"
    click ADAPTERS "https://github.com/meteroid-oss/meteroid/tree/main/modules/adapters"
    click STRIPE "https://github.com/meteroid-oss/meteroid/tree/main/modules/meteroid/crates/stripe-client"
    click MAILER "https://github.com/meteroid-oss/meteroid/tree/main/modules/meteroid/crates/meteroid-mailer"
    click DOCKER "https://github.com/meteroid-oss/meteroid/tree/main/docker"
    click K8S "https://github.com/meteroid-oss/meteroid/tree/main/k8s/meteroid"
    click CICD "https://github.com/meteroid-oss/meteroid/tree/main/.github/workflows"
    click UTIL "https://github.com/meteroid-oss/meteroid/tree/main/crates/common-utils"
    click CONFIG "https://github.com/meteroid-oss/meteroid/tree/main/crates/common-config"
    click GEN "https://github.com/meteroid-oss/meteroid/tree/main/extra/generator"
    click LOCK "https://github.com/meteroid-oss/meteroid/tree/main/crates/distributed-lock"

    %% Styles
    classDef api fill:#ffd1dc,stroke:#d6336c,stroke-width:2px;
    classDef frontend fill:#d1ffd6,stroke:#28a745,stroke-width:2px;
    classDef db fill:#d1e0ff,stroke:#007bff,stroke-width:2px;
    classDef infra fill:#fff4cc,stroke:#ffae42,stroke-width:2px;
    classDef utils fill:#e6ffe6,stroke:#28a745,stroke-width:2px;
    classDef external fill:#e8e8e8,stroke:#a9a9a9,stroke-dasharray:5 5,stroke-width:2px;
```
