# piyushsachdeva/ai-observability-with-otel-and-honeycomb architecture

> Architecture diagram of the GitHub repository piyushsachdeva/ai-observability-with-otel-and-honeycomb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb
- Repository: https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb

## Overview

1. This repo is a Kubernetes-based demo application for URL shortening and observability. The main application stack lives under `honeycomb-demo/`, with Kubernetes manifests, OpenTelemetry config, service entrypoints, and operational scripts.

2. The core runtime is split into three application services: `link-service`, `redirect-service`, and `stats-service`. Their `main.go` files under `patches/services/*` suggest each service is independently deployable and wired from a shared codebase or patches layer.

3. `link-service` is the write path. The presence of `patches/internal/adapters/repository/postgres/link.go` shows a repository adapter for storing link records in PostgreSQL, so this service is the main persistence boundary for created short links.

4. `redirect-service` is the read/serve path. It likely resolves a short code into a destination URL and handles the high-volume redirect traffic. This is the most latency-sensitive service in the system.

5. `stats-service` is the analytics boundary. It aggregates or exposes usage data for links/redirects, likely reading from the database and/or a cache rather than serving the redirect path directly.

6. PostgreSQL is the primary durable datastore, deployed via `k8s/02-postgres.yaml`. Redis is a separate infrastructure component in `k8s/03-redis.yaml`, which implies the app uses a fast ephemeral store for caching, counters, or request state.

7. Observability is first-class. `k8s/04-otel-collector.yaml` and `otel/collector-config.yaml` define an in-cluster OpenTelemetry Collector, and `patches/otel/otel.go` indicates shared instrumentation setup inside the services. Telemetry is therefore routed through the collector rather than sent directly from each service to a backend.

8. `k8s/05-feature-flags.yaml` adds a feature-flag subsystem inside the cluster. That makes runtime behavior configurable without redeploying the services, which is important for demos and controlled experiments.

9. The user-facing edge is split between `frontend`, `nginx`, and `ingress`. `frontend` is the UI layer, `nginx` likely serves or reverse-proxies it, and `k8s/11-ingress.yaml` exposes the stack externally. Requests then fan out from the ingress to the frontend and API services.

10. Deployment is fully Kubernetes-native and ordered by numbered manifests: namespace, secrets, backing services, observability, app services, edge, and ingress. `k8s/01-secrets.yaml` is the shared configuration boundary for credentials and sensitive settings.

11. The `scripts/` folder defines operational workflows around the app: `apply.sh` deploys the stack, `load-test.sh` generates traffic, and `inject-chaos.sh` / `remove-chaos.sh` support resilience testing. These are not part of the product path, but they are important to the repo’s demo architecture.

12. `ubuntu-nodegroup.yaml` suggests the cluster runs on a cloud-managed node group, so the deployment model is “Kubernetes on provisioned Linux worker nodes” rather than a local-only demo.

13. For an architecture diagram, the key flows are: external user traffic enters through ingress/nginx to the frontend and API services; `link-service` writes to Postgres; `redirect-service` serves redirects and may consult Redis/Postgres; `stats-service` reads aggregated data; and all services emit telemetry to the OpenTelemetry Collector, which is the central observability hub.

Main entry points: [`honeycomb-demo/scripts/apply.sh`](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/apply.sh) (Apply Script), [`honeycomb-demo/patches/services/redirect-service/main.go`](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/redirect-service/main.go) (Redirect Service), [`honeycomb-demo/patches/services/stats-service/main.go`](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/stats-service/main.go) (Stats Service), [`honeycomb-demo/patches/services/link-service/main.go`](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/link-service/main.go) (Link Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_namespace["Namespace<br/>[00-namespace.yaml]"]
  node_secrets["Secrets<br/>k8s config<br/>[01-secrets.yaml]"]
  node_postgres[("Postgres<br/>database<br/>[02-postgres.yaml]")]
  node_redis[("Redis<br/>cache<br/>[03-redis.yaml]")]
  node_flags["Feature Flags<br/>runtime flags"]
  node_ingress["Ingress<br/>[11-ingress.yaml]"]
end

subgraph group_app["Application"]
  node_linksvc["Link Service<br/>write API<br/>[main.go]"]
  node_linkrepo["Postgres Adapter<br/>repo adapter<br/>[link.go]"]
  node_redirectsvc["Redirect Service<br/>read path<br/>[main.go]"]
  node_statssvc["Stats Service<br/>analytics API<br/>[main.go]"]
  node_frontend["Frontend<br/>ui<br/>[10-frontend.yaml]"]
  node_nginx["Nginx<br/>edge proxy<br/>[09-nginx.yaml]"]
end

subgraph group_obs["Observability"]
  node_otelcollector["OTel Collector<br/>telemetry collector"]
  node_otelconfig["Collector Config<br/>otel config"]
  node_otelshared["Shared OTEL<br/>instrumentation<br/>[otel.go]"]
end

subgraph group_ops["Operations"]
  node_apply["Apply Script<br/>deploy script<br/>[apply.sh]"]
  node_loadtest["Load Test<br/>traffic script<br/>[load-test.sh]"]
  node_chaos["Chaos Scripts<br/>resilience scripts<br/>[inject-chaos.sh]"]
end

node_apply -->|"creates"| node_namespace
node_apply -->|"applies"| node_secrets
node_apply -->|"deploys"| node_postgres
node_apply -->|"deploys"| node_redis
node_apply -->|"deploys"| node_otelcollector
node_apply -->|"deploys"| node_flags
node_apply -->|"deploys"| node_linksvc
node_apply -->|"deploys"| node_redirectsvc
node_apply -->|"deploys"| node_statssvc
node_apply -->|"deploys"| node_nginx
node_apply -->|"deploys"| node_frontend
node_apply -->|"exposes"| node_ingress
node_ingress -->|"routes"| node_nginx
node_ingress -->|"routes"| node_frontend
node_frontend -->|"creates links"| node_linksvc
node_frontend -->|"resolves"| node_redirectsvc
node_frontend -->|"shows stats"| node_statssvc
node_nginx -->|"serves"| node_frontend
node_linksvc -->|"uses"| node_linkrepo
node_linkrepo -->|"writes"| node_postgres
node_redirectsvc -->|"consults"| node_redis
node_redirectsvc -->|"falls back"| node_postgres
node_statssvc -->|"reads"| node_postgres
node_statssvc -->|"reads"| node_redis
node_linksvc -->|"checks"| node_flags
node_redirectsvc -->|"checks"| node_flags
node_statssvc -->|"checks"| node_flags
node_linksvc -->|"instruments"| node_otelshared
node_redirectsvc -->|"instruments"| node_otelshared
node_statssvc -->|"instruments"| node_otelshared
node_otelshared -->|"exports"| node_otelcollector
node_otelcollector -->|"configured by"| node_otelconfig
node_loadtest -->|"targets"| node_ingress
node_chaos -->|"stresses"| node_linksvc
node_chaos -->|"stresses"| node_redirectsvc

click node_namespace "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/00-namespace.yaml"
click node_secrets "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/01-secrets.yaml"
click node_postgres "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/02-postgres.yaml"
click node_redis "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/03-redis.yaml"
click node_flags "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/05-feature-flags.yaml"
click node_otelcollector "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/04-otel-collector.yaml"
click node_otelconfig "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/otel/collector-config.yaml"
click node_otelshared "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/otel/otel.go"
click node_linksvc "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/link-service/main.go"
click node_linkrepo "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/internal/adapters/repository/postgres/link.go"
click node_redirectsvc "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/redirect-service/main.go"
click node_statssvc "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/stats-service/main.go"
click node_frontend "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/10-frontend.yaml"
click node_nginx "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/09-nginx.yaml"
click node_ingress "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/11-ingress.yaml"
click node_apply "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/apply.sh"
click node_loadtest "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/load-test.sh"
click node_chaos "https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/inject-chaos.sh"

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_namespace,node_secrets,node_postgres,node_redis,node_flags,node_ingress toneBlue
class node_linksvc,node_linkrepo,node_redirectsvc,node_statssvc,node_frontend,node_nginx toneAmber
class node_otelcollector,node_otelconfig,node_otelshared toneMint
class node_apply,node_loadtest,node_chaos toneRose
```

## Components

### Platform

Cluster resources and external entrypoints

- [Namespace](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/00-namespace.yaml): k8s namespace · Shared Kubernetes namespace for the demo stack · `honeycomb-demo/k8s/00-namespace.yaml`
- [Secrets](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/01-secrets.yaml): k8s config · Shared sensitive configuration for services · `honeycomb-demo/k8s/01-secrets.yaml`
- [Postgres](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/02-postgres.yaml): database · Primary durable store for links and analytics · `honeycomb-demo/k8s/02-postgres.yaml`
- [Redis](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/03-redis.yaml): cache · Ephemeral fast store for caching or counters · `honeycomb-demo/k8s/03-redis.yaml`
- [Feature Flags](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/05-feature-flags.yaml): runtime flags · In-cluster feature-flag subsystem for live behavior changes · `honeycomb-demo/k8s/05-feature-flags.yaml`
- [Ingress](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/11-ingress.yaml): cluster ingress · External entrypoint into the demo stack · `honeycomb-demo/k8s/11-ingress.yaml`

### Application

User-facing services and data path

- [Link Service](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/link-service/main.go): write API · Creates short links and persists them · `honeycomb-demo/patches/services/link-service/main.go`
- [Postgres Adapter](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/internal/adapters/repository/postgres/link.go): repo adapter · PostgreSQL persistence adapter for link records · `honeycomb-demo/patches/internal/adapters/repository/postgres/link.go`
- [Redirect Service](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/redirect-service/main.go): read path · Resolves short codes and serves redirects · `honeycomb-demo/patches/services/redirect-service/main.go`
- [Stats Service](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/services/stats-service/main.go): analytics API · Exposes link and redirect usage data · `honeycomb-demo/patches/services/stats-service/main.go`
- [Frontend](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/10-frontend.yaml): ui · User interface for creating and viewing links · `honeycomb-demo/k8s/10-frontend.yaml`
- [Nginx](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/09-nginx.yaml): edge proxy · Serves or reverse-proxies the frontend and API traffic · `honeycomb-demo/k8s/09-nginx.yaml`

### Observability

Telemetry pipeline and shared instrumentation

- [OTel Collector](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/k8s/04-otel-collector.yaml): telemetry collector · Central OpenTelemetry aggregation and export point · `honeycomb-demo/k8s/04-otel-collector.yaml`
- [Collector Config](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/otel/collector-config.yaml): otel config · Collector pipeline and export configuration · `honeycomb-demo/otel/collector-config.yaml`
- [Shared OTEL](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/patches/otel/otel.go): instrumentation · Common service-side OpenTelemetry setup · `honeycomb-demo/patches/otel/otel.go`

### Operations

Deployment and test workflows

- [Apply Script](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/apply.sh): deploy script · Deploys the Kubernetes stack in order · `honeycomb-demo/scripts/apply.sh`
- [Load Test](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/load-test.sh): traffic script · Generates traffic against the running system · `honeycomb-demo/scripts/load-test.sh`
- [Chaos Scripts](https://github.com/piyushsachdeva/ai-observability-with-otel-and-honeycomb/blob/main/honeycomb-demo/scripts/inject-chaos.sh): resilience scripts · Injects and removes chaos for fault testing · `honeycomb-demo/scripts/inject-chaos.sh`

## Connections

- Apply Script → Namespace: creates · Bootstraps the shared namespace
- Apply Script → Secrets: applies · Installs shared configuration and credentials
- Apply Script → Postgres: deploys · Brings up the durable datastore
- Apply Script → Redis: deploys · Brings up the cache layer
- Apply Script → OTel Collector: deploys · Installs the telemetry collector
- Apply Script → Feature Flags: deploys · Installs runtime feature flags
- Apply Script → Link Service: deploys · Installs the write service
- Apply Script → Redirect Service: deploys · Installs the redirect service
- Apply Script → Stats Service: deploys · Installs the analytics service
- Apply Script → Nginx: deploys · Installs the edge proxy
- Apply Script → Frontend: deploys · Installs the UI layer
- Apply Script → Ingress: exposes · Configures external access
- Ingress → Nginx: routes · Sends public traffic to the edge proxy
- Ingress → Frontend: routes · Exposes the user interface
- Frontend → Link Service: creates links · UI submits new short-link requests
- Frontend → Redirect Service: resolves · UI-facing navigation and redirect interactions
- Frontend → Stats Service: shows stats · UI fetches analytics views
- Nginx → Frontend: serves · Proxies or serves the frontend
- Link Service → Postgres Adapter: uses · Delegates persistence to the repository adapter
- Postgres Adapter → Postgres: writes · Stores link records in PostgreSQL
- Redirect Service → Redis: consults · Uses cache for fast redirect lookups or counters
- Redirect Service → Postgres: falls back · May read durable link data when needed
- Stats Service → Postgres: reads · Aggregates or queries usage data from storage
- Stats Service → Redis: reads · May use cached counters or summaries
- Link Service → Feature Flags: checks · Uses feature flags to alter runtime behavior
- Redirect Service → Feature Flags: checks · Uses feature flags on the hot path
- Stats Service → Feature Flags: checks · Uses feature flags for analytics behavior
- Link Service → Shared OTEL: instruments · Shares telemetry setup with the service runtime
- Redirect Service → Shared OTEL: instruments · Shares telemetry setup with the service runtime
- Stats Service → Shared OTEL: instruments · Shares telemetry setup with the service runtime
- Shared OTEL → OTel Collector: exports · Sends traces and metrics to the collector
- OTel Collector → Collector Config: configured by · Collector behavior is defined by the config file
- Load Test → Ingress: targets · Generates traffic through the public entrypoint
- Chaos Scripts → Link Service: stresses · Used to validate service resilience
- Chaos Scripts → Redirect Service: stresses · Used to validate redirect-path resilience