# cybozu-go/fin architecture

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

- Interactive diagram: https://gitdiagram.com/cybozu-go/fin
- Repository: https://github.com/cybozu-go/fin

## Overview

##### Project type and purpose
- This is a Kubernetes “operator” written in Go (using Kubebuilder). It defines Custom Resources (FinBackup, FinRestore, FinBackupConfig), watches them, and spins up Jobs to do backups, restores, clean-up, deletion, and verification. It also provides a validating/mutating webhook for CR admission.

##### File structure
- Top-level “api/v1” holds the CRD Go types and generated deepcopy code.
- “cmd” contains the CLI entry points for the operator binary (main.go + subcommands).
- “internal/controller” implements the reconcile loops for each CR type.
- “internal/job” is the library for constructing Kubernetes Job specs for backup/restore/etc.
- “internal/infrastructure” contains adapters to external storage (Ceph RBD, NLV, DB) and fake implementations for testing.
- “internal/webhook” hosts the admission logic.
- “config” holds Kustomize overlays: CRD manifests, RBAC, manager deployment, webhook Service, Prometheus monitors, network policies.
- “test/e2e” and “test/utils” support end-to-end testing with real or simulated KVM/ceph clusters.

##### Additional insights
- CRDs → RBAC → Manager Deployment (with leader election, metrics) → Webhook Service → Prometheus monitors.
- Controllers reconcile loops that react to CR changes and update status.

- “API Server + etcd”
- “Job Pod” for each job type
- “Ceph RBD Cluster” and “NLV Service”
- “etcd (CRD storage)”
- CR creation → API Server → controllers
- Controller → Job creation
- Job Pod → external storage
- Job Pod → status update → API Server → Controller
- Data Plane components (Job Pods, Ceph) in another
- Test/E2E harness in a third

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlanes implied by vertical order

    %% User Interaction
    User["User / kubectl"]:::user
    User -->|create/update CR| API["API Server + etcd"]:::cp

    %% CRD Definitions
    CRDTypes["CustomResource Definitions"]:::cp
    click CRDTypes "https://github.com/cybozu-go/fin/tree/main/api/v1/"
    API -->|CRD plug-in| CRDTypes

    %% Operator Manager Pod
    subgraph "Operator Manager Pod"
        direction TB
        Manager["controller-runtime Manager"]:::operator
        subgraph "Controllers"
            direction TB
            BackupCtrl["FinBackupController"]:::operator
            RestoreCtrl["FinRestoreController"]:::operator
            ConfigCtrl["FinBackupConfigController"]:::operator
        end
        Webhook["Admission Webhook Server"]:::operator
    end

    %% CLI Entry Points
    CLI["CLI Entry Points"]:::operator
    click CLI "https://github.com/cybozu-go/fin/blob/main/cmd/root.go"
    Manager --> CLI

    %% Operator Watch & Reconcile
    API -->|watch CRs| BackupCtrl
    API -->|watch CRs| RestoreCtrl
    API -->|watch CRs| ConfigCtrl
    API -->|intercept requests| Webhook

    %% Job Spec Library
    JobLib["Job Specification Library"]:::operator
    click JobLib "https://github.com/cybozu-go/fin/tree/main/internal/job/"
    BackupCtrl -->|generate Job| JobLib
    RestoreCtrl -->|generate Job| JobLib
    ConfigCtrl -->|generate Job| JobLib

    %% Kubernetes Job Pods (Data Plane)
    JobPod["Kubernetes Job Pod"]:::dataplane
    JobLib -->|submit Job| JobPod
    JobPod -->|update status| API

    %% Infrastructure Adapters
    subgraph "External Storage / DB"
        direction TB
        Ceph["Ceph RBD Adapter"]:::infra
        click Ceph "https://github.com/cybozu-go/fin/blob/main/internal/infrastructure/ceph/command.go"
        NLV["NLV Adapter"]:::infra
        click NLV "https://github.com/cybozu-go/fin/blob/main/internal/infrastructure/nlv/nlv.go"
        DB["DB Backend Adapter"]:::infra
        click DB "https://github.com/cybozu-go/fin/blob/main/internal/infrastructure/db/fin.go"
    end

    JobPod -->|snapshot/push/pull| Ceph
    JobPod -->|snapshot/push/pull| NLV
    JobPod -->|record diffs| DB

    %% Webhook Flow
    User -->|create/update CR| Webhook --> API

    %% Kustomize Manifests
    Kustom["Kustomize Manifests & Overlays"]:::infra
    click Kustom "https://github.com/cybozu-go/fin/tree/main/config/crd/bases/"
    Kustom --> API
    Kustom --> Manager
    Kustom --> Webhook

    %% Test Harness
    Test["End-to-End Test Harness"]:::testing
    click Test "https://github.com/cybozu-go/fin/blob/main/test/e2e/e2e_suite_test.go"
    Test -->|simulate cluster| API
    Test --> Manager
    Test --> JobPod

    %% Styles
    classDef cp fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef operator fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef dataplane fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef testing fill:#ffccbc,stroke:#333,stroke-width:1px
    classDef user fill:#f5f5f5,stroke:#333,stroke-width:1px
```
