# hypertrace/config-service architecture

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

- Interactive diagram: https://gitdiagram.com/hypertrace/config-service
- Repository: https://github.com/hypertrace/config-service

## Overview

##### Project type and purpose
- Type: A Gradle‐based multi‐module Java microservice implementing a gRPC API for managing configurations (user prefs, filters, ingestion configs, etc.)
- Purpose: Provide a unified “config‐service” that stores, serves, versions, audits, and publishes change‐events for various domain‐specific configurations (alerting, labeling, notification, partitioner, spaces, span‐processing).

##### File structure to find logical layers
Top‐level modules:
- alerting‐config‐service‐api / impl
- config‐object‐store
- config‐proto‐converter
- config‐service‐api
- config‐service‐impl
- config‐service (the main executable)
- config‐validation‐utils
- config‐service‐change‐event‐api / generator
- config‐service‐factory
- domain modules (label‐application‐rule, labels, notification‐channel, notification‐rule, partitioner, spaces, span‐processing) each split into api + impl
- helm chart for deployment

Patterns:
- Modular, domain‐driven services under one codebase
- gRPC‐first API definition in “‐api” modules, Java implementations in “‐impl” modules
- Factory module to wire up domain services into one server
- Converter & validation utility modules for shared logic
- Event‐generator module to emit change events

##### Readme insights
- Single Docker image with all services (built via ./gradlew dockerBuildImages)
- Main API defined in config‐service‐api/config_service.proto
- Uses gRPC + Protobuf on the wire
- Integration tests verify end‐to‐end behavior

##### Main components
a. Client/Consumer Layer
– gRPC clients (other Hypertrace services or UIs)
b. API Layer
– config‐service‐api: Protobuf definitions
– alerting/labels/notification/etc. APIs
c. Service Runtime Layer (config‐service)
– ConfigServiceGrpcImpl (entry point)
– ConfigServiceFactory: wires up individual domain service impls
– Domain Service Modules (each implements its own ConfigServiceImpl)
- alerting‐config‐service‐impl
- labels‐config‐service‐impl
- notification‐channel/notification‐rule‐config‐service‐impl
- partitioner‐config‐service‐impl
- spaces‐config‐service‐impl
- span‐processing‐config‐service‐impl
d. Helper/Utility Modules
– config‐proto‐converter: DTO ↔ Proto mapping
– config‐validation‐utils: request validation logic
– config‐object‐store: generic object‐store abstraction
e. Persistence Layer
– DocumentConfigStore (backed by a NoSQL/Document DB—e.g., Couchbase, Cassandra, DynamoDB)
– ’store’ interfaces inside each domain impl
f. Eventing Layer
– config‐service‐change‐event‐api: event schema definitions
– config‐service‐change‐event‐generator: publishes events to Kafka (or another bus)
g. Operations / Deployment
– Docker image built by Gradle
– Helm chart (helm/Chart.yaml + templates): Kubernetes Deployment, Service, ConfigMap, Logging

##### Relationships and data flows
1) Client → gRPC (edge of system)
2) gRPC server → ConfigServiceGrpcImpl → ConfigServiceFactory
3) Factory → appropriate DomainServiceImpl
4) DomainServiceImpl →
a) proto‐converter for marshalling
b) validator for request checks
c) object‐store client for persistence
d) after write/update → change‐event generator
5) Persistence → Document DB
6) Change events → Kafka (or configured message bus)
7) Helm/K8s → deploys the Docker image and ConfigMaps

##### Architectural patterns & principles
- Modularization by domain (plug‐in style)
- “API first” via Protobuf/gRPC
- Factory pattern to assemble services in one server
- Separation of concerns: API, service logic, validation, conversion, persistence, eventing
- Event‐driven integration for config change notifications

– Clear component names matching module names
– Note on the bottom: build & deployment via Gradle → Docker → Helm/K8s

– Reflects each Gradle module’s role in the chain
– Shows how gRPC requests flow through factory & domain services
– Captures persistence and event‐driven integrations
– Illustrates the Kubernetes deployment topology via Helm

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client/Consumer Layer"
        Client["gRPC Clients"]:::external
    end

    subgraph "API Layer"
        cfgApi["config-service-api\n(proto)"]:::api
        alertApi["alerting-config-service-api"]:::api
        labelsApi["labels-config-service-api"]:::api
        notifChanApi["notification-channel-config-service-api"]:::api
        notifRuleApi["notification-rule-config-service-api"]:::api
        partApi["partitioner-config-service-api"]:::api
        spacesApi["spaces-config-service-api"]:::api
        spanApi["span-processing-config-service-api"]:::api
    end

    subgraph "Service Runtime Layer"
        grpcImpl["ConfigServiceGrpcImpl"]:::service
        factory["ConfigServiceFactory"]:::service

        subgraph "Domain Service Modules"
            alertImpl["EventConditionConfigServiceImpl"]:::service
            labelsImpl["LabelsConfigServiceImpl"]:::service
            notifChanImpl["NotificationChannelConfigServiceImpl"]:::service
            notifRuleImpl["NotificationRuleConfigServiceImpl"]:::service
            partImpl["PartitionerConfigServiceImpl"]:::service
            spacesImpl["SpacesConfigServiceImpl"]:::service
            spanImpl["SpanProcessingConfigServiceImpl"]:::service
        end

        subgraph "Utility Modules"
            converter["ConfigProtoConverter"]:::util
            validator["GrpcValidatorUtils"]:::util
            objStore["DefaultObjectStore"]:::util
        end

        grpcImpl -->|"calls"| factory
        factory --> alertImpl
        factory --> labelsImpl
        factory --> notifChanImpl
        factory --> notifRuleImpl
        factory --> partImpl
        factory --> spacesImpl
        factory --> spanImpl

        alertImpl -->|"uses converter"| converter
        labelsImpl -->|"uses converter"| converter
        notifChanImpl -->|"uses converter"| converter
        notifRuleImpl -->|"uses converter"| converter
        partImpl -->|"uses converter"| converter
        spacesImpl -->|"uses converter"| converter
        spanImpl -->|"uses converter"| converter

        alertImpl -->|"uses validator"| validator
        labelsImpl -->|"uses validator"| validator
        notifChanImpl -->|"uses validator"| validator
        notifRuleImpl -->|"uses validator"| validator
        partImpl -->|"uses validator"| validator
        spacesImpl -->|"uses validator"| validator
        spanImpl -->|"uses validator"| validator

        alertImpl -->|"uses object store"| objStore
        labelsImpl -->|"uses object store"| objStore
        notifChanImpl -->|"uses object store"| objStore
        notifRuleImpl -->|"uses object store"| objStore
        partImpl -->|"uses object store"| objStore
        spacesImpl -->|"uses object store"| objStore
        spanImpl -->|"uses object store"| objStore
    end

    subgraph "Persistence Layer"
        objStore --> docStore["DocumentConfigStore"]:::persistence
        docStore -->|"Document write/read"| DB["NoSQL Document DB"]:::persistence
    end

    subgraph "Eventing Layer"
        eventApi["config-service-change-event-api"]:::api
        eventGen["ConfigChangeEventGenerator"]:::event
        eventApi -->|"defines schema"| eventGen
        alertImpl -->|"change event"| eventGen
        labelsImpl -->|"change event"| eventGen
        notifChanImpl -->|"change event"| eventGen
        notifRuleImpl -->|"change event"| eventGen
        partImpl -->|"change event"| eventGen
        spacesImpl -->|"change event"| eventGen
        spanImpl -->|"change event"| eventGen
        eventGen -->|"publishes"| Kafka["Kafka (Message Bus)"]:::event
    end

    subgraph "Deployment"
        docker["Docker Image (Gradle Build)"]:::deploy
        helm["Helm Chart"]:::deploy
        kube["Kubernetes Deployment/ConfigMap"]:::deploy
        docker --> helm
        helm --> kube
    end

    Client -->|"gRPC/Protobuf"| cfgApi
    cfgApi -->|"gRPC/Protobuf"| grpcImpl

    click cfgApi "https://github.com/hypertrace/config-service/blob/main/config-service-api/src/main/proto/org/hypertrace/config/service/v1/config_service.proto"
    click alertApi "https://github.com/hypertrace/config-service/blob/main/alerting-config-service-api/src/main/proto/org/hypertrace/alerting/config/service/v1/event_condition_config_service.proto"
    click labelsApi "https://github.com/hypertrace/config-service/blob/main/labels-config-service-api/src/main/proto/org/hypertrace/label/config/service/v1/labels_config_service.proto"
    click notifChanApi "https://github.com/hypertrace/config-service/blob/main/notification-channel-config-service-api/src/main/proto/org/hypertrace/notification/config/service/v1/notification_channel_config_service.proto"
    click notifRuleApi "https://github.com/hypertrace/config-service/blob/main/notification-rule-config-service-api/src/main/proto/org/hypertrace/notification/config/service/v1/notification_rule_config_service.proto"
    click partApi "https://github.com/hypertrace/config-service/blob/main/partitioner-config-service-api/src/main/proto/org/hypertrace/partitioner/config/service/v1/partitioner_config_service.proto"
    click spacesApi "https://github.com/hypertrace/config-service/blob/main/spaces-config-service-api/src/main/proto/org/hypertrace/spaces/config/service/v1/spaces_config_service.proto"
    click spanApi "https://github.com/hypertrace/config-service/blob/main/span-processing-config-service-api/src/main/proto/org/hypertrace/span/processing/config/service/v1/span_processing_config_service.proto"
    click grpcImpl "https://github.com/hypertrace/config-service/blob/main/config-service-impl/src/main/java/org/hypertrace/config/service/ConfigServiceGrpcImpl.java"
    click factory "https://github.com/hypertrace/config-service/blob/main/config-service-factory/src/main/java/org/hypertrace/config/service/ConfigServiceFactory.java"
    click alertImpl "https://github.com/hypertrace/config-service/blob/main/alerting-config-service-impl/src/main/java/org/hypertrace/alerting/config/service/EventConditionConfigServiceImpl.java"
    click labelsImpl "https://github.com/hypertrace/config-service/blob/main/labels-config-service-impl/src/main/java/org/hypertrace/label/config/service/LabelsConfigServiceImpl.java"
    click notifChanImpl "https://github.com/hypertrace/config-service/blob/main/notification-channel-config-service-impl/src/main/java/org/hypertrace/notification/config/service/NotificationChannelConfigServiceImpl.java"
    click notifRuleImpl "https://github.com/hypertrace/config-service/blob/main/notification-rule-config-service-impl/src/main/java/org/hypertrace/notification/config/service/NotificationRuleConfigServiceImpl.java"
    click partImpl "https://github.com/hypertrace/config-service/blob/main/partitioner-config-service-impl/src/main/java/org/hypertrace/partitioner/config/service/PartitionerConfigServiceImpl.java"
    click spacesImpl "https://github.com/hypertrace/config-service/blob/main/spaces-config-service-impl/src/main/java/org/hypertrace/space/config/service/SpacesConfigServiceImpl.java"
    click spanImpl "https://github.com/hypertrace/config-service/blob/main/span-processing-config-service-impl/src/main/java/org/hypertrace/span/processing/config/service/SpanProcessingConfigServiceImpl.java"
    click converter "https://github.com/hypertrace/config-service/blob/main/config-proto-converter/src/main/java/org/hypertrace/config/proto/converter/ConfigProtoConverter.java"
    click validator "https://github.com/hypertrace/config-service/blob/main/config-validation-utils/src/main/java/org/hypertrace/config/validation/GrpcValidatorUtils.java"
    click objStore "https://github.com/hypertrace/config-service/blob/main/config-object-store/src/main/java/org/hypertrace/config/objectstore/DefaultObjectStore.java"
    click docStore "https://github.com/hypertrace/config-service/blob/main/config-service-impl/src/main/java/org/hypertrace/config/service/store/DocumentConfigStore.java"
    click eventApi "https://github.com/hypertrace/config-service/blob/main/config-service-change-event-api/src/main/proto/org/hypertrace/config/change/event/v1/config_change_event_key.proto"
    click eventGen "https://github.com/hypertrace/config-service/blob/main/config-service-change-event-generator/src/main/java/org/hypertrace/config/service/change/event/api/ConfigChangeEventGenerator.java"
    click helm "https://github.com/hypertrace/config-service/tree/main/helm"

    classDef api fill:#cce5ff,stroke:#004085,color:#004085
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef util fill:#fff3cd,stroke:#856404,color:#856404
    classDef persistence fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef event fill:#f5e6ff,stroke:#6f42c1,color:#6f42c1
    classDef deploy fill:#fff8e1,stroke:#ffb74d,color:#ffb74d
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
