# ghbihuy123/astrotel architecture

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

- Interactive diagram: https://gitdiagram.com/ghbihuy123/astrotel
- Repository: https://github.com/ghbihuy123/astrotel

## Overview

##### Project type and purpose
- Astrotel is a Python library (not a standalone web service) that integrates application frameworks (FastAPI, Celery) with OpenTelemetry tracing and logging, exporting data to OTEL collectors or backends (Signoz, Jaeger).

##### File structure
- src/astrotel/
- base.py         – core abstractions for tracing/logging
- config.py       – environment-driven settings loader
- error.py        – custom exceptions and error handling
- provider/       – framework adapters
· fastapi.py    – FastAPI tracer setup
· celery.py     – Celery tracer setup
- Tests and CI configs (.github/workflows) confirm a library project with linters, formatting, tests, and release pipelines.

##### README for additional insights
- Describes Python ≥3.12, pip install extras ([fastapi]), usage code snippets, env-var configuration, supported exporters (HTTP/gRPC), and integration points (logging handler).

##### Main components & relationships
a. Client Application
- FastAPI app or Celery worker code calls into Astrotel.provider.*
b. Astrotel Library
- Core modules (base, config, error)
- Provider modules inject middleware spans, configure log handler
c. OpenTelemetry SDK Pipeline
- Span processors, BatchSpanProcessor
- Exporter (OTLP HTTP or gRPC)
d. OTEL Collector (or direct exporter)
- Receives traces/logs
- Forwards to backends (Signoz, Jaeger)
e. Backend Systems
- Signoz, Jaeger, other tracing UIs

Data flow:
1. HTTP request → FastAPI endpoint
2. Provider.fastapi config adds tracing middleware → Spans emitted
3. Logging via Python logging + Astrotel handler → LogRecords forwarded as telemetry
4. Spans/Logs flow through OTEL SDK → Exporter
5. Exporter sends telemetry to Collector (via HTTP/gRPC) → Backend UI

##### Architectural patterns & design principles
- Adapter pattern: provider modules implement framework-specific hooks
- Configuration via environment variables
- Separation of concerns: core tracing logic vs. framework adapters
- Modular, extensible for new frameworks or exporters

##### Detailed capture
- Support for HTTP vs. gRPC exporters
- “Application Runtime”
- “Telemetry Pipeline”
- “External Systems”

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Runtime
    subgraph "Application Runtime"
        direction TB
        AppFastAPI["FastAPI App"]:::app
        AppCelery["Celery Worker"]:::app
        AppLogger["Application Logger"]:::app

        subgraph "Astrotel Library"
            direction TB
            CoreBase["Astrotel Core\n(base.py)"]:::lib
            CoreConfig["Astrotel Config\n(config.py)"]:::lib
            CoreError["Astrotel Error\n(error.py)"]:::lib
            ProviderFASTAPI["FastAPI Provider\n(fastapi.py)"]:::lib
            ProviderCelery["Celery Provider\n(celery.py)"]:::lib
            LoggingHandler["Astrotel Logging Handler"]:::lib
        end
    end

    %% Telemetry Pipeline
    subgraph "Telemetry Pipeline"
        direction TB
        SpanProcessor["BatchSpanProcessor"]:::telemetry
        Exporter["OTLP Exporter\n(HTTP/gRPC)"]:::telemetry
        OTELSDK["OpenTelemetry SDK"]:::telemetry
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Collector["OTEL Collector"]:::external
        Signoz["Signoz"]:::external
        Jaeger["Jaeger"]:::external
    end

    %% Project Artifacts
    subgraph "Project Artifacts"
        direction TB
        Pyproject["pyproject.toml"]:::artifact
        Readme["README.md"]:::artifact
        CIBuild["_build.yml"]:::artifact
        CILint["_lint.yml"]:::artifact
        CITest["_test.yml"]:::artifact
        CIRelease["_release.yml"]:::artifact
        CICi["ci.yml"]:::artifact
        DocsConf["docs/conf.py"]:::artifact
        DocsIndex["docs/index.rst"]:::artifact
    end

    %% Connections - Application to Library
    AppFastAPI -->|"uses"| ProviderFASTAPI
    AppCelery -->|"uses"| ProviderCelery
    AppLogger -->|"sends logs to"| LoggingHandler
    ProviderFASTAPI -->|"calls"| CoreBase
    ProviderCelery -->|"calls"| CoreBase
    ProviderFASTAPI -->|"reads config"| CoreConfig
    ProviderCelery -->|"reads config"| CoreConfig
    CoreBase -->|"raises errors"| CoreError
    LoggingHandler -->|"forwards logs"| SpanProcessor

    %% Connections - Library to Telemetry Pipeline
    ProviderFASTAPI -->|"emits spans"| SpanProcessor
    ProviderCelery -->|"emits spans"| SpanProcessor
    SpanProcessor -->|"processes spans"| OTELSDK
    OTELSDK -->|"exports spans/logs"| Exporter

    %% Connections - Telemetry to External
    Exporter -->|"sends telemetry"| Collector
    Collector -->|"forwards to"| Signoz
    Collector -->|"forwards to"| Jaeger

    %% Click Events
    click CoreBase "https://github.com/ghbihuy123/astrotel/blob/main/src/astrotel/base.py"
    click CoreConfig "https://github.com/ghbihuy123/astrotel/blob/main/src/astrotel/config.py"
    click CoreError "https://github.com/ghbihuy123/astrotel/blob/main/src/astrotel/error.py"
    click ProviderFASTAPI "https://github.com/ghbihuy123/astrotel/blob/main/src/astrotel/provider/fastapi.py"
    click ProviderCelery "https://github.com/ghbihuy123/astrotel/blob/main/src/astrotel/provider/celery.py"
    click Pyproject "https://github.com/ghbihuy123/astrotel/blob/main/pyproject.toml"
    click Readme "https://github.com/ghbihuy123/astrotel/blob/main/README.md"
    click CIBuild "https://github.com/ghbihuy123/astrotel/blob/main/.github/workflows/_build.yml"
    click CILint "https://github.com/ghbihuy123/astrotel/blob/main/.github/workflows/_lint.yml"
    click CITest "https://github.com/ghbihuy123/astrotel/blob/main/.github/workflows/_test.yml"
    click CIRelease "https://github.com/ghbihuy123/astrotel/blob/main/.github/workflows/_release.yml"
    click CICi "https://github.com/ghbihuy123/astrotel/blob/main/.github/workflows/ci.yml"
    click DocsConf "https://github.com/ghbihuy123/astrotel/blob/main/docs/conf.py"
    click DocsIndex "https://github.com/ghbihuy123/astrotel/blob/main/docs/index.rst"

    %% Styles
    classDef app fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef lib fill:#b3d9ff,stroke:#333,stroke-width:1px
    classDef telemetry fill:#d9f2d9,stroke:#333,stroke-width:1px
    classDef external fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef artifact fill:#f2f2f2,stroke:#666,stroke-width:1px,stroke-dasharray: 3 3
```
