# bucketeer-io/bucketeer architecture

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

- Interactive diagram: https://gitdiagram.com/bucketeer-io/bucketeer
- Repository: https://github.com/bucketeer-io/bucketeer

## Overview

##### Main System Components
- Backend Services: You have several “cmd” directories (cmd/api, cmd/batch, cmd/subscriber, cmd/web) which indicate that the backend is composed of multiple services. In addition, the “pkg” directory is divided by domain (account, auditlog, auth, autoops, batch, etc.) that implement business logic and data storage operations.
- Communication & API Layer: The “proto” directory and generated Go and TypeScript files illustrate that the system uses gRPC (and likely REST) as well as Protobuf contracts between services.
- Data Stores and Cache: The presence of storage packages (MySQL, Postgres, BigQuery, Redis, etc.) and caching layers (pkg/cache) show that persistent storage and caching are key parts of the system.
- Frontend Applications: Two major UI directories exist (“ui/dashboard” and “ui/web‑v2”). They are built with TypeScript/React and handle client-side interactions with the backend through REST/gRPC APIs.
- Infrastructure & Deployment: Directories such as “manifests,” “.github/workflows,” “migration,” and “Dockerfiles” imply the use of containerized deployments (e.g., Docker, Kubernetes via Helm charts) and automated CI/CD pipelines.
- Messaging/Events: The presence of “pkg/pubsub,” “pkg/eventcounter,” and “pkg/subscriber” modules indicates that event streaming/message processing is used to process events (for logging, evaluation events, and notifications).

##### Relationships and Interactions
- Shared Communication Contract: Represent the Protobuf/gRPC layer as a middle entity used by both internal services and client SDKs (Android, iOS, JavaScript, Flutter, Go, Node.js) to maintain consistent communication.
- Messaging and Event Pipelines: Represent the pubsub system and other messaging channels that feed evaluation results, notifications, and analytics from one module (e.g., autoops or eventcounter) to another (e.g., batch or subscriber) via asynchronous message brokers.

##### Architectural Patterns and Technologies
- Continuous Integration/Delivery: Optionally add an “Infra/DevOps” layer that displays CI/CD pipelines, Docker containers, and orchestration with Kubernetes showing deployment flow.

##### Final Touches
- Flows such as “Feature Flag Evaluation,” “A/B Testing Results Analysis,” and “Notification Delivery” to emphasize Bucketeer’s core functionality.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Clients
    Client("Client SDKs & Browsers"):::frontend

    %% Frontend Layer
    subgraph "Frontend Layer"
        Dashboard("Dashboard App"):::frontend
        WebClient("Web Client App"):::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        API("API Service"):::backend
        Batch("Batch Processor"):::backend
        Subscriber("Subscriber Service"):::backend
        Web("Web Service"):::backend
    end

    %% Communication & Contracts
    subgraph "Communication & Contracts"
        APIContracts("gRPC/Protobuf Contracts"):::middleware
    end

    %% Data & Messaging
    subgraph "Data & Messaging"
        Storage["SQL & BigQuery Storage"]:::data
        Cache["Redis Cache"]:::data
        PubSub("PubSub System"):::data
        EventCounter("Event Counter"):::data
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        CICD("CI/CD Pipelines"):::infra
        Helm("Kubernetes/Helm Charts"):::infra
        Migration("Migration Scripts"):::infra
    end

    %% Connections from External Clients to Frontend
    Client -->|"REST/gRPC"| Dashboard
    Client -->|"REST/gRPC"| WebClient

    %% Frontend to Backend
    Dashboard -->|"REST/gRPC"| API
    WebClient -->|"REST/gRPC"| API

    %% Backend Internal Communication
    API -->|"Calls"| Batch
    API -->|"Publishes events"| Subscriber
    API -->|"Delivers UI data"| Web
    API -->|"Uses"| APIContracts

    %% Backend to Data & Messaging
    API -->|"DB Query"| Storage
    API -->|"Caches Data"| Cache

    Batch -->|"DB Query"| Storage
    Batch -->|"Caches Data"| Cache

    Subscriber -->|"DB Query"| Storage
    Subscriber -->|"Caches Data"| Cache

    Web -->|"DB Query"| Storage
    Web -->|"Caches Data"| Cache

    %% Messaging flows
    API -->|"Publishes"| PubSub
    PubSub -->|"Delivers"| Subscriber
    Batch -->|"Updates count"| EventCounter
    EventCounter -->|"Notifies"| Subscriber

    %% Infrastructure Deployment Links
    CICD -->|"Deploys"| API
    CICD -->|"Deploys"| Batch
    CICD -->|"Deploys"| Subscriber
    CICD -->|"Deploys"| Web
    CICD -->|"Deploys"| Dashboard
    CICD -->|"Deploys"| WebClient

    %% Class Definitions
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef middleware fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef data fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

    %% Click Events
    click API "https://github.com/bucketeer-io/bucketeer/blob/main/cmd/api/api.go"
    click Batch "https://github.com/bucketeer-io/bucketeer/blob/main/cmd/batch/batch.go"
    click Subscriber "https://github.com/bucketeer-io/bucketeer/blob/main/cmd/subscriber/subscriber.go"
    click Web "https://github.com/bucketeer-io/bucketeer/blob/main/cmd/web/web.go"
    click Dashboard "https://github.com/bucketeer-io/bucketeer/tree/main/ui/dashboard/"
    click WebClient "https://github.com/bucketeer-io/bucketeer/tree/main/ui/web-v2/"
    click APIContracts "https://github.com/bucketeer-io/bucketeer/tree/main/proto/"
    click Storage "https://github.com/bucketeer-io/bucketeer/tree/main/pkg/storage/"
    click Cache "https://github.com/bucketeer-io/bucketeer/tree/main/pkg/cache/"
    click PubSub "https://github.com/bucketeer-io/bucketeer/tree/main/pkg/pubsub/"
    click EventCounter "https://github.com/bucketeer-io/bucketeer/tree/main/pkg/eventcounter/"
    click CICD "https://github.com/bucketeer-io/bucketeer/tree/main/.github/workflows/"
    click Helm "https://github.com/bucketeer-io/bucketeer/tree/main/manifests/"
    click Migration "https://github.com/bucketeer-io/bucketeer/tree/main/migration/"
```
