# safoosafa/vouchermanagement-docs architecture

> Architecture diagram of the GitHub repository safoosafa/vouchermanagement-docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safoosafa/vouchermanagement-docs
- Repository: https://github.com/safoosafa/vouchermanagement-docs

## Overview

This repository documents MITF Voucher Provider, a voucher-stock platform with channel purchases, bank inventories, integrations, and a microservice ledger. The graph captures its documented services and domain capabilities, but not implementation-level call wiring: the repository tree contains documentation only, and the supplied source excerpt contains only documentation dependencies.

Main entry points: [`docs/reference/purchase-orchestrator.md`](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/purchase-orchestrator.md) (Purchase orchestrator), [`docs/architecture/outbox-and-ledger-consistency.md`](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/outbox-and-ledger-consistency.md) (Microservice ledger), [`docs/reference/external-api.md`](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/external-api.md) (External API), [`docs/architecture/README.md`](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/README.md) (Central stock custody)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Channels and APIs"]
  node_external_api["External API<br/>[external-api.md]"]
  node_gateway["Gateway<br/>[gateway.md]"]
  node_internal_api["Internal API<br/>[internal-api.md]"]
  node_management_api["Management API<br/>[management-api.md]"]
  node_stock_spa["Stock SPA"]
end

subgraph group_voucher["Voucher operations"]
  node_purchase["Purchase orchestrator"]
  node_central_stock[("Central stock custody<br/>[README.md]")]
  node_bank_inventory[("Bank inventory<br/>[README.md]")]
  node_kyc_approval["KYC and approval"]
  node_provider_integration["Provider integrations<br/>[README.md]"]
end

subgraph group_money["Money movement"]
  node_ledger[("Microservice ledger")]
  node_money_movement["Money movement"]
end

subgraph group_oversight["Operations and oversight"]
  node_reports["Reports"]
  node_reconciliation["Reconciliation<br/>[reconciliation.md]"]
end

node_bank(("Bank / partner"))
node_channel(("Purchase channel"))
node_admin(("Admin operator"))
node_external(("Third-party provider"))

node_channel -->|"purchases"| node_external_api
node_bank -->|"partner access"| node_gateway
node_admin -->|"administers"| node_management_api
node_admin -->|"manages stock"| node_stock_spa
node_external -.->|"integrates"| node_provider_integration
node_external_api -->|"purchase flow"| node_purchase
node_purchase -->|"uses stock"| node_central_stock
node_central_stock -->|"allocates stock"| node_bank_inventory
node_purchase -->|"records activity"| node_ledger
node_money_movement -->|"ledger consistency"| node_ledger
node_internal_api -->|"supports approval"| node_kyc_approval
node_reports -->|"reports stock"| node_bank_inventory
node_reconciliation -->|"checks consistency"| node_ledger

click node_external_api "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/external-api.md"
click node_gateway "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/gateway.md"
click node_internal_api "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/internal-api.md"
click node_management_api "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/management-api.md"
click node_stock_spa "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/vouchers-stock-spa.md"
click node_purchase "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/purchase-orchestrator.md"
click node_central_stock "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/README.md"
click node_bank_inventory "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/README.md"
click node_kyc_approval "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/kyc-flow-validation-and-portal-approval.md"
click node_ledger "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/outbox-and-ledger-consistency.md"
click node_money_movement "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/money-movement-sequence-diagrams.md"
click node_provider_integration "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/integrations/README.md"
click node_reports "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/reports-api-guide.md"
click node_reconciliation "https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reconciliation/reconciliation.md"

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_external_api,node_gateway,node_internal_api,node_management_api,node_stock_spa toneBlue
class node_purchase,node_central_stock,node_bank_inventory,node_kyc_approval,node_provider_integration toneAmber
class node_ledger,node_money_movement toneMint
class node_reports,node_reconciliation toneRose
class node_bank,node_channel,node_admin,node_external toneIndigo
```

## Components

### Channels and APIs

- [External API](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/external-api.md): `docs/reference/external-api.md`
- [Gateway](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/gateway.md): `docs/reference/gateway.md`
- [Internal API](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/internal-api.md): `docs/reference/internal-api.md`
- [Management API](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/management-api.md): `docs/reference/management-api.md`
- [Stock SPA](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/vouchers-stock-spa.md): `docs/reference/vouchers-stock-spa.md`

### Voucher operations

- [Purchase orchestrator](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/purchase-orchestrator.md): `docs/reference/purchase-orchestrator.md`
- [Central stock custody](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/README.md): `docs/architecture/README.md`
- [Bank inventory](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/README.md): `docs/architecture/README.md`
- [KYC and approval](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/kyc-flow-validation-and-portal-approval.md): `docs/architecture/kyc-flow-validation-and-portal-approval.md`
- [Provider integrations](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/integrations/README.md): `docs/integrations/README.md`

### Money movement

- [Microservice ledger](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/outbox-and-ledger-consistency.md): `docs/architecture/outbox-and-ledger-consistency.md`
- [Money movement](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/architecture/money-movement-sequence-diagrams.md): `docs/architecture/money-movement-sequence-diagrams.md`

### Operations and oversight

- [Reports](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reference/reports-api-guide.md): `docs/reference/reports-api-guide.md`
- [Reconciliation](https://github.com/safoosafa/vouchermanagement-docs/blob/main/docs/reconciliation/reconciliation.md): `docs/reconciliation/reconciliation.md`

### Other components

- **Bank / partner**
- **Purchase channel**
- **Admin operator**
- **Third-party provider**

## Connections

- Purchase channel → External API: purchases
- Bank / partner → Gateway: partner access
- Admin operator → Management API: administers
- Admin operator → Stock SPA: manages stock
- Third-party provider → Provider integrations: integrates
- External API → Purchase orchestrator: purchase flow
- Purchase orchestrator → Central stock custody: uses stock
- Central stock custody → Bank inventory: allocates stock
- Purchase orchestrator → Microservice ledger: records activity
- Money movement → Microservice ledger: ledger consistency
- Internal API → KYC and approval: supports approval
- Reports → Bank inventory: reports stock
- Reconciliation → Microservice ledger: checks consistency