# oscarlucas22/demo-pi architecture

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

- Interactive diagram: https://gitdiagram.com/oscarlucas22/demo-pi
- Repository: https://github.com/oscarlucas22/demo-pi

## Overview

##### Project Type and Purpose
- This is a Kubernetes–centric tutorial/documentation repo for installing and using Linkerd as a Service Mesh, plus observability components (Prometheus, Grafana) and a demo app (Emojivoto).
- The “imagenes” folder holds screenshots; there’s no application source code here.

##### Key Components
a. Kubernetes Cluster
- Namespaces:
– linkerd (control plane & extensions)
– emojivoto (demo app)
- kube-apiserver, etcd, kubelet, controller-manager (abstracted as “K8s control plane”).
b. Linkerd Service Mesh
- Control Plane (in linkerd ns):
– linkerd-controller (linkerd-web, identity, destination, proxy-injector, etc.)
– linkerd-viz extension (metrics-collector, dashboard)
- Data Plane (injected sidecar proxies next to each pod)
c. Demo Application (in emojivoto ns)
– web-svc → web pods (HTTP)
– vote-bot, vote-front, emoji-svc, results-svc (gRPC/HTTP flows)
d. Observability Stack
– Prometheus (scrapes metrics from Linkerd and app proxies)
– Grafana (visualizes Prometheus metrics)
e. User & CLI
– Developer’s local machine with linkerd CLI & kubectl
– Browser accessing dashboards and emojivoto UI

##### Relationships & Data Flows
- Developer runs `linkerd install` → CLI → applies Control Plane MANIFESTS to cluster.
- K8s Control Plane schedules Control Plane & extension pods.
- Developer injects Linkerd proxies into Emojivoto deployments → data-plane proxies wrap each app container.
- User HTTP/gRPC traffic to Emojivoto:
Browser → Kubernetes Ingress/Service → Linkerd inbound proxy → app container → outbound proxy → downstream pods.
- Linkerd proxies emit mTLS-encrypted traffic and telemetry.
- Prometheus scrapes `/metrics` endpoints on Linkerd control plane and sidecar proxies.
- Grafana queries Prometheus API for dashboards.
- CLI `linkerd check` commands validate both planes.

##### Architectural Patterns & Principles
- Sidecar Proxy Pattern: Linkerd injects a proxy container per pod (data plane).
- Control-Data Plane Separation: Control plane components are centralized; data-plane logic lives alongside app pods.
- Namespace Isolation: Separate namespaces for mesh control, observability, and applications.
- Git-Ops / Declarative Infrastructure: Use of `kubectl apply` on generated YAML manifests.

##### Final Recommendations
- Be as granular as possible: each namespace, each component, each network flow.
- Use consistent iconography (Kubernetes logo for cluster, Linkerd logo for mesh).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Dev["Developer<br/>linkerd CLI & kubectl"]:::actor
    Browser["User Browser"]:::actor

    %% Documentation Assets
    Doc["README.md"]:::doc
    Imagenes["imagenes/"]:::doc

    %% Cluster
    subgraph "Kubernetes Cluster"
      direction TB
      subgraph "linkerd namespace"
        direction TB
        subgraph "Control Plane Components"
          direction TB
          LC["linkerd-controller"]:::controlPlane
          ID["identity"]:::controlPlane
          DS["destination"]:::controlPlane
          PI["proxy-injector"]:::controlPlane
          LW["linkerd-web"]:::controlPlane
        end
        subgraph "linkerd-viz extension"
          direction TB
          MC["metrics-collector"]:::controlPlane
          DB["viz-dashboard"]:::controlPlane
        end
        PR["Prometheus"]:::observ
        GF["Grafana"]:::graf
      end
      subgraph "emojivoto namespace"
        direction TB
        WSVC["web-svc"]:::service
        WP["web-proxy"]:::dataPlane
        WAPP["web"]:::app
        VB_P["vote-bot-proxy"]:::dataPlane
        VB_APP["vote-bot"]:::app
        VF_P["vote-front-proxy"]:::dataPlane
        VF_APP["vote-front"]:::app
        ES_P["emoji-svc-proxy"]:::dataPlane
        ES_APP["emoji-svc"]:::app
        RS_P["results-svc-proxy"]:::dataPlane
        RS_APP["results-svc"]:::app
      end
    end

    %% Installation and Injection
    Dev -->|"linkerd install"| LC
    Dev -->|"linkerd inject deployments"| PI

    %% User Flows
    Browser -->|"HTTP/gRPC"| WSVC
    Browser -->|"view dashboards"| DB
    Browser -->|"view dashboards"| GF

    %% Service Mesh Data Plane Flows
    WSVC -->|"HTTP"| WP
    WP -->|"HTTP"| WAPP
    WAPP -->|"gRPC"| VF_P
    VF_P -->|"gRPC"| VF_APP
    VF_APP -->|"gRPC"| ES_P
    ES_P -->|"gRPC"| ES_APP
    ES_APP -->|"gRPC"| RS_P
    RS_P -->|"gRPC"| RS_APP

    %% Telemetry
    PR -->|"/metrics"| LC
    PR -->|"/metrics"| ID
    PR -->|"/metrics"| DS
    PR -->|"/metrics"| PI
    PR -->|"/metrics"| LW
    PR -->|"/metrics"| MC
    PR -->|"/metrics"| DB
    PR -->|"/metrics"| WP
    PR -->|"/metrics"| VB_P
    PR -->|"/metrics"| VF_P
    PR -->|"/metrics"| ES_P
    PR -->|"/metrics"| RS_P

    %% Observability Queries
    GF -->|"PromQL queries"| PR

    %% Click Events
    click Doc "https://github.com/oscarlucas22/demo-pi/blob/main/README.md"
    click Imagenes "https://github.com/oscarlucas22/demo-pi/tree/main/imagenes/"

    %% Styles
    classDef controlPlane fill:#cfe2f3,stroke:#0366d6;
    classDef dataPlane fill:#fce5cd,stroke:#e69138;
    classDef observ fill:#d9ead3,stroke:#6aa84f;
    classDef graf fill:#d9d2e9,stroke:#8e7cc3;
    classDef actor fill:#f0f0f0,stroke:#999;
    classDef service fill:#ffffff,stroke:#444;
    classDef app fill:#eeeeee,stroke:#666;
    classDef doc fill:#f8f9fa,stroke:#6c757d;
```
