# maheshpulivarthi18/opentelmetry architecture

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

- Interactive diagram: https://gitdiagram.com/maheshpulivarthi18/opentelmetry
- Repository: https://github.com/maheshpulivarthi18/opentelmetry

## Overview

This repository is a hands-on OpenTelemetry learning course, not a single deployed application. Its recurring workflow is a simulated checkout that produces telemetry, propagates trace context across services or a queue, and exports or correlates the resulting signals. Later exercises branch into database and external-API instrumentation, metrics, log correlation, and sampling. The graph represents the distinct chapter exercises and their demonstrated runtime interactions; source excerpts are limited, so undocumented wiring is omitted.

Main entry points: [`chapters/01-why-logs-fail/code/gateway.js`](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/01-why-logs-fail/code/gateway.js) (Untraced gateway), [`chapters/02-traces-and-spans/code/spans-demo.js`](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/02-traces-and-spans/code/spans-demo.js) (Trace and spans), [`chapters/06-distributed-tracing/code/backend.js`](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/backend.js) (Charge backend), [`chapters/06-distributed-tracing/code/queue.js`](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/queue.js) (Message queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fundamentals["Tracing Fundamentals"]
  node_plain_gateway["Untraced gateway<br/>[gateway.js]"]
  node_plain_backend["Untraced backend<br/>[backend.js]"]
  node_span_demo["Trace and spans<br/>[spans-demo.js]"]
end

subgraph group_services["Services and Propagation"]
  node_manual_gateway["Traceparent gateway<br/>[gateway.js]"]
  node_manual_backend["Traceparent backend<br/>[backend.js]"]
  node_coffee_demo["Propagation demo"]
  node_auto_gateway["Instrumented gateway<br/>[gateway.js]"]
  node_auto_backend["Instrumented backend<br/>[backend.js]"]
  node_tracing_setup["Auto-instrumentation setup<br/>[tracing.js]"]
  node_distributed_gateway["Checkout gateway<br/>[gateway.js]"]
  node_distributed_backend["Charge backend<br/>[backend.js]"]
  node_message_queue["Message queue<br/>[queue.js]"]
  node_notifications["Notifications worker<br/>[notifications.js]"]
end

subgraph group_collection["Export and Integrations"]
  node_collector_demo["OTLP span demo<br/>[spans-demo.js]"]
  node_collector["OTel Collector"]
  node_db_demo["Database instrumentation<br/>[db-demo.js]"]
  node_sqlite[("SQLite database")]
  node_api_client["Payment API client<br/>[client.js]"]
  node_fake_api["Fake payment API"]
end

subgraph group_signals["Signals and Sampling"]
  node_metrics_demo["Metrics demo<br/>[metrics-demo.js]"]
  node_logs_gateway["Trace-correlated gateway logs<br/>[gateway.js]"]
  node_logs_backend["Trace-correlated backend logs<br/>[backend.js]"]
  node_sampling_demo["Sampling demo<br/>[sampling-demo.js]"]
end

node_caller(("HTTP caller"))

node_caller -->|"requests checkout"| node_plain_gateway
node_plain_gateway -->|"calls charge"| node_plain_backend
node_span_demo -->|"creates child span"| node_span_demo
node_manual_gateway -->|"sends traceparent"| node_manual_backend
node_distributed_gateway -.->|"calls charge"| node_distributed_backend
node_distributed_backend -->|"enqueues receipt"| node_message_queue
node_notifications -->|"dequeues message"| node_message_queue
node_collector_demo -->|"exports spans"| node_collector
node_db_demo -->|"queries"| node_sqlite
node_api_client -->|"sends payment request"| node_fake_api
node_logs_gateway -->|"calls charge"| node_logs_backend

click node_plain_gateway "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/01-why-logs-fail/code/gateway.js"
click node_plain_backend "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/01-why-logs-fail/code/backend.js"
click node_span_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/02-traces-and-spans/code/spans-demo.js"
click node_manual_gateway "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/gateway.js"
click node_manual_backend "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/backend.js"
click node_coffee_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/coffee-shop-demo.js"
click node_auto_gateway "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/gateway.js"
click node_auto_backend "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/backend.js"
click node_tracing_setup "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/tracing.js"
click node_collector_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/05-collector/code/spans-demo.js"
click node_distributed_gateway "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/gateway.js"
click node_distributed_backend "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/backend.js"
click node_message_queue "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/queue.js"
click node_notifications "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/notifications.js"
click node_db_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/07-database-instrumentation/code/db-demo.js"
click node_api_client "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/08-external-apis/code/client.js"
click node_fake_api "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/08-external-apis/code/fake-external-api.js"
click node_metrics_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/09-metrics/code/metrics-demo.js"
click node_logs_gateway "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/10-logs/code/gateway.js"
click node_logs_backend "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/10-logs/code/backend.js"
click node_sampling_demo "https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/11-advanced-topics/code/sampling-demo.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plain_gateway,node_plain_backend,node_span_demo toneBlue
class node_manual_gateway,node_manual_backend,node_coffee_demo,node_auto_gateway,node_auto_backend,node_tracing_setup,node_distributed_gateway,node_distributed_backend,node_message_queue,node_notifications toneAmber
class node_collector_demo,node_collector,node_db_demo,node_sqlite,node_api_client,node_fake_api toneMint
class node_metrics_demo,node_logs_gateway,node_logs_backend,node_sampling_demo toneRose
class node_caller toneIndigo
```

## Components

### Tracing Fundamentals

- [Untraced gateway](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/01-why-logs-fail/code/gateway.js): `chapters/01-why-logs-fail/code/gateway.js`
- [Untraced backend](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/01-why-logs-fail/code/backend.js): `chapters/01-why-logs-fail/code/backend.js`
- [Trace and spans](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/02-traces-and-spans/code/spans-demo.js): `chapters/02-traces-and-spans/code/spans-demo.js`

### Services and Propagation

- [Traceparent gateway](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/gateway.js): `chapters/03-context-propagation/code/gateway.js`
- [Traceparent backend](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/backend.js): `chapters/03-context-propagation/code/backend.js`
- [Propagation demo](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/03-context-propagation/code/coffee-shop-demo.js): `chapters/03-context-propagation/code/coffee-shop-demo.js`
- [Instrumented gateway](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/gateway.js): `chapters/04-manual-instrumentation/code/gateway.js`
- [Instrumented backend](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/backend.js): `chapters/04-manual-instrumentation/code/backend.js`
- [Auto-instrumentation setup](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/04-manual-instrumentation/code/tracing.js): `chapters/04-manual-instrumentation/code/tracing.js`
- [Checkout gateway](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/gateway.js): `chapters/06-distributed-tracing/code/gateway.js`
- [Charge backend](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/backend.js): `chapters/06-distributed-tracing/code/backend.js`
- [Message queue](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/queue.js): `chapters/06-distributed-tracing/code/queue.js`
- [Notifications worker](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/06-distributed-tracing/code/notifications.js): `chapters/06-distributed-tracing/code/notifications.js`

### Export and Integrations

- [OTLP span demo](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/05-collector/code/spans-demo.js): `chapters/05-collector/code/spans-demo.js`
- **OTel Collector**
- [Database instrumentation](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/07-database-instrumentation/code/db-demo.js): `chapters/07-database-instrumentation/code/db-demo.js`
- **SQLite database**
- [Payment API client](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/08-external-apis/code/client.js): `chapters/08-external-apis/code/client.js`
- [Fake payment API](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/08-external-apis/code/fake-external-api.js): `chapters/08-external-apis/code/fake-external-api.js`

### Signals and Sampling

- [Metrics demo](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/09-metrics/code/metrics-demo.js): `chapters/09-metrics/code/metrics-demo.js`
- [Trace-correlated gateway logs](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/10-logs/code/gateway.js): `chapters/10-logs/code/gateway.js`
- [Trace-correlated backend logs](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/10-logs/code/backend.js): `chapters/10-logs/code/backend.js`
- [Sampling demo](https://github.com/maheshpulivarthi18/opentelmetry/blob/main/chapters/11-advanced-topics/code/sampling-demo.js): `chapters/11-advanced-topics/code/sampling-demo.js`

### Other components

- **HTTP caller**

## Connections

- HTTP caller → Untraced gateway: requests checkout (evidence: `chapters/01-why-logs-fail/code/gateway.js`)
- Untraced gateway → Untraced backend: calls charge (evidence: `chapters/01-why-logs-fail/code/gateway.js`)
- Trace and spans → Trace and spans: creates child span (evidence: `chapters/02-traces-and-spans/code/spans-demo.js`)
- Traceparent gateway → Traceparent backend: sends traceparent (evidence: `chapters/03-context-propagation/code/gateway.js`)
- Checkout gateway → Charge backend: calls charge
- Charge backend → Message queue: enqueues receipt (evidence: `chapters/06-distributed-tracing/code/backend.js`)
- Notifications worker → Message queue: dequeues message (evidence: `chapters/06-distributed-tracing/code/notifications.js`)
- OTLP span demo → OTel Collector: exports spans (evidence: `chapters/05-collector/code/spans-demo.js`)
- Database instrumentation → SQLite database: queries (evidence: `chapters/07-database-instrumentation/code/db-demo.js`)
- Payment API client → Fake payment API: sends payment request (evidence: `chapters/08-external-apis/code/client.js`)
- Trace-correlated gateway logs → Trace-correlated backend logs: calls charge (evidence: `chapters/10-logs/code/gateway.js`)
