# xuhpppp/python-opentelemetry architecture

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

- Interactive diagram: https://gitdiagram.com/xuhpppp/python-opentelemetry
- Repository: https://github.com/xuhpppp/python-opentelemetry

## Overview

##### Project type and purpose
- This is a single‐service, full‐stack backend demo: a FastAPI “Order Service” instrumented with OpenTelemetry, packaged via Docker Compose alongside a PostgreSQL database and an observability stack (Jaeger, Prometheus, cAdvisor, Grafana). Its primary goal is to demonstrate how to collect metrics, logs, and traces from a Python FastAPI app.

##### File structure
- Top level:
- Dockerfile, docker-compose.yml, .env.example – container builds & orchestration
- init.sql – DB schema/data initialization
- setup/ – monitoring configuration (Grafana datasources, Prometheus rules)
- src/ – application code
- src/ substructure:
- src/main.py – FastAPI entrypoint
- src/config/databases.py – DB connection
- src/orders/ – feature module with models.py, routers.py, services.py, telemetries.py
- No frontend; it’s a backend microservice with a single domain (orders).

##### README for additional insights
- The README confirms the use of Docker Compose to stand up:
- FastAPI service (port 8080)
- PostgreSQL (5432)
- Jaeger UI (16686)
- cAdvisor (8081)
- Prometheus (9090)
- Grafana (implicitly via setup folder)
- An “Architecture” image is referenced, showing how telemetry flows from the app to the observability tools.

##### Main components & interactions
- User / Client
- FastAPI Order Service
- PostgreSQL Database
- OpenTelemetry SDK & Exporters (in-app)
- Jaeger Collector & UI
- Prometheus Server
- cAdvisor
- Grafana (dashboards)
- Docker Compose boundary (optional container grouping)
b. Relationships & data flows:
1. HTTP request → FastAPI
2. FastAPI → SQL queries → PostgreSQL
3. OpenTelemetry instrumentation in FastAPI captures:
– Traces → Jaeger
– Metrics → Prometheus (scraped at /metrics)
4. Prometheus also scrapes metrics from cAdvisor
5. Grafana reads from Prometheus (configured via setup/grafana-datasources.yml)
c. Architectural patterns:
– Single microservice with clear separation of concerns (routers, services, models, telemetry)
– Observability pipeline pattern: instrumentation → collectors → storage/visualization
d. Key technologies:
– Python & FastAPI
– OpenTelemetry SDK
– PostgreSQL
– Docker & Docker Compose
– Jaeger, Prometheus, cAdvisor, Grafana

##### Detail level
- Sub-component only if it adds clarity (e.g., “Orders Router” vs “Order Service”).
- Config files implicitly by noting “Prometheus config” and “Grafana datasource” pointing at the respective services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose boundary
    subgraph "Docker Compose"
      direction TB

      User["User / Client"]:::external
      User -->|"HTTP (GET /orders/{id})"| FastAPI

      subgraph "Order Service"
        direction TB
        FastAPI["FastAPI Order Service\n(port 8080)"]:::app
        DBConn["DB Connection"]:::app
        Models["Orders Models"]:::app
        Routers["Orders API Routers"]:::app
        Services["Orders Business Logic"]:::app
        Telemetry["OpenTelemetry Instrumentation & Exporters"]:::telemetry

        FastAPI -->|"imports"| DBConn
        FastAPI -->|"imports"| Models
        FastAPI -->|"imports"| Routers
        FastAPI -->|"imports"| Services
        FastAPI -->|"imports"| Telemetry
      end

      FastAPI -->|"SQL"| Postgres
      FastAPI -->|"exposes /metrics"| Telemetry

      Postgres["PostgreSQL Database\n(port 5432)"]:::app

      subgraph "Observability"
        direction TB
        Jaeger["Jaeger Collector & UI\n(port 16686)"]:::obs
        Prometheus["Prometheus Server\n(port 9090)"]:::obs
        cAdvisor["cAdvisor\n(port 8081)"]:::obs
        Grafana["Grafana Dashboards"]:::obs

        Telemetry -->|"OTLP/Zipkin"| Jaeger
        Prometheus -->|"scrapes metrics"| Telemetry
        Prometheus -->|"scrapes metrics"| cAdvisor
        Grafana -->|"reads metrics"| Prometheus
      end
    end

    %% Configuration files and docs
    subgraph "Configuration & Docs"
      direction TB
      ComposeYML["docker-compose.yml"]:::config
      Dockerfile["Dockerfile"]:::config
      InitSQL["init.sql"]:::config
      PromConfig["setup/prometheus.yml"]:::config
      GrafanaConfig["setup/grafana-datasources.yml"]:::config
      EnvExample[".env.example"]:::config
      Requirements["requirements.txt"]:::config
      Drawio["docs/common.drawio"]:::config
      DocsImgs["docs/imgs/"]:::config
    end

    %% Click Events
    click FastAPI "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/main.py"
    click DBConn "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/config/databases.py"
    click Models "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/orders/models.py"
    click Routers "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/orders/routers.py"
    click Services "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/orders/services.py"
    click Telemetry "https://github.com/xuhpppp/python-opentelemetry/blob/main/src/orders/telemetries.py"
    click ComposeYML "https://github.com/xuhpppp/python-opentelemetry/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/xuhpppp/python-opentelemetry/tree/main/Dockerfile"
    click InitSQL "https://github.com/xuhpppp/python-opentelemetry/blob/main/init.sql"
    click PromConfig "https://github.com/xuhpppp/python-opentelemetry/blob/main/setup/prometheus.yml"
    click GrafanaConfig "https://github.com/xuhpppp/python-opentelemetry/blob/main/setup/grafana-datasources.yml"
    click Drawio "https://github.com/xuhpppp/python-opentelemetry/blob/main/docs/common.drawio"
    click DocsImgs "https://github.com/xuhpppp/python-opentelemetry/tree/main/docs/imgs/"
    click EnvExample "https://github.com/xuhpppp/python-opentelemetry/blob/main/.env.example"
    click Requirements "https://github.com/xuhpppp/python-opentelemetry/blob/main/requirements.txt"

    %% Styles
    classDef app fill:#D0E8FF,stroke:#2B6CB0,stroke-width:2px;
    classDef telemetry fill:#FFE5B4,stroke:#DD6B20,stroke-width:2px;
    classDef obs fill:#D4F4DD,stroke:#2F855A,stroke-width:2px;
    classDef external fill:#E2E8F0,stroke:#4A5568,stroke-width:2px;
    classDef config fill:#F0E68C,stroke:#D69E2E,stroke-width:2px;
```
