How swamisllc/go-orchestrator works
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)