# openutm/deployment architecture

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

- Interactive diagram: https://gitdiagram.com/openutm/deployment
- Repository: https://github.com/openutm/deployment

## Overview

##### Project Type and Purpose
- This repository is not a traditional application codebase but a deployment configuration repository.
- Its purpose is to deploy and manage multiple microservices (named “blender”, “passport”, and “spotlight”) in a Kubernetes cluster on the cloud.
- It includes environment configuration files, kustomize-based YAMLs for Kubernetes resources, helm-based instructions for ingress and cert-manager, and template files for generating TLS issuing components.
- Elements like generating OIDC keys, domain/DNS configurations, ingress, and certificate management which indicate a cloud-focused and secure deployment architecture.

##### File Structure
- Top-level files (.gitignore, LICENSE, README.md, etc.) indicate this is a public, configuration-driven deployment tool.
- The env.examples folder contains example environment files for different microservices.
- The kustomize directory is subdivided into three directories (“blender”, “passport”, “spotlight”), each containing configuration files like deployments, services, persistent volume claims, and additional configurations (e.g., redis, tile38 for spotlight).
- The templates folder contains YAML templates for certificates, issuers, and ingress objects, while the generate-from-templates.sh script indicates there's automated processing to customize these files.
- Presence of documents like constructing_environment_files.md and env_file_documentation.md advise on how to build reliable environment setups, which are critical to system deployment.

##### README for Additional Insights
- The README walks through prerequisites, including setup of DigitalOcean’s Kubernetes cluster, ingress-nginx, and cert-manager.
- It instructs on domain and DNS record creation, load balancer usage, and further customization of environment files.
- Steps include running kustomize updates, generating an OIDC key, applying Kubernetes manifests, and eventually launching the services at sub-domains.
- These points reveal clear external dependencies and corresponding interactions among cloud components (DNS records, load balancers, API tokens) and internal components (service deployments, database storage, caching).

a. Main Components:
- Cloud Provider Infrastructure: DigitalOcean (domain name service, load balancer, Kubernetes Cluster).
- Ingress Controller: Deployed using ingress-nginx (handles public traffic routing).
- Certificate Management: cert-manager along with an Issuer and Certificate objects (from the templates and helm instructions).
- Microservices: Three core services:
– Passport (authentication/identity service)
– Blender (possibly content/service processing)
– Spotlight (likely serving geospatial or specialized functions, also integrating services such as Tile38 for location-based features)
- Supporting Databases and Caches: Each service has its own dedicated database (YAML files like db-blender.yaml, db-passport.yaml) and caching mechanisms (redis setups), with additional component tile38 for spotlight.
- Template Processing: The generate-from-templates.sh script which converts template YAMLs (for ingress, issuer, certificate management) into service-specific files.

b. Relationships and Interactions:
- External traffic enters through the DigitalOcean load balancer, which is then directed to the ingress-nginx controller in Kubernetes.
- The ingress controller uses routing rules (possibly based on subdomains such as blender.example.com, passport.example.com, spotlight.example.com) to forward requests to the respective services.
- Certificate management (cert-manager with its Issuer/CERT objects) adds secure, automatic TLS termination by interacting with DNS and the ingress.
- Services (blender, passport, spotlight) interact with their own databases and caches. Additionally, configuration data is managed via environment variables (from the env files) and dynamically applied using kustomize.
- The generate-from-templates.sh transforms generic templates into tailored resource definitions, aligning service endpoints, domains, and certificate parameters.

c. Architectural Patterns & Design Principles:
- Declarative Infrastructure: Kubernetes manifests managed via kustomize for environment-specific overlays.
- Separation of Concerns: Dividing the system into distinct microservices (authentication, processing, geospatial/search) each with dedicated backend resources.
- Infrastructure as Code: Use of YAML templates, helm charts (for ingress-nginx and cert-manager), and git for version control.
- Secure and Automated Deployment: Automated DNS record creation, TLS certificate issuance, and OIDC key generation.
- Extensibility via Templates: Template directory and generate-from-templates.sh enable dynamic generation and customization of deployment files.

d. Relevant Technologies and Frameworks:
- Kubernetes (and kubectl for deployment)
- kustomize for configuration management
- Helm for deploying ingress-nginx and cert-manager
- DigitalOcean (cloud provider, load balancing, DNS)
- OpenSSL for OIDC key generation
- Templating for ingress and certificate resources

##### Final Advice
- Be sure to capture both static infrastructure (e.g., DNS records, load balancer, ingress) and dynamic/declarative aspects (Kubernetes deployments, kustomize overlays, templated resources).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DigitalOcean Cloud Layer
    subgraph "DigitalOcean Cloud"
        dns["DigitalOcean DNS"]:::cloud
        lb["DigitalOcean Load Balancer"]:::cloud
    end

    %% Deployment Configuration Layer
    subgraph "Deployment Configurations"
        ks["Kustomize Declarative Infra (kustomize)"]:::infra
        env["Environment Configs (env.examples)"]:::config
        tpl["Template Processing"]:::template
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        %% Ingress and Certificate Management
        subgraph "Ingress Layer"
            ing["Ingress Controller (ingress-nginx)"]:::k8s
        end
        subgraph "Certificate Management"
            cert["cert-manager & Issuer/CERT"]:::k8s
        end
        %% Microservices
        subgraph "Microservices"
            p["Passport Service"]:::micro
            b["Blender Service"]:::micro
            s["Spotlight Service"]:::micro
        end
        %% Supporting Databases and Caches
        subgraph "Supporting Services"
            dbp["DB for Passport"]:::database
            dbb["DB for Blender"]:::database
            dbs["DB for Spotlight"]:::database
            redisb["Redis for Blender"]:::cache
            rediss["Redis for Spotlight"]:::cache
            tile38["Tile38 for Spotlight"]:::cache
        end
    end

    %% Documentation
    subgraph "Documentation"
        readme["README.md"]:::doc
        constructing["constructing_environment_files.md"]:::doc
        envdoc["env_file_documentation.md"]:::doc
    end

    %% Connections: Cloud to Cluster
    dns --> lb
    lb -->|"routes traffic"| ing
    ing -->|"secure_traffic"| p
    ing -->|"secure_traffic"| b
    ing -->|"secure_traffic"| s
    ing -->|"integrates_with"| cert

    %% Connections: Deployment Configuration to Kubernetes Cluster
    ks -->|"deploys"| ing
    ks -->|"deploys"| p
    ks -->|"deploys"| b
    ks -->|"deploys"| s
    tpl -->|"generates_config_for"| ks
    env -->|"provides_settings_to"| ks

    %% Microservices to Supporting Services
    p --> dbp
    b --> dbb
    s --> dbs
    b --> redisb
    s --> rediss
    s --> tile38

    %% Documentation links to Deployment Configuration
    readme --> ks
    constructing --> ks
    envdoc --> env

    %% Style definitions
    classDef cloud fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef infra fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef template fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef k8s fill:#D2B4DE,stroke:#78281F,stroke-width:2px;
    classDef micro fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef database fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef cache fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef doc fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;

    %% Click Events (paths are for internal use only)
    click b "https://github.com/openutm/deployment/tree/main/kustomize/blender"
    click p "https://github.com/openutm/deployment/tree/main/kustomize/passport"
    click s "https://github.com/openutm/deployment/tree/main/kustomize/spotlight"
    click env "https://github.com/openutm/deployment/blob/main/env.examples"
    click tpl "https://github.com/openutm/deployment/blob/main/generate-from-templates.sh"
    click ks "https://github.com/openutm/deployment/tree/main/kustomize"
    click readme "https://github.com/openutm/deployment/blob/main/README.md"
    click constructing "https://github.com/openutm/deployment/blob/main/constructing_environment_files.md"
    click envdoc "https://github.com/openutm/deployment/blob/main/env_file_documentation.md"
```
