# miguelsmuller/lab-observability architecture

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

- Interactive diagram: https://gitdiagram.com/miguelsmuller/lab-observability
- Repository: https://github.com/miguelsmuller/lab-observability

## Overview

##### Project Type & Purpose
- This project is designed as an experimentation environment focused on observability. It includes two microservices – one written in Kotlin and another in Python – alongside a monitoring/observability platform, SigNoz.
- The goal is to demonstrate and learn about monitoring, distributed tracing, and centralized logging by instrumenting these microservices and integrating with SigNoz.

##### Analyzing the File Structure
- There are clearly two main application components:
– The “kotlin-app” directory hosts the Kotlin microservice, which follows a layered/hexagonal architecture pattern. Notice the separation into:
▪ Application entry point (KotlinAppApplication.kt)
▪ Adapters for incoming requests (controllers)
▪ Adapters for outgoing integrations (client, e.g., PythonAppClient)
▪ Environment-specific configurations in application-{env}.yaml.
– The “python-app” directory contains the Python microservice with its own Dockerfile, configuration (pyproject.toml), and tests.
- The presence of Dockerfiles in both subprojects along with a top-level “compose.yaml” suggests that container orchestration is a key aspect.
- Additionally, a “signoz” directory and a reference to SigNoz in the README indicate that a full observability stack is used for metrics, logs, and traces.
- Other files include build scripts (Gradle for Kotlin), submodules, and documentation (docs/ directory).

a. Main Components:
- Kotlin Microservice – “kotlin-app”
- Python Microservice – “python-app”
- Observability Platform – SigNoz (deployed via Docker Compose in the “signoz” directory)
- Additional components include:
▪ Docker Compose orchestration that brings up all containers.
▪ Subsystems within each microservice (e.g., controllers and client adapters in Kotlin).
b. Relationships and Interactions:
- Both microservices are instrumented to send metrics, traces, and logs to the SigNoz observability platform.
- The Kotlin microservice further structures its code into inbound (controllers) and outbound (client integrator to Python) adapters, reflecting a hexagonal architecture.
- The deployment layer (Docker Compose) should be shown orchestrating the start-up of each container/service.
c. Architectural Patterns and Design Principles:
- Hexagonal (ports & adapters) architecture in the Kotlin service: clearly separate internal domain logic from external interfaces.
- Containerization and orchestration (Docker, Docker Compose) to manage the microservices and observability stack.
- Emphasis on observability: all components emit metrics, logs, and traces to SigNoz.
d. Relevant Technologies and Frameworks:
- Kotlin with Gradle for the Kotlin app.
- Python for another microservice using pyproject.toml (likely a framework like Flask/FastAPI, though not explicitly stated—review the “app” directory for clues).
- Docker files for containerization.
- SigNoz to aggregate observability data, using OpenTelemetry (OTel) instrumentation, as referenced by the documentation links.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Container Orchestration Layer
    subgraph "Deployment"
        DockerCompose["Docker Compose"]:::orchestration
    end

    %% Microservices Layer
    subgraph "Microservices"
        %% Kotlin Microservice Subgraph
        subgraph "Kotlin Microservice"
            KotlinApp["Kotlin Microservice (Entry Point)"]:::service
            Inbound["API Controller (Inbound Adapters)"]:::adapter
            Outbound["Python Client (Outbound Adapter)"]:::adapter
            Config["Environment Configurations"]:::config
            KotlinApp --> Inbound
            KotlinApp --> Outbound
            KotlinApp -.-> Config
        end

        %% Python Microservice Subgraph
        subgraph "Python Microservice"
            PythonApp["Python Microservice (Core & Instrumentation)"]:::service
            PythonConfig["Build & Configuration"]:::config
            PythonDockerfile["Dockerfile"]:::config
            PythonApp --> PythonConfig
            PythonApp -.-> PythonDockerfile
        end
    end

    %% Observability Platform
    subgraph "Observability"
        SigNoz["SigNoz Observability Platform"]:::observability
    end

    %% Relationships between Layers
    DockerCompose --> KotlinApp
    DockerCompose --> PythonApp
    DockerCompose --> SigNoz

    KotlinApp -->|"reports_metrics/logs/traces"| SigNoz
    PythonApp -->|"reports_metrics/logs/traces"| SigNoz
    Outbound -->|"calls"| PythonApp

    %% Styles
    classDef service fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef adapter fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef orchestration fill:#a9dfbf,stroke:#229954,stroke-width:2px;
    classDef observability fill:#fad7a0,stroke:#d35400,stroke-width:2px;

    %% Click Events for Kotlin Microservice
    click KotlinApp "https://github.com/miguelsmuller/lab-observability/blob/main/kotlin-app/src/main/kotlin/lab/observability/kotlin_app/KotlinAppApplication.kt"
    click Inbound "https://github.com/miguelsmuller/lab-observability/tree/main/kotlin-app/src/main/kotlin/lab/observability/kotlin_app/adapters/in/controller"
    click Outbound "https://github.com/miguelsmuller/lab-observability/blob/main/kotlin-app/src/main/kotlin/lab/observability/kotlin_app/adapters/out/client/PythonAppClient.kt"
    click Config "https://github.com/miguelsmuller/lab-observability/tree/main/kotlin-app/src/main/resources"

    %% Click Events for Python Microservice
    click PythonApp "https://github.com/miguelsmuller/lab-observability/tree/main/python-app/app"
    click PythonConfig "https://github.com/miguelsmuller/lab-observability/blob/main/python-app/pyproject.toml"
    click PythonDockerfile "https://github.com/miguelsmuller/lab-observability/tree/main/python-app/dockerfile"

    %% Click Events for Observability and Orchestration
    click SigNoz "https://github.com/miguelsmuller/lab-observability/tree/main/signoz"
    click DockerCompose "https://github.com/miguelsmuller/lab-observability/blob/main/compose.yaml"
```
