# manojcloud/tidewater-link2build architecture

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

- Interactive diagram: https://gitdiagram.com/manojcloud/tidewater-link2build
- Repository: https://github.com/manojcloud/tidewater-link2build

## Overview

Settle is a daily merchant settlement service: an API accepts settlement requests, queues jobs, and a worker calculates amounts and sends idempotent payouts to a bank. PostgreSQL stores settlement and payout state; Redis backs the job queue. The repository also documents health checks, reports, metrics, migrations, and operational dashboards and alerts. The graph emphasizes runtime behavior and those product capabilities; observability wiring is documented at the subsystem level, while unsampled deployment details are not expanded.

Main entry points: [`app/settle/worker.py`](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/worker.py) (Settlement worker), [`app/settle/api.py`](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/api.py) (Settlement API), [`app/settle/metrics.py`](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/metrics.py) (Service metrics), [`app/settle/logging_setup.py`](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/logging_setup.py) (Structured logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and reporting"]
  node_api_service["Settlement API<br/>[api.py]"]
  node_daily_report["Daily reports<br/>[api.py]"]
end

subgraph group_settlement["Settlement processing"]
  node_worker["Settlement worker<br/>[worker.py]"]
  node_bank["Bank service"]
  node_mockbank["Mock bank<br/>[mockbank.py]"]
end

subgraph group_state["State and dependencies"]
  node_postgres[("PostgreSQL")]
  node_redis["Redis queue"]
  node_migration_runner["Migration runner<br/>[migrate.py]"]
end

subgraph group_operations["Operations and observability"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_logging["Structured logging<br/>[logging_setup.py]"]
  node_metrics["Service metrics<br/>[metrics.py]"]
  node_observability["Dashboards and alerts"]
end

node_merchant(("Merchant client"))

node_merchant -->|"submits requests"| node_api_service
node_api_service -->|"enqueues jobs"| node_redis
node_worker -->|"claims jobs"| node_redis
node_worker -->|"reads and records payouts"| node_postgres
node_worker -->|"requests payout"| node_bank
node_worker -.->|"may target locally"| node_mockbank
node_api_service -->|"reads settlements"| node_postgres
node_daily_report -->|"aggregates settlements"| node_postgres
node_migration_runner -->|"applies schema changes"| node_postgres
node_api_service -->|"uses settings"| node_config
node_worker -->|"uses settings"| node_config
node_api_service -->|"sets up logging"| node_logging
node_worker -->|"sets up logging"| node_logging
node_migration_runner -->|"sets up logging"| node_logging
node_api_service -->|"records and serves"| node_metrics
node_worker -->|"records job metrics"| node_metrics
node_metrics -.->|"feeds dashboards"| node_observability

click node_api_service "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/api.py"
click node_daily_report "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/api.py"
click node_worker "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/worker.py"
click node_mockbank "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/mockbank.py"
click node_migration_runner "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/migrate.py"
click node_config "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/config.py"
click node_logging "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/logging_setup.py"
click node_metrics "https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/metrics.py"
click node_observability "https://github.com/manojcloud/tidewater-link2build/tree/main/observability"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_service,node_daily_report,node_merchant toneBlue
class node_worker,node_bank,node_mockbank toneAmber
class node_postgres,node_redis,node_migration_runner toneMint
class node_config,node_logging,node_metrics,node_observability toneRose
```

## Components

### API and reporting

- [Settlement API](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/api.py): `app/settle/api.py`
- [Daily reports](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/api.py): `app/settle/api.py`

### Settlement processing

- [Settlement worker](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/worker.py): `app/settle/worker.py`
- **Bank service**
- [Mock bank](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/mockbank.py): `app/settle/mockbank.py`

### State and dependencies

- **PostgreSQL**
- **Redis queue**
- [Migration runner](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/migrate.py): `app/settle/migrate.py`

### Operations and observability

- [Runtime configuration](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/config.py): `app/settle/config.py`
- [Structured logging](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/logging_setup.py): `app/settle/logging_setup.py`
- [Service metrics](https://github.com/manojcloud/tidewater-link2build/blob/main/app/settle/metrics.py): `app/settle/metrics.py`
- [Dashboards and alerts](https://github.com/manojcloud/tidewater-link2build/tree/main/observability): `observability`

### Other components

- **Merchant client**

## Connections

- Merchant client → Settlement API: submits requests (evidence: `README.md`)
- Settlement API → Redis queue: enqueues jobs (evidence: `app/settle/api.py`)
- Settlement worker → Redis queue: claims jobs (evidence: `app/settle/worker.py`)
- Settlement worker → PostgreSQL: reads and records payouts (evidence: `app/settle/worker.py`)
- Settlement worker → Bank service: requests payout (evidence: `app/settle/worker.py`)
- Settlement worker → Mock bank: may target locally
- Settlement API → PostgreSQL: reads settlements (evidence: `app/settle/api.py`)
- Daily reports → PostgreSQL: aggregates settlements (evidence: `app/settle/api.py`)
- Migration runner → PostgreSQL: applies schema changes (evidence: `app/settle/migrate.py`)
- Settlement API → Runtime configuration: uses settings (evidence: `app/settle/api.py`)
- Settlement worker → Runtime configuration: uses settings (evidence: `app/settle/worker.py`)
- Settlement API → Structured logging: sets up logging (evidence: `app/settle/api.py`)
- Settlement worker → Structured logging: sets up logging (evidence: `app/settle/worker.py`)
- Migration runner → Structured logging: sets up logging (evidence: `app/settle/migrate.py`)
- Settlement API → Service metrics: records and serves (evidence: `app/settle/api.py`)
- Settlement worker → Service metrics: records job metrics (evidence: `app/settle/worker.py`)
- Service metrics → Dashboards and alerts: feeds dashboards (evidence: `README.md`)
