# jakub-k-slys/n8n-operator architecture

> Architecture diagram of the GitHub repository jakub-k-slys/n8n-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakub-k-slys/n8n-operator
- Repository: https://github.com/jakub-k-slys/n8n-operator

## Overview

##### Project type and purpose
- This is a Kubernetes operator—specifically, the “n8n-operator”—written in Go using Kubebuilder/controller-runtime.
- Its purpose is to watch custom N8n CRs (Custom Resources), and on each reconciliation, automatically create/manage the underlying Kubernetes resources (Deployments, Services, Ingress or Gateway‐API HTTPRoutes, PVCs) and configure external PostgreSQL connections for n8n workflow instances.

##### File structure
- Top-level directories:
- api/v1alpha1: Go types for the N8n CRD (groupVersionInfo, type definitions, deepcopy).
- cmd/main.go: the operator’s entrypoint, sets up manager and controllers.
- internal/controller: the Reconciler logic (n8n_controller.go), tests.
- config/: Kustomize manifests for CRDs, RBAC, manager Deployment, network policies, Prometheus monitors, sample CRs, scorecard tests.
- bundle/: an OLM (Operator Lifecycle Manager) bundle (CSV, RBAC, CRDs) for packaging and distribution.
- hack/, test/: helper scripts and E2E/unit tests.
- Build & deployment configuration:
- Dockerfile & bundle.Dockerfile for images; Makefile targets for build/push, install/deploy/uninstall, scorecard; .golangci.yml for linting.

##### README for additional insights
- Describes two traffic-routing options (Ingress vs. Gateway API HTTPRoute).
- Explains PostgreSQL parameters, persistent storage, TLS, and secure non-root execution.
- Provides sample CR YAMLs, deployment steps (make docker-build/push, make install/deploy).

##### Elements
- Clear labels: e.g., “N8n CRD,” “Operator Manager,” “Reconciler,” “n8n Deployment,” “Ingress,” “HTTPRoute,” “PVC,” “PostgreSQL.”
- Cluster built-in components (e.g., grey)
- CRD & custom resources (e.g., green)
- External services (e.g., orange)

##### Detail and essential architectural elements
- Break out the Manager into subparts: metrics server, leader election, controller registration.
- RBAC roles/bindings granting the Operator permissions.
- Call out Kustomize overlays for CRDs vs. manager deployment vs. defaults.
- OLM CSV metadata and bundle/metadata folder as the packaging layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Kubernetes Cluster Components
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["API Server & etcd"]:::cluster
        CRD["N8n CRD (CustomResourceDefinition)"]:::crd
        Operator["Operator Manager Deployment"]:::operator
        Reconciler["Reconciler Logic"]:::operator

        subgraph "n8n Instance Resources"
            direction TB
            Deployment["n8n Deployment & Pod(s)"]:::app
            Service["Service"]:::app
            PVC["PersistentVolumeClaim"]:::app
            Secrets["Secrets (TLS, DB creds)"]:::app
            Ingress["Ingress"]:::network
            HTTPRoute["HTTPRoute"]:::network
        end

        APIServer -->|watch/get/update| Operator
        Operator --> Reconciler
        Reconciler -->|create/update| Deployment
        Reconciler -->|create/update| Service
        Reconciler -->|create/update| PVC
        Reconciler -->|create/update| Secrets
        Reconciler -->|create/update| Ingress
        Reconciler -->|create/update| HTTPRoute
    end

    %% External Traffic and Services
    Internet["User/Internet"]:::external
    Internet -->|HTTP request| Ingress
    Internet -->|HTTP request| HTTPRoute

    Postgres[(External PostgreSQL Database)]:::external
    Deployment -->|connect| Postgres

    %% Metrics
    MetricsService["Metrics Service"]:::cluster
    Prometheus[(Prometheus)]:::external
    Operator --> MetricsService
    Prometheus -->|scrape metrics| MetricsService

    %% OLM Bundle & Scorecard
    subgraph "OLM Bundle & Scorecard"
        direction TB
        BundleManifests["OLM Bundle Manifests"]:::config
        BundleMetadata["OLM Bundle Metadata"]:::config
        Scorecard["Scorecard Tests Configuration"]:::config
    end

    %% Tests
    subgraph "Tests"
        direction TB
        ControllerTests["Controller Unit Tests"]:::tests
        SuiteTest["Controller Suite Tests"]:::tests
        E2ESuite["E2E Suite Tests"]:::tests
        E2ETest["E2E Tests"]:::tests
        Utils["Helper Test Utilities"]:::tests
    end

    %% Click Events
    click CRD "https://github.com/jakub-k-slys/n8n-operator/tree/main/api/v1alpha1/"
    click Operator "https://github.com/jakub-k-slys/n8n-operator/blob/main/cmd/main.go"
    click Reconciler "https://github.com/jakub-k-slys/n8n-operator/blob/main/internal/controller/n8n_controller.go"
    click ControllerTests "https://github.com/jakub-k-slys/n8n-operator/blob/main/internal/controller/n8n_controller_test.go"
    click SuiteTest "https://github.com/jakub-k-slys/n8n-operator/blob/main/internal/controller/suite_test.go"
    click E2ESuite "https://github.com/jakub-k-slys/n8n-operator/blob/main/test/e2e/e2e_suite_test.go"
    click E2ETest "https://github.com/jakub-k-slys/n8n-operator/blob/main/test/e2e/e2e_test.go"
    click Utils "https://github.com/jakub-k-slys/n8n-operator/blob/main/test/utils/utils.go"
    click BundleManifests "https://github.com/jakub-k-slys/n8n-operator/tree/main/bundle/manifests/"
    click BundleMetadata "https://github.com/jakub-k-slys/n8n-operator/tree/main/bundle/metadata/"
    click Scorecard "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/scorecard/"
    click CRDManifests "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/crd/"
    click DefaultOverlay "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/default/"
    click RBAC "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/rbac/"
    click NetworkPolicy "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/network-policy/"
    click PrometheusConfig "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/prometheus/"
    click SampleCR "https://github.com/jakub-k-slys/n8n-operator/tree/main/config/samples/"
    click Dockerfile "https://github.com/jakub-k-slys/n8n-operator/tree/main/Dockerfile"
    click BundleDockerfile "https://github.com/jakub-k-slys/n8n-operator/blob/main/bundle.Dockerfile"
    click Makefile "https://github.com/jakub-k-slys/n8n-operator/tree/main/Makefile"
    click Golangci "https://github.com/jakub-k-slys/n8n-operator/blob/main/.golangci.yml"

    %% Styles
    classDef cluster fill:#cccccc,stroke:#333,stroke-width:1px
    classDef operator fill:#bbeeff,stroke:#333,stroke-width:1px
    classDef crd fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef app fill:#e0e0ff,stroke:#333,stroke-width:1px
    classDef network fill:#ffebcc,stroke:#333,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef config fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef tests fill:#ffe6e6,stroke:#333,stroke-width:1px
```
