# shoplineapp/captin architecture

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

- Interactive diagram: https://gitdiagram.com/shoplineapp/captin
- Repository: https://github.com/shoplineapp/captin

## Overview

##### Project Type and Purpose
- This is a CLI tool (“captin”) written in Go for managing the delivery of webhooks in a distributed fashion.
- It reads a JSON configuration, ingests incoming events (HTTP, message queue, etc.), applies filters and throttles, and dispatches webhooks to arbitrary destinations (HTTP endpoint, SQS, Beanstalkd, console, etc.).

##### File Structure
Top-level packages:
- cmd (entrypoint “captin” CLI)
- core (core engine orchestration)
- interfaces (abstractions for dispatcher, store, document store, errors)
- destinations (user-configurable filters before sending)
- dispatcher (pipelines: delayers, error handlers, tracking)
- senders (concrete destination implementations: HTTP, SQS, console, Beanstalkd)
- internal (helpers, in-memory stores, custom outgoing dispatch logic, throttles)
- models (configuration mapping, incoming event definition, distributed tracing data)
- configs/examples/tests (demonstrate Redis store, filters, incoming HTTP hooks)

##### README for Additional Insights
- Usage is simply `captin ./example/config.json`.
- By convention, you supply a hook configuration and captin spins up listeners, pipelines, and sends outgoing webhooks.

##### Main Components & Their Relationships

[CLI Entrypoint]
- cmd/captin/main.go
- Reads JSON config via models/config_mapper.go

↓ loads configuration

[Core Engine]
- core/captin.go
- Orchestrates incoming adapters, dispatcher pipeline, and outgoing senders

↙                             ↘
[Incoming Adapters]          [Dispatcher Pipeline]         [Outgoing Senders]
- HTTP listener               • dispatcher/delayers/goroutine.go      • senders/http_sender.go
- (could be extended via internal/outgoing/custom.go)     • dispatcher/error_handlers      • senders/sqs_sender.go
- models/incoming_event.go     • dispatcher/filters                  • senders/beanstlakd_sender.go
- dispatcher/tracking.go               • senders/console_sender.go
- internal/throttles/throttler.go

↓ Events feed into
[Destination Filters]
- destinations/filters/*.go
- base rules (environment, source, validate, desired_hook)

↓ Filtered events feed into
[Document Store & Tracking]
- interfaces/document_store.go
- internal/document_stores (memstore, null_store)
- used for deduplication, retry tracking, throttling

↓ Persisted & enriched
[Dispatcher → Senders]
- dispatcher invokes appropriate sender(s)
- uses interfaces/store.go, interfaces/errors.go

##### Architectural Patterns & Principles
- Pipeline pattern – events flow through a configurable chain of delayers, filters, error handlers, trackers, then senders.
- Dependency inversion – core logic depends on interfaces; concrete implementations are pluggable.
- Modular, package-per-responsibility – clear separation between incoming, dispatching, filtering, persistence, and sending.
- Config-driven – behavior defined entirely by JSON hooks config (models/config.go, models/config_mapper.go).

##### Technologies, Frameworks & Libraries
- Go modules (go.mod)
- Standard Go net/http for HTTP ingress and egress
- Optional Redis (examples/redis/stores/redis_store.go)
- Message queues (SQS, Beanstalkd)
- JSON config parsing (encoding/json)
- Unit tests for every package

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entrypoint"]:::cli
        ConfigLoader["Config Loader (models/config_mapper.go)"]:::cli
    end

    %% Core Layer
    subgraph "Core Engine" 
        Core["Core Engine (core/captin.go)"]:::core
    end

    %% Incoming Adapters
    subgraph "Incoming Adapters"
        HTTPListener["HTTP Listener"]:::incoming
        EventDef["Incoming Event Definition"]:::incoming
    end

    %% Dispatch Pipeline
    subgraph "Dispatch Pipeline"
        Delayer["Delayers (dispatcher/delayers/goroutine.go)"]:::pipeline
        ErrorHandlers["Error Handlers (dispatcher/error_handlers)"]:::pipeline
        DispatcherFilters["Filters (dispatcher/filters)"]:::pipeline
        Tracking["Tracking (dispatcher/tracking.go)"]:::pipeline
        Throttler["Throttler (internal/throttles/throttler.go)"]:::pipeline
    end

    %% Destination Filters
    subgraph "Destination Filters"
        BaseFilter["base.go"]:::filters
        DesiredHook["desired_hook.go"]:::filters
        EnvFilter["environment.go"]:::filters
        SourceFilter["source.go"]:::filters
        ValidateFilter["validate.go"]:::filters
    end

    %% Persistence
    subgraph "Persistence"
        DocStoreIF["Document Store Interface\n(interfaces/document_store.go)"]:::persistence
        StoreIF["Store Interface (interfaces/store.go)"]:::persistence
        DispIF["Dispatcher Interface (interfaces/dispatcher.go)"]:::persistence
        MemStore["In‐Memory Store\n(internal/stores/memstore.go)"]:::persistence
        NullStore["Null Store\n(internal/document_stores/null_store.go)"]:::persistence
    end

    %% Outgoing Dispatch Logic
    subgraph "Outgoing Dispatch Logic"
        OutDisp["Dispatcher (internal/outgoing/dispatcher.go)"]:::dispatch
        CustomDisp["Custom Dispatcher (internal/outgoing/custom.go)"]:::dispatch
    end

    %% Senders
    subgraph "Senders"
        HTTPSender["HTTP Sender\n(senders/http_sender.go)"]:::senders
        HTTPProxy["HTTP Proxy Sender\n(senders/http_proxy_sender.go)"]:::senders
        SQSSender["SQS Sender\n(senders/sqs_sender.go)"]:::senders
        Beanstalkd["Beanstalkd Sender\n(senders/beanstlakd_sender.go)"]:::senders
        ConsoleSender["Console Sender\n(senders/console_sender.go)"]:::senders
    end

    %% Flow
    CLI -->|loads config| ConfigLoader
    ConfigLoader -->|initializes| Core
    Core -->|spins up| HTTPListener
    Core -->|orchestrates| Delayer
    HTTPListener -->|events| Delayer
    Delayer --> ErrorHandlers --> DispatcherFilters --> Tracking --> Throttler
    Throttler --> BaseFilter --> DesiredHook --> EnvFilter --> SourceFilter --> ValidateFilter
    ValidateFilter --> DocStoreIF --> StoreIF --> DispIF
    StoreIF --> MemStore
    StoreIF --> NullStore
    DispIF --> OutDisp --> CustomDisp
    CustomDisp --> HTTPSender
    CustomDisp --> HTTPProxy
    CustomDisp --> SQSSender
    CustomDisp --> Beanstalkd
    CustomDisp --> ConsoleSender

    %% Click Events
    click CLI "https://github.com/shoplineapp/captin/blob/master/cmd/captin/main.go"
    click ConfigLoader "https://github.com/shoplineapp/captin/blob/master/models/config_mapper.go"
    click Core "https://github.com/shoplineapp/captin/blob/master/core/captin.go"
    click EventDef "https://github.com/shoplineapp/captin/blob/master/models/incoming_event.go"
    click Delayer "https://github.com/shoplineapp/captin/blob/master/dispatcher/delayers/goroutine.go"
    click ErrorHandlers "https://github.com/shoplineapp/captin/tree/master/dispatcher/error_handlers"
    click DispatcherFilters "https://github.com/shoplineapp/captin/tree/master/dispatcher/filters"
    click Tracking "https://github.com/shoplineapp/captin/blob/master/dispatcher/tracking.go"
    click Throttler "https://github.com/shoplineapp/captin/blob/master/internal/throttles/throttler.go"
    click BaseFilter "https://github.com/shoplineapp/captin/blob/master/destinations/filters/base.go"
    click DesiredHook "https://github.com/shoplineapp/captin/blob/master/destinations/filters/desired_hook.go"
    click EnvFilter "https://github.com/shoplineapp/captin/blob/master/destinations/filters/environment.go"
    click SourceFilter "https://github.com/shoplineapp/captin/blob/master/destinations/filters/source.go"
    click ValidateFilter "https://github.com/shoplineapp/captin/blob/master/destinations/filters/validate.go"
    click DocStoreIF "https://github.com/shoplineapp/captin/blob/master/interfaces/document_store.go"
    click StoreIF "https://github.com/shoplineapp/captin/blob/master/interfaces/store.go"
    click DispIF "https://github.com/shoplineapp/captin/blob/master/interfaces/dispatcher.go"
    click MemStore "https://github.com/shoplineapp/captin/blob/master/internal/stores/memstore.go"
    click NullStore "https://github.com/shoplineapp/captin/blob/master/internal/document_stores/null_store.go"
    click OutDisp "https://github.com/shoplineapp/captin/blob/master/internal/outgoing/dispatcher.go"
    click CustomDisp "https://github.com/shoplineapp/captin/blob/master/internal/outgoing/custom.go"
    click HTTPSender "https://github.com/shoplineapp/captin/blob/master/senders/http_sender.go"
    click HTTPProxy "https://github.com/shoplineapp/captin/blob/master/senders/http_proxy_sender.go"
    click SQSSender "https://github.com/shoplineapp/captin/blob/master/senders/sqs_sender.go"
    click Beanstalkd "https://github.com/shoplineapp/captin/blob/master/senders/beanstlakd_sender.go"
    click ConsoleSender "https://github.com/shoplineapp/captin/blob/master/senders/console_sender.go"

    %% Styles
    classDef cli fill:#ffe4b2,stroke:#cc7a00;
    classDef core fill:#d0e1ff,stroke:#0059b3;
    classDef incoming fill:#d4ffd4,stroke:#009900;
    classDef pipeline fill:#ffd4f4,stroke:#b30059;
    classDef filters fill:#e6ccff,stroke:#5a00b3;
    classDef persistence fill:#fff0b3,stroke:#b38600;
    classDef dispatch fill:#b3f0ff,stroke:#008080;
    classDef senders fill:#ffcccc,stroke:#b30000;
```
