# sweetiu172/nbiot_detector_core architecture

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

- Interactive diagram: https://gitdiagram.com/sweetiu172/nbiot_detector_core
- Repository: https://github.com/sweetiu172/nbiot_detector_core

## Overview

##### Project type and purpose
- This is a cloud-native, microservices-style deployment of a Python inference service (“nbiot-detector”) that exposes a REST API for NB-IoT device detection.
- It includes CI/CD (Jenkins), GitOps (ArgoCD), observability (Prometheus/Grafana, Jaeger), logging (ELK), ingress (nginx + Cloudflare Tunnel), and runs on either Minikube (local) or GKE (production, provisioned via Terraform).

##### High-level components
a. Inference application
- Python FastAPI (app/main.py) in a Docker container
- Model assets loaded from app/saved_assets
- Exposes HTTP endpoints for single/batch prediction
- Docker image built by Jenkins
b. API ingress
- Ingress-NGINX controller (helm chart)
- Cloudflare Tunnel (optional for external access)
- Kubernetes Ingress resources
c. CI/CD and GitOps
- Jenkins (builds, pushes Docker images, triggers Helm / manifests deploy)
- ArgoCD (automatically syncs Helm charts and K8s manifests from Git)
d. Infrastructure provisioning
- Terraform (GKE cluster, networking, DNS, IAM)
- scripts/bootstrap.sh & cleanup.sh (orchestrate Terraform → kubectl → Helm)
e. Monitoring & observability
- kube-prometheus-stack (Prometheus, Alertmanager, Grafana dashboards)
- Jaeger all-in-one (distributed tracing)
f. Logging
- Elasticsearch (stores logs)
- Filebeat (ships logs into Elasticsearch)
- Kibana (log browsing & querying)

##### Interactions and data flows
- User/client HTTP → Cloudflare Tunnel → Ingress → nbiot-detector service → returns prediction
- nbiot-detector logs → stdout → Filebeat DaemonSet → Elasticsearch → Kibana UI
- nbiot-detector metrics (Prometheus client) scraped by Prometheus → Grafana dashboards
- Traces emitted by nbiot-detector → Jaeger collector → Jaeger UI
- Git push → Jenkins Multibranch Pipeline → builds/pushes Docker image → commits Helm values → triggers ArgoCD sync → Kubernetes Deployment rolling update

##### Architectural patterns and design principles
- Microservices (single-purpose inference service)
- GitOps for declarative deployments (ArgoCD, Helm charts under kubernetes/helm)
- IaC for infra (Terraform + bootstrap script)
- Sidecar-style logging and metrics collection via DaemonSets and Prometheus operators
- Namespace isolation (e.g., jenkins, monitoring, logging, argocd, app) in Kubernetes

##### Final checklist
- Critical configuration points: Terraform variables, Helm values, namespace names.
- Helm chart is represented (argocd, cert-manager, nginx-ingress, filebeat, elasticsearch, jaeger, prometheus-stack).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    User[/User\/Client/]:::external
    GH[/"GitHub Repo"/]:::external
    DockerHub[(Docker Hub)]:::external

    %% Cloud Infra (Orange)
    subgraph "Cloud Infra" 
        direction TB
        Bootstrap["scripts/bootstrap.sh"]:::infra
        Cleanup["scripts/cleanup.sh"]:::infra
        Terra["Terraform"]:::infra
    end

    %% CI/CD & GitOps (Green)
    subgraph "CI/CD & GitOps"
        direction TB
        Jenkins["Jenkins"]:::cicd
        ArgoCD["ArgoCD"]:::cicd
    end

    %% Kubernetes Cluster (GKE/Minikube)
    subgraph "Kubernetes Cluster"
        direction TB
        subgraph "Control Plane"
            direction TB
            IngressNGINX["Ingress-NGINX"]:::k8s
            CertManager["Cert-Manager"]:::k8s
            CFBase["cloudflare-ingress.yaml"]:::k8s
            GIBase["google-ingress.yaml"]:::k8s
            BaseIngress["ingress.yaml"]:::k8s
        end
        subgraph "Application Workloads"
            direction TB
            Service["nbiot-detector Service"]:::app
            Deployment["nbiot-detector Deployment\n(app/main.py)"]:::app
            Model["Model Assets\n(app/saved_assets/)"]:::app
        end
        subgraph "Observability"
            direction TB
            Prometheus[(Prometheus TSDB)]:::obs
            Grafana["Grafana"]:::obs
            Jaeger[(Jaeger All-in-One)]:::obs
        end
        subgraph "Logging"
            direction TB
            Filebeat["Filebeat DaemonSet"]:::log
            Elasticsearch[(Elasticsearch)]:::log
            Kibana["Kibana"]:::log
        end
    end

    %% Ingress External
    User -->|HTTP| Tunnel["Cloudflare Tunnel"]:::k8s
    Tunnel --> IngressNGINX

    %% Request Flow
    IngressNGINX --> Service
    Service -->|predict| Deployment
    Deployment -->|loads model| Model

    %% Logging Flow
    Service -->|stdout logs| Filebeat
    Filebeat --> Elasticsearch
    Elasticsearch --> Kibana

    %% Metrics & Tracing
    Deployment -->|metrics scrape| Prometheus
    Prometheus --> Grafana
    Deployment -->|traces| Jaeger
    Jaeger --> Grafana

    %% GitOps & CI/CD Flow
    GH -->|webhook| Jenkins
    Jenkins -->|build & push image| DockerHub
    Jenkins -->|commit Helm values| GH
    ArgoCD -->|sync Helm charts & manifests| Deployment
    ArgoCD --> IngressNGINX
    ArgoCD --> Prometheus
    ArgoCD --> Elasticsearch
    ArgoCD --> Jaeger

    %% Infra Provisioning Flow
    Bootstrap -->|runs| Terra
    Terra -->|provisions cluster| IngressNGINX

    %% Click Events
    click Deployment "https://github.com/sweetiu172/nbiot_detector_core/blob/main/app/main.py"
    click Deployment "https://github.com/sweetiu172/nbiot_detector_core/blob/main/app/model_definition.py"
    click Model "https://github.com/sweetiu172/nbiot_detector_core/tree/main/app/saved_assets/"
    click Service "https://github.com/sweetiu172/nbiot_detector_core/tree/main/kubernetes/helm/app-nbiot-detector/"
    click IngressNGINX "https://github.com/sweetiu172/nbiot_detector_core/tree/main/kubernetes/helm/ingress-nginx/"
    click Tunnel "https://github.com/sweetiu172/nbiot_detector_core/tree/main/kubernetes/helm/cloudflare-tunnel-remote/"
    click CFBase "https://github.com/sweetiu172/nbiot_detector_core/blob/main/kubernetes/base/cloudflare-ingress.yaml"
    click GIBase "https://github.com/sweetiu172/nbiot_detector_core/blob/main/kubernetes/base/google-ingress.yaml"
    click BaseIngress "https://github.com/sweetiu172/nbiot_detector_core/blob/main/kubernetes/base/ingress.yaml"
    click Bootstrap "https://github.com/sweetiu172/nbiot_detector_core/blob/main/scripts/bootstrap.sh"
    click Cleanup "https://github.com/sweetiu172/nbiot_detector_core/blob/main/scripts/cleanup.sh"
    click Terra "https://github.com/sweetiu172/nbiot_detector_core/blob/main/terraform/main.tf"
    click Jenkins "https://github.com/sweetiu172/nbiot_detector_core/tree/main/Jenkinsfile"
    click ArgoCD "https://github.com/sweetiu172/nbiot_detector_core/tree/main/kubernetes/helm/argo-cd/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,color:#000;
    classDef infra fill:#f96,stroke:#333,color:#000;
    classDef cicd fill:#9f6,stroke:#333,color:#000;
    classDef k8s fill:#ccf,stroke:#333,color:#000;
    classDef app fill:#6cf,stroke:#333,color:#000;
    classDef obs fill:#c9f,stroke:#333,color:#000;
    classDef log fill:#ccc,stroke:#333,color:#000;
```
