# bhanuwealthy/otel-demo architecture

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

- Interactive diagram: https://gitdiagram.com/bhanuwealthy/otel-demo
- Repository: https://github.com/bhanuwealthy/otel-demo

## Overview

##### Project type and purpose
- This is a small microservice demo (“otel-demo”) showcasing end-to-end observability using OpenTelemetry.
- It includes two Go services (order, user), a Python-based traffic generator, backing data stores (MongoDB, Redis), an OTel Collector, and the observability backend (Tempo for traces, VictoriaMetrics for metrics, Grafana).
- Local deployment manifests live under `kind-deployments` and `local-setup`, indicating a Kubernetes-based local cluster.

##### Break out the top-level components
a. Microservices layer
- user-service (Go)
- order-service (Go)
b. Traffic generator
- py-project/run.py + postman.js (simulates client calls)
c. Data layer
- MongoDB (persistent user/order data)
- Redis (cache or auxiliary store)
d. Observability pipeline
- Instrumentation libraries (utils/otel.go, middleware.go) embedded in services
- OpenTelemetry Collector (receives traces & metrics)
- Tempo (distributed trace store)
- VictoriaMetrics (time-series metrics store)
e. Visualization
- Grafana dashboards (datasources configured via local-setup/grafana-datasources.yaml)

##### Relationships and data-flows
- Traffic generator → user-service & order-service (HTTP calls)
- user-service ↔ MongoDB
- order-service ↔ MongoDB (and/or Redis)
- Each service → OTel Collector (OTLP export of traces & metrics)
- Collector → Tempo (traces)
- Collector → VictoriaMetrics (metrics)
- Grafana → Tempo & VictoriaMetrics (reads data for dashboards)

##### Architectural patterns and design principles
- Microservices loosely coupled via HTTP/REST
- Centralized observability pipeline (Collector) decouples instrumentation from backends
- Infrastructure as Code: Kubernetes manifests (kind-deployments) + local-setup for local docker/kind cluster
- Clear separation of concerns: application code, infra code, docs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Traffic Generator
    TG["Traffic Generator (Python)"]:::client

    subgraph "Kind Cluster" 
        direction TB

        %% Application Services
        US["user-service (Go)"]:::service
        OS["order-service (Go)"]:::service
        UT["Instrumentation Libs (Go)"]:::obs

        %% Observability Collector
        Col["OpenTelemetry Collector"]:::obs

        %% Data Stores
        Mongo["MongoDB"]:::datastore
        Redis["Redis"]:::datastore

        %% Observability Backends
        Tempo["Tempo (Traces)"]:::datastore
        VM["VictoriaMetrics (Metrics)"]:::datastore

        %% Visualization
        Graf["Grafana"]:::viz
    end

    %% Traffic to services
    TG -->|HTTP| US
    TG -->|HTTP| OS

    %% Services to DBs
    US -->|MongoDB| Mongo
    OS -->|MongoDB| Mongo
    OS -->|Redis| Redis

    %% Services to Collector
    US -->|OTLP-GRPC| Col
    OS -->|OTLP-GRPC| Col
    UT -->|embedded in| US
    UT -->|embedded in| OS

    %% Collector to Backends
    Col -->|Traces| Tempo
    Col -->|Metrics| VM

    %% Grafana queries
    Graf -->|Queries| Tempo
    Graf -->|Queries| VM

    %% Click Events
    click US "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/user/server.go"
    click US "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/user/users.go"
    click OS "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/order/server.go"
    click OS "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/order/order.go"
    click UT "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/utils/otel.go"
    click UT "https://github.com/bhanuwealthy/otel-demo/blob/main/go-project/utils/middleware.go"
    click TG "https://github.com/bhanuwealthy/otel-demo/blob/main/py-project/run.py"
    click TG "https://github.com/bhanuwealthy/otel-demo/blob/main/py-project/postman.js"
    click Mongo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/mongodb-deployment.yaml"
    click Mongo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/mongodb-service.yaml"
    click Mongo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/mongodb-claim0-persistentvolumeclaim.yaml"
    click Mongo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/mongodb-claim1-persistentvolumeclaim.yaml"
    click Mongo "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/local-mongo-init.js"
    click Redis "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/redis-deployment.yaml"
    click Redis "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/redis-service.yaml"
    click Col "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/otelcol-deployment.yaml"
    click Col "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/otelcol-service.yaml"
    click Col "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/otelcol-claim0-persistentvolumeclaim.yaml"
    click Col "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/otel-collector-config.yaml"
    click Tempo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/tempo-deployment.yaml"
    click Tempo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/tempo-service.yaml"
    click Tempo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/tempo-claim0-persistentvolumeclaim.yaml"
    click Tempo "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/tempo-claim1-persistentvolumeclaim.yaml"
    click Tempo "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/tempo.yaml"
    click VM "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/victoria-deployment.yaml"
    click VM "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/victoria-service.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/grafana-deployment.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/grafana-service.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/kind-deployments/grafana-claim0-persistentvolumeclaim.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/grafana-datasources.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/local-cluster.yaml"
    click Graf "https://github.com/bhanuwealthy/otel-demo/blob/main/local-setup/local-dockercompose.yaml"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366D6,stroke-width:2px;
    classDef datastore fill:#E6F4EA,stroke:#22863A,stroke-width:2px;
    classDef obs fill:#FFF5E6,stroke:#D9822B,stroke-width:2px;
    classDef viz fill:#F0E6FF,stroke:#6F42C1,stroke-width:2px;
    classDef client fill:#EDF5FF,stroke:#005CC5,stroke-width:2px,stroke-dasharray: 5 5;
```
