# nageshgarje/mandate architecture

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

- Interactive diagram: https://gitdiagram.com/nageshgarje/mandate
- Repository: https://github.com/nageshgarje/mandate

## Overview

MandateHQ Core is a mandate-management service. Its main user-facing path enters through the API server and reaches mandate and customer operations; related services handle payment/execution state and issuer-specific integrations. The repository also includes hosted-card authentication, IIN lookup, notifications, webhooks, and background workers. Edges below are limited to registrations or dependencies visible in the supplied excerpts and SOURCE INDEX; unsampled runtime wiring is not inferred.

Main entry points: [`internal/mandates/service/server.go`](https://github.com/nageshgarje/mandate/blob/main/internal/mandates/service/server.go) (Mandate operations), [`cmd/api/main.go`](https://github.com/nageshgarje/mandate/blob/main/cmd/api/main.go) (API bootstrap), [`internal/customer/service/server.go`](https://github.com/nageshgarje/mandate/blob/main/internal/customer/service/server.go) (Customer operations), [`internal/server/server.go`](https://github.com/nageshgarje/mandate/blob/main/internal/server/server.go) (HTTP and gRPC server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and customer operations"]
  node_api_main["API bootstrap<br/>[main.go]"]
  node_server["HTTP and gRPC server<br/>[server.go]"]
  node_customer["Customer operations<br/>[server.go]"]
  node_acs["Card authentication<br/>[server.go]"]
  node_iin["IIN lookup<br/>[server.go]"]
  node_instruments["Card instruments<br/>[server.go]"]
end

subgraph group_mandate["Mandate lifecycle"]
  node_mandates["Mandate operations<br/>[server.go]"]
  node_execution["Execution tracking<br/>[server.go]"]
  node_payment["Payment state<br/>[server.go]"]
end

subgraph group_integrations["Issuer integrations"]
  node_rupay["RuPay integration<br/>[server.go]"]
  node_hub["Hub interoperability<br/>[server.go]"]
  node_sihub["SIHub integration<br/>[server.go]"]
  node_issuer_api["Issuer adapters<br/>[server.go]"]
end

subgraph group_async["Notifications and workers"]
  node_notification["Notification service<br/>[server.go]"]
  node_webhook["Mandate webhooks<br/>[server.go]"]
  node_worker["Background worker runtime<br/>[manager.go]"]
  node_queue["Queue backends<br/>[queue_manager.go]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_server
node_api_main -->|"starts server"| node_server
node_api_main -->|"registers API"| node_mandates
node_api_main -->|"constructs service"| node_customer
node_api_main -->|"constructs service"| node_acs
node_api_main -->|"registers API"| node_iin
node_server -->|"routes requests"| node_mandates
node_customer -->|"fetches mandate"| node_mandates
node_customer -->|"delegates RuPay"| node_rupay
node_mandates -->|"reads execution"| node_execution
node_mandates -.->|"uses payment state"| node_payment
node_rupay -->|"reads mandate"| node_mandates
node_hub -->|"fetches mandate"| node_mandates
node_sihub -.->|"creates payment"| node_payment
node_worker -->|"enqueues jobs"| node_queue

click node_api_main "https://github.com/nageshgarje/mandate/blob/main/cmd/api/main.go"
click node_server "https://github.com/nageshgarje/mandate/blob/main/internal/server/server.go"
click node_customer "https://github.com/nageshgarje/mandate/blob/main/internal/customer/service/server.go"
click node_acs "https://github.com/nageshgarje/mandate/blob/main/internal/acs/service/server.go"
click node_iin "https://github.com/nageshgarje/mandate/blob/main/internal/iin/service/server.go"
click node_instruments "https://github.com/nageshgarje/mandate/blob/main/internal/instruments/server.go"
click node_mandates "https://github.com/nageshgarje/mandate/blob/main/internal/mandates/service/server.go"
click node_execution "https://github.com/nageshgarje/mandate/blob/main/internal/execution/service/server.go"
click node_payment "https://github.com/nageshgarje/mandate/blob/main/internal/payment/service/server.go"
click node_rupay "https://github.com/nageshgarje/mandate/blob/main/internal/rupay_integration/service/server.go"
click node_hub "https://github.com/nageshgarje/mandate/blob/main/internal/hub_interoperability/service/server.go"
click node_sihub "https://github.com/nageshgarje/mandate/blob/main/internal/sihub/service/server.go"
click node_issuer_api "https://github.com/nageshgarje/mandate/blob/main/internal/issuer_api/server.go"
click node_notification "https://github.com/nageshgarje/mandate/blob/main/internal/notification/service/server.go"
click node_webhook "https://github.com/nageshgarje/mandate/blob/main/internal/mandate_webhook/server.go"
click node_worker "https://github.com/nageshgarje/mandate/blob/main/pkg/worker/manager.go"
click node_queue "https://github.com/nageshgarje/mandate/blob/main/pkg/worker/queue/queue_manager.go"

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_main,node_server,node_customer,node_acs,node_iin,node_instruments,node_client toneBlue
class node_mandates,node_execution,node_payment toneAmber
class node_rupay,node_hub,node_sihub,node_issuer_api toneMint
class node_notification,node_webhook,node_worker,node_queue toneRose
```

## Components

### API and customer operations

- [API bootstrap](https://github.com/nageshgarje/mandate/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [HTTP and gRPC server](https://github.com/nageshgarje/mandate/blob/main/internal/server/server.go): `internal/server/server.go`
- [Customer operations](https://github.com/nageshgarje/mandate/blob/main/internal/customer/service/server.go): `internal/customer/service/server.go`
- [Card authentication](https://github.com/nageshgarje/mandate/blob/main/internal/acs/service/server.go): `internal/acs/service/server.go`
- [IIN lookup](https://github.com/nageshgarje/mandate/blob/main/internal/iin/service/server.go): `internal/iin/service/server.go`
- [Card instruments](https://github.com/nageshgarje/mandate/blob/main/internal/instruments/server.go): `internal/instruments/server.go`

### Mandate lifecycle

- [Mandate operations](https://github.com/nageshgarje/mandate/blob/main/internal/mandates/service/server.go): `internal/mandates/service/server.go`
- [Execution tracking](https://github.com/nageshgarje/mandate/blob/main/internal/execution/service/server.go): `internal/execution/service/server.go`
- [Payment state](https://github.com/nageshgarje/mandate/blob/main/internal/payment/service/server.go): `internal/payment/service/server.go`

### Issuer integrations

- [RuPay integration](https://github.com/nageshgarje/mandate/blob/main/internal/rupay_integration/service/server.go): `internal/rupay_integration/service/server.go`
- [Hub interoperability](https://github.com/nageshgarje/mandate/blob/main/internal/hub_interoperability/service/server.go): `internal/hub_interoperability/service/server.go`
- [SIHub integration](https://github.com/nageshgarje/mandate/blob/main/internal/sihub/service/server.go): `internal/sihub/service/server.go`
- [Issuer adapters](https://github.com/nageshgarje/mandate/blob/main/internal/issuer_api/server.go): `internal/issuer_api/server.go`

### Notifications and workers

- [Notification service](https://github.com/nageshgarje/mandate/blob/main/internal/notification/service/server.go): `internal/notification/service/server.go`
- [Mandate webhooks](https://github.com/nageshgarje/mandate/blob/main/internal/mandate_webhook/server.go): `internal/mandate_webhook/server.go`
- [Background worker runtime](https://github.com/nageshgarje/mandate/blob/main/pkg/worker/manager.go): `pkg/worker/manager.go`
- [Queue backends](https://github.com/nageshgarje/mandate/blob/main/pkg/worker/queue/queue_manager.go): `pkg/worker/queue/queue_manager.go`

### Other components

- **API client**

## Connections

- API client → HTTP and gRPC server: sends requests (evidence: `internal/server/server.go`)
- API bootstrap → HTTP and gRPC server: starts server (evidence: `cmd/api/main.go`)
- API bootstrap → Mandate operations: registers API (evidence: `cmd/api/main.go`)
- API bootstrap → Customer operations: constructs service (evidence: `cmd/api/main.go`)
- API bootstrap → Card authentication: constructs service (evidence: `cmd/api/main.go`)
- API bootstrap → IIN lookup: registers API (evidence: `cmd/api/main.go`)
- HTTP and gRPC server → Mandate operations: routes requests (evidence: `internal/server/server.go`)
- Customer operations → Mandate operations: fetches mandate (evidence: `internal/customer/service/server.go`)
- Customer operations → RuPay integration: delegates RuPay (evidence: `internal/customer/service/server.go`)
- Mandate operations → Execution tracking: reads execution (evidence: `internal/mandates/service/server.go`)
- Mandate operations → Payment state: uses payment state
- RuPay integration → Mandate operations: reads mandate (evidence: `internal/rupay_integration/service/server.go`)
- Hub interoperability → Mandate operations: fetches mandate (evidence: `internal/hub_interoperability/service/server.go`)
- SIHub integration → Payment state: creates payment
- Background worker runtime → Queue backends: enqueues jobs (evidence: `pkg/worker/manager.go`)
