# mitsu3s/cadence architecture

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

- Interactive diagram: https://gitdiagram.com/mitsu3s/cadence
- Repository: https://github.com/mitsu3s/cadence

## Overview

##### Project Type and Purpose
- From the file tree and minimal README (“cadence”), we see this is a standalone backend microservice written in Go (“api/” directory), designed to receive and process events (via a webhook), expose health checks, log activity, and persist data to Google Firestore.
- Terraform is used to provision GCP resources (Cloud Run service, Firestore, IAM roles, workload-identity).
- CI/CD workflows (in .github/workflows) build, test, deploy both Go code and Terraform.

##### Main Components
a. API Service
- Go application packaged into a Docker container (api/Dockerfile)
- Endpoints:
– /events (api/handler/events.go)
– /webhook (api/handler/webhook.go)
– /health (api/handler/health.go)
- Core modules: server setup (api/server), request handlers (api/handler), logging (api/logger), data models (api/model), and storage interface (api/store).
b. Data Store
- Google Firestore (api/store/firestore.go implements store.Store)
c. Infrastructure as Code
- Terraform modules under terraform/ (cloud_run.tf, firestore.tf, iam.tf, workload_identity.tf, etc.)
d. CI/CD Pipelines
- GitHub workflows:
– go.yaml (build & test Go code)
– terraform.yaml (plan & apply infra)
– cloud-run.yaml (build Docker image and deploy to Cloud Run)

##### Interactions and Data Flow
- External clients (event producers) → invoke the webhook endpoint on the Cloud Run URL.
- The Go server receives the HTTP request, logs it, optionally transforms it into an Event model, and writes it to Firestore.
- Health probes call the /health endpoint.
- The Terraform pipeline provisions and updates the Cloud Run service and Firestore database.
- CI pipelines trigger on push/PR, run tests, then deploy code or infra.

##### Architectural Patterns & Design Principles
- Microservice / 12-factor app: stateless container, externalized config (api/config/env.go reads environment variables).
- Clean separation of concerns: handlers vs. server vs. store vs. model vs. logger.
- Infrastructure immutability via Terraform.
- Strong interface-driven design for storage layer (store.Store).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    EP["Event Producer"]:::external

    %% Cloud Run Service Container
    subgraph "Cloud Run Service: cadence-api"
        direction TB
        Server["Server Bootstrap"]:::container
        Config["Config Loader"]:::container
        subgraph "HTTP Handler Layer"
            direction TB
            HE["/events Handler"]:::container
            HW["/webhook Handler"]:::container
            HH["/health Handler"]:::container
        end
        Logger["Logger Module"]:::container
        StoreIface["Store Interface"]:::container
        Model["Event Data Model"]:::container
    end

    %% Database
    FS["Firestore (NoSQL Database)"]:::db

    %% CI/CD Processes
    GHGo["GitHub Actions: Go CI"]:::ci
    GHTf["GitHub Actions: Terraform"]:::ci
    DR["Docker Registry"]:::registry

    %% Infrastructure Provisioning
    %% Using dashed lines for IaC flows
    GCP["GCP Resources\n(Cloud Run & Firestore)"]:::infra

    %% Runtime Flow
    EP -->|HTTP POST /events| HE
    EP -->|HTTP POST /webhook| HW
    EP -->|GET /health| HH
    HE -->|log request| Logger
    HW -->|log request| Logger
    HH -->|health probe| Logger
    Logger -->|invoke store| StoreIface
    StoreIface -->|writes Event| FS

    %% CI/CD Flow
    GHGo -->|build & test| DR
    DR -->|docker push| Server
    GHTf -.->|terraform apply| GCP
    GCP -.->|provision| FS

    %% Internal Dependencies
    Server --> Config
    Server --> HE
    Server --> HW
    Server --> HH
    Config --> HE
    Config --> HW
    Config --> HH
    StoreIface --> Model

    %% Click Events
    click Server "https://github.com/mitsu3s/cadence/blob/main/api/main.go"
    click Server "https://github.com/mitsu3s/cadence/blob/main/api/server/server.go"
    click Config "https://github.com/mitsu3s/cadence/blob/main/api/config/env.go"
    click HE "https://github.com/mitsu3s/cadence/blob/main/api/handler/events.go"
    click HW "https://github.com/mitsu3s/cadence/blob/main/api/handler/webhook.go"
    click HH "https://github.com/mitsu3s/cadence/blob/main/api/handler/health.go"
    click Logger "https://github.com/mitsu3s/cadence/blob/main/api/logger/logger.go"
    click Model "https://github.com/mitsu3s/cadence/blob/main/api/model/event.go"
    click StoreIface "https://github.com/mitsu3s/cadence/blob/main/api/store/store.go"
    click FS "https://github.com/mitsu3s/cadence/blob/main/api/store/firestore.go"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/cloud_run.tf"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/firestore.tf"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/iam.tf"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/workload_identity.tf"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/main.tf"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/terraform/variables.tf"
    click GHGo "https://github.com/mitsu3s/cadence/blob/main/.github/workflows/go.yaml"
    click GHTf "https://github.com/mitsu3s/cadence/blob/main/.github/workflows/terraform.yaml"
    click DR "https://github.com/mitsu3s/cadence/blob/main/.github/workflows/cloud-run.yaml"

    %% Styling
    classDef external fill:#b3ffb3,stroke:#2d662d;
    classDef container fill:#cce5ff,stroke:#335c80;
    classDef db fill:#ffe0b3,stroke:#b36b00;
    classDef ci fill:#e6e6e6,stroke:#999999;
    classDef registry fill:#f2e6ff,stroke:#804d99;
    classDef infra fill:#e0f7ff,stroke:#3399cc;
```
