# khayaai/a-card architecture

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

- Interactive diagram: https://gitdiagram.com/khayaai/a-card
- Repository: https://github.com/khayaai/a-card

## Overview

A-CARD provides scoped virtual cards and prepaid wallets for AI agents, with a human-operated dashboard and merchant directory. The principal flow is an agent request through MCP or another API client, API authorization, policy/rules and approval checks, then a ledger hold and payment rail; outcomes are recorded and exposed as transactions. Core domain logic is separated from API adapters and durable stores. The README documents capabilities beyond the sampled excerpts; those branches are included where documented, while uncertain internal call paths are omitted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/app.ts) (REST API), [`packages/core/src/platform.ts`](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/platform.ts) (Platform operations), [`packages/core/src/afp.ts`](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/afp.ts) (AFP routing and ledger), [`apps/api/src/afp/workers.ts`](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/afp/workers.ts) (Settlement workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client surfaces"]
  node_mcp["MCP tools<br/>[server.ts]"]
  node_mcpclient["API client<br/>[client.ts]"]
  node_cli["CLI<br/>[index.ts]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_merchantportal["Merchant portal<br/>[page.tsx]"]
end

subgraph group_api["API and controls"]
  node_rest["REST API<br/>[app.ts]"]
  node_service[("Platform service stores")]
  node_payfast["PayFast<br/>[payfast.ts]"]
end

subgraph group_domain["Core domain"]
  node_auth["Identity and RBAC<br/>[auth.ts]"]
  node_platform["Platform operations<br/>[platform.ts]"]
  node_cards["Cards and wallets<br/>[cards.ts]"]
  node_ledger[("Double-entry ledger<br/>[ledger.ts]")]
  node_rules["Rules and approvals<br/>[rules.ts]"]
  node_enterprise["Enterprise governance<br/>[enterprise.ts]"]
  node_billing["Billing tiers<br/>[billing.ts]"]
end

subgraph group_payments["Payments and compliance"]
  node_compliance["KYC KYB AML<br/>[didit.ts]"]
  node_afp["AFP routing and ledger<br/>[afp.ts]"]
  node_rails["Payment rails"]
  node_workers["Settlement workers<br/>[workers.ts]"]
end

subgraph group_merchant["Merchant network"]
  node_merchant[("Merchant directory<br/>[merchants.ts]")]
  node_merchantstore[("Merchant stores<br/>[postgres.ts]")]
  node_merchantpush["Merchant webhooks<br/>[webhooks.ts]"]
end

node_agent(("AI agent"))
node_operator(("Human operator"))

node_agent -->|"uses tools"| node_mcp
node_mcp -->|"calls"| node_mcpclient
node_mcpclient -->|"HTTP requests"| node_rest
node_operator -->|"manages"| node_dashboard
node_dashboard -->|"uses API"| node_rest
node_operator -->|"runs commands"| node_cli
node_cli -->|"uses API"| node_rest
node_operator -->|"manages catalog"| node_merchantportal
node_rest -->|"handles operations"| node_platform
node_rest -->|"guards requests"| node_auth
node_rest -->|"persists state"| node_service
node_service -->|"implements ledger"| node_ledger
node_platform -->|"manages lifecycle"| node_cards
node_platform -->|"checks authorization"| node_rules
node_platform -->|"enforces policy"| node_enterprise
node_platform -->|"records holds"| node_ledger
node_rest -->|"routes screening"| node_compliance
node_rest -->|"routes AFP"| node_afp
node_afp -->|"selects rail"| node_rails
node_workers -->|"confirms outcomes"| node_rails
node_workers -->|"updates transactions"| node_afp
node_rest -->|"serves directory"| node_merchant
node_rest -->|"persists merchant data"| node_merchantstore
node_rest -->|"delivers events"| node_merchantpush
node_merchantpush -->|"sends signed events"| node_merchant
node_rest -->|"handles billing"| node_payfast
node_rest -->|"enforces tiers"| node_billing

click node_mcp "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/mcp/src/server.ts"
click node_mcpclient "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/mcp/src/client.ts"
click node_cli "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/cli/src/index.ts"
click node_dashboard "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/dashboard/app/page.tsx"
click node_merchantportal "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/dashboard/app/merchant/page.tsx"
click node_rest "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/app.ts"
click node_auth "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/auth.ts"
click node_platform "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/platform.ts"
click node_cards "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/cards.ts"
click node_ledger "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/ledger.ts"
click node_rules "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/rules.ts"
click node_enterprise "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/enterprise.ts"
click node_billing "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/billing.ts"
click node_service "https://github.com/khayaai/a-card/tree/claude/agentcard-platform-build-affhcj/apps/api/src/service"
click node_compliance "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/compliance/didit.ts"
click node_afp "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/afp.ts"
click node_rails "https://github.com/khayaai/a-card/tree/claude/agentcard-platform-build-affhcj/apps/api/src/rails"
click node_workers "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/afp/workers.ts"
click node_merchant "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/merchants.ts"
click node_merchantstore "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/merchant/postgres.ts"
click node_merchantpush "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/merchant/webhooks.ts"
click node_payfast "https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/payfast.ts"

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_mcp,node_mcpclient,node_cli,node_dashboard,node_merchantportal toneBlue
class node_rest,node_service,node_payfast toneAmber
class node_auth,node_platform,node_cards,node_ledger,node_rules,node_enterprise,node_billing toneMint
class node_compliance,node_afp,node_rails,node_workers toneRose
class node_merchant,node_merchantstore,node_merchantpush,node_agent,node_operator toneIndigo
```

## Components

### Client surfaces

- [MCP tools](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/mcp/src/server.ts): `apps/mcp/src/server.ts`
- [API client](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/mcp/src/client.ts): `apps/mcp/src/client.ts`
- [CLI](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [Dashboard](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/dashboard/app/page.tsx): `apps/dashboard/app/page.tsx`
- [Merchant portal](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/dashboard/app/merchant/page.tsx): `apps/dashboard/app/merchant/page.tsx`

### API and controls

- [REST API](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Platform service stores](https://github.com/khayaai/a-card/tree/claude/agentcard-platform-build-affhcj/apps/api/src/service): `apps/api/src/service`
- [PayFast](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/payfast.ts): `apps/api/src/payfast.ts`

### Core domain

- [Identity and RBAC](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/auth.ts): `packages/core/src/auth.ts`
- [Platform operations](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/platform.ts): `packages/core/src/platform.ts`
- [Cards and wallets](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/cards.ts): `packages/core/src/cards.ts`
- [Double-entry ledger](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/ledger.ts): `packages/core/src/ledger.ts`
- [Rules and approvals](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/rules.ts): `packages/core/src/rules.ts`
- [Enterprise governance](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/enterprise.ts): `packages/core/src/enterprise.ts`
- [Billing tiers](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/billing.ts): `packages/core/src/billing.ts`

### Payments and compliance

- [KYC KYB AML](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/compliance/didit.ts): `apps/api/src/compliance/didit.ts`
- [AFP routing and ledger](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/afp.ts): `packages/core/src/afp.ts`
- [Payment rails](https://github.com/khayaai/a-card/tree/claude/agentcard-platform-build-affhcj/apps/api/src/rails): `apps/api/src/rails`
- [Settlement workers](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/afp/workers.ts): `apps/api/src/afp/workers.ts`

### Merchant network

- [Merchant directory](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/packages/core/src/merchants.ts): `packages/core/src/merchants.ts`
- [Merchant stores](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/merchant/postgres.ts): `apps/api/src/merchant/postgres.ts`
- [Merchant webhooks](https://github.com/khayaai/a-card/blob/claude/agentcard-platform-build-affhcj/apps/api/src/merchant/webhooks.ts): `apps/api/src/merchant/webhooks.ts`

### Other components

- **AI agent**
- **Human operator**

## Connections

- AI agent → MCP tools: uses tools
- MCP tools → API client: calls (evidence: `apps/mcp/src/server.ts`)
- API client → REST API: HTTP requests (evidence: `apps/mcp/src/client.ts`)
- Human operator → Dashboard: manages
- Dashboard → REST API: uses API
- Human operator → CLI: runs commands
- CLI → REST API: uses API
- Human operator → Merchant portal: manages catalog
- REST API → Platform operations: handles operations
- REST API → Identity and RBAC: guards requests
- REST API → Platform service stores: persists state (evidence: `apps/api/src/app.ts`)
- Platform service stores → Double-entry ledger: implements ledger
- Platform operations → Cards and wallets: manages lifecycle
- Platform operations → Rules and approvals: checks authorization
- Platform operations → Enterprise governance: enforces policy
- Platform operations → Double-entry ledger: records holds
- REST API → KYC KYB AML: routes screening (evidence: `apps/api/src/app.ts`)
- REST API → AFP routing and ledger: routes AFP (evidence: `apps/api/src/app.ts`)
- AFP routing and ledger → Payment rails: selects rail (evidence: `apps/api/src/rails/types.ts`)
- Settlement workers → Payment rails: confirms outcomes (evidence: `apps/api/src/afp/workers.ts`)
- Settlement workers → AFP routing and ledger: updates transactions (evidence: `apps/api/src/afp/workers.ts`)
- REST API → Merchant directory: serves directory
- REST API → Merchant stores: persists merchant data
- REST API → Merchant webhooks: delivers events (evidence: `apps/api/src/app.ts`)
- Merchant webhooks → Merchant directory: sends signed events (evidence: `apps/api/src/merchant/webhooks.ts`)
- REST API → PayFast: handles billing (evidence: `apps/api/src/app.ts`)
- REST API → Billing tiers: enforces tiers
