# swamisllc/go-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/swamisllc/go-orchestrator
- Repository: https://github.com/swamisllc/go-orchestrator

## Overview

##### Project Type & Purpose
- This is a backend “payment orchestration” service (no UI layer), implemented in Go, exposing a gRPC/HTTP API to accept merchant payment requests, validating & normalizing them, orchestrating multi-step payment flows, integrating with external payment providers (e.g. Stripe), and emitting observability data & retrospective reports.

##### File Structure
- Cmd/server
– Entry point: initializes server, loads configs, exposes `/process-payment` endpoint
- Protobufs & pkg/gen
– Protobuf IDLs (protos/) → Buf → Go stubs in pkg/gen → used across modules
- internal/
– adapter/: provider‐specific adapters (Stripe, mock)
– context/: builds execution context & domain objects, traces each step
– router/: circuit-breaker & routing logic deciding which adapter(s) to invoke
– orchestrator/: high-level orchestration engine, sequences steps per plan
– planbuilder/: constructs dynamic payment plans (composite of processing steps)
– processor/: executes individual steps in a plan
– policy/: policy-driven rules (e.g. retry policies, fallback logic)
– monitor/: collects metrics, schemas, contract violations
– reporting/: generates retrospective reports
- schemas/
– JSON Schema for external requests—enforces input discipline
- CI & Build
– .github/workflows/ci.yml, Makefile for `make gen`, `make test`, `go build`

##### README & Spec
- Domain-Driven Design (DDD) with strict external→internal model transformation
- Built-in observability: metrics, traces, contract monitoring, retrospective reports
- Modularity: adapters pluggable, routing & fallback configurable per merchant

1. Client (Merchant Apps / HTTP or gRPC callers)
2. API Gateway / Server (cmd/server)
3. Validation & Normalization Layer (schemas + context builder)
4. Orchestration Engine (orchestrator module)
5. Routing & Policy (router + policy modules)
6. Plan Builder (planbuilder module)
7. Step Processor (processor module)
8. Adapter Layer (stripe, mock, future providers)
9. Observability & Monitoring (monitor module)
10. Reporting & Retrospectives (reporting module)
b. Relationships & Data Flow:
- Server → Validation Layer → (if invalid: log, continue) → Orchestrator
- Orchestrator → Router/Policy → PlanBuilder → Processor → Adapter(s) → External Payment Provider(s)
- Throughout, emit metrics/traces to Monitor; errors or contract violations feed back to Monitor
- Reporting pulls data from Monitor or log store every X days to generate reports
c. Architectural Patterns & Principles:
- Layers & Separation of Concerns: API → validation → orchestration → execution → adapters
- Pluggable Adapters: Dependency inversion, each provider behind a uniform interface
- Circuit Breaker & Fallback (router/circuitbreaker)
- Policy-driven behavior (retry, fallback, thresholds)
- DDD: mapping external protobuf model → domain model → back to protobuf for responses
d. Key Technologies & Frameworks:
- Go (1.19+)
- Buf & Protobuf → gRPC stubs
- golangci-lint for static analysis
- Makefile for automation
- CI/CD (GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External client
    Client(("Merchant Client")):::external

    %% Protobuf Definitions
    subgraph "Protobuf Definitions"
        ProtoIDL["IDL Files (protos/)"]:::proto
        ProtobufStubs["Generated Stubs (pkg/gen/)"]:::proto
    end

    %% API / Ingress Layer
    subgraph "API / Ingress" 
        API["API Gateway / Server"]:::ingress
    end

    %% Validation & Normalization Layer
    subgraph "Validation & Normalization"
        Schema["JSON Schema Validation"]:::validation
        ContextBuilder["Context Builder"]:::validation
        ContextDomain["Domain Mapping"]:::validation
        ContextStep["Step Context"]:::validation
        ContextTrace["Trace Context"]:::validation
    end

    %% Core Orchestration Layer
    subgraph "Core Orchestration"
        Orchestrator["Orchestration Engine"]:::orchestration
        Router["Routing Logic"]:::orchestration
        CircuitBreaker["Circuit Breaker"]:::orchestration
        Policy["Policy Engine"]:::orchestration
        PlanBuilder["Plan Builder"]:::orchestration
        Composite["Plan Composite"]:::orchestration
        Processor["Step Processor"]:::orchestration
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        AdapterInterface["Adapter Interface"]:::adapter
        StripeAdapter["Stripe Adapter"]:::adapter
        MockAdapter["Mock Adapter"]:::adapter
        ExternalProviders(("External Payment Providers")):::external
    end

    %% Observability & Reporting
    subgraph "Observability & Reporting"
        Monitor["Observability & Monitoring"]:::observability
        Reporting["Reporting & Retrospectives"]:::observability
    end

    %% CI & Build
    subgraph "CI & Build"
        CI["GitHub Actions CI"]:::ci
        Make["Makefile Automation"]:::ci
    end

    %% Data Flows
    Client -->|"gRPC/HTTP Request"| API
    API -->|"ExternalRequest.proto"| Schema
    Schema --> ContextBuilder
    ContextBuilder --> ContextDomain
    ContextDomain --> ContextStep
    ContextStep --> ContextTrace
    ContextTrace --> Orchestrator

    Orchestrator --> Router
    Router --> CircuitBreaker
    CircuitBreaker --> Policy
    Policy --> PlanBuilder
    PlanBuilder --> Composite
    Composite --> Processor
    Processor --> AdapterInterface

    AdapterInterface --> StripeAdapter
    AdapterInterface --> MockAdapter
    StripeAdapter --> ExternalProviders
    MockAdapter --> ExternalProviders

    %% Observability streams
    API -.->|metrics/traces| Monitor
    Schema -.->|validation logs| Monitor
    Orchestrator -.->|orchestration metrics| Monitor
    Router -.->|circuit events| Monitor
    Processor -.->|processing metrics| Monitor
    AdapterInterface -.->|adapter metrics| Monitor
    Monitor --> Reporting

    %% Protobuf links
    ProtoIDL --> API
    ProtobufStubs --> API
    ProtobufStubs --> ContextBuilder

    %% CI links
    CI --> API
    CI --> ProtobufStubs
    Make --> CI

    %% Click Events
    click API "https://github.com/swamisllc/go-orchestrator/blob/main/cmd/server/main.go"
    click ProtoIDL "https://github.com/swamisllc/go-orchestrator/tree/main/protos/"
    click ProtobufStubs "https://github.com/swamisllc/go-orchestrator/tree/main/pkg/gen/"
    click Schema "https://github.com/swamisllc/go-orchestrator/blob/main/schemas/external_request_schema.json"
    click ContextBuilder "https://github.com/swamisllc/go-orchestrator/blob/main/internal/context/builder.go"
    click ContextDomain "https://github.com/swamisllc/go-orchestrator/blob/main/internal/context/domain.go"
    click ContextStep "https://github.com/swamisllc/go-orchestrator/blob/main/internal/context/step.go"
    click ContextTrace "https://github.com/swamisllc/go-orchestrator/blob/main/internal/context/trace.go"
    click Orchestrator "https://github.com/swamisllc/go-orchestrator/blob/main/internal/orchestrator/orchestrator.go"
    click Router "https://github.com/swamisllc/go-orchestrator/blob/main/internal/router/router.go"
    click CircuitBreaker "https://github.com/swamisllc/go-orchestrator/blob/main/internal/router/circuitbreaker/circuitbreaker.go"
    click Policy "https://github.com/swamisllc/go-orchestrator/blob/main/internal/policy/policy.go"
    click PlanBuilder "https://github.com/swamisllc/go-orchestrator/blob/main/internal/planbuilder/planbuilder.go"
    click Composite "https://github.com/swamisllc/go-orchestrator/blob/main/internal/planbuilder/composite.go"
    click Processor "https://github.com/swamisllc/go-orchestrator/blob/main/internal/processor/processor.go"
    click AdapterInterface "https://github.com/swamisllc/go-orchestrator/blob/main/internal/adapter/adapter.go"
    click StripeAdapter "https://github.com/swamisllc/go-orchestrator/blob/main/internal/adapter/stripe/stripe_adapter.go"
    click MockAdapter "https://github.com/swamisllc/go-orchestrator/blob/main/internal/adapter/mock/mock_adapter.go"
    click Monitor "https://github.com/swamisllc/go-orchestrator/blob/main/internal/monitor/monitor.go"
    click Reporting "https://github.com/swamisllc/go-orchestrator/blob/main/internal/reporting/retrospective.go"
    click CI "https://github.com/swamisllc/go-orchestrator/blob/main/.github/workflows/ci.yml"
    click Make "https://github.com/swamisllc/go-orchestrator/tree/main/Makefile"

    %% Styles
    classDef external fill:#eef,stroke:#333,stroke-width:1px
    classDef proto fill:#ddd,stroke:#333,stroke-width:1px
    classDef ingress fill:#aaf,stroke:#333,stroke-width:1px
    classDef validation fill:#bbf,stroke:#333,stroke-width:1px
    classDef orchestration fill:#afa,stroke:#333,stroke-width:1px
    classDef adapter fill:#f96,stroke:#333,stroke-width:1px
    classDef observability fill:#c9c,stroke:#333,stroke-width:1px
    classDef ci fill:#ffc,stroke:#333,stroke-width:1px
```
