# rakshityadav1868/kairo-main architecture

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

- Interactive diagram: https://gitdiagram.com/rakshityadav1868/kairo-main
- Repository: https://github.com/rakshityadav1868/kairo-main

## Overview

Kairo is a payment orchestration platform: a merchant integrates through the SDK or dashboard, configures projects, keys, providers and routing, then creates payments/refunds and receives normalized webhook outcomes. The Go API owns routing and provider operations; PostgreSQL-backed services support identity, billing, limits, analytics and audit. The graph also preserves documented dashboard, SDK, provider, webhook and usage capabilities. Some links are limited to the entrypoint’s route/setup excerpt and SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`backend/cmd/api/main.go`](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/cmd/api/main.go) (Go API server), [`backend/internal/db/queries/db.go`](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/db/queries/db.go) (PostgreSQL queries), [`backend/internal/webhook/provider_handler.go`](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/webhook/provider_handler.go) (Webhook ingestion), [`backend/internal/payment/service.go`](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/payment/service.go) (Payment operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Merchant interfaces"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
  node_sdk_http["SDK HTTP transport<br/>[http.ts]"]
end

subgraph group_api["API and identity"]
  node_api_server["Go API server<br/>[main.go]"]
  node_auth["Authentication<br/>[service.go]"]
  node_projects["Project management<br/>[handler.go]"]
  node_api_keys["API key management<br/>[handler.go]"]
end

subgraph group_payments["Payment orchestration"]
  node_payments["Payment operations<br/>[service.go]"]
  node_routing["Provider routing<br/>[routing_engine.go]"]
  node_providers["Provider integrations<br/>[service.go]"]
  node_provider_registry["Provider registry<br/>[registry.go]"]
  node_webhook_ingest["Webhook ingestion"]
  node_webhook_mapping["Event normalization"]
  node_webhook_dispatch["Webhook dispatch<br/>[dispatcher.go]"]
end

subgraph group_operations["Operations and insight"]
  node_billing["Plan billing<br/>[service.go]"]
  node_usage["Usage and limits<br/>[service.go]"]
  node_analytics["Analytics<br/>[service.go]"]
  node_audit["Audit trail<br/>[service.go]"]
  node_database[("PostgreSQL queries<br/>[db.go]")]
end

node_merchant(("Merchant developer"))
node_payment_provider["Payment providers"]
node_merchant_endpoint["Merchant webhook endpoint"]

node_merchant -.->|"configures"| node_dashboard
node_dashboard -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls API"| node_api_server
node_merchant -.->|"integrates"| node_sdk
node_sdk -->|"uses transport"| node_sdk_http
node_sdk_http -.->|"sends requests"| node_api_server
node_api_server -->|"routes auth"| node_auth
node_api_server -->|"routes projects"| node_projects
node_api_server -->|"routes keys"| node_api_keys
node_api_server -->|"routes payments"| node_payments
node_api_server -->|"routes decisions"| node_routing
node_api_server -->|"routes webhooks"| node_webhook_ingest
node_api_server -->|"registers providers"| node_provider_registry
node_api_server -->|"starts worker"| node_webhook_dispatch
node_webhook_ingest -->|"maps events"| node_webhook_mapping
node_webhook_ingest -->|"decrypts credentials"| node_providers
node_webhook_ingest -->|"queues events"| node_webhook_dispatch
node_webhook_ingest -->|"records events"| node_database
node_payments -.->|"selects provider"| node_routing
node_payments -.->|"executes payment"| node_providers
node_providers -.->|"integrates"| node_payment_provider
node_routing -->|"loads rules"| node_database
node_auth -->|"stores identities"| node_database
node_billing -->|"records plan transactions"| node_database
node_usage -->|"reads usage"| node_database
node_analytics -->|"queries analytics"| node_database
node_webhook_dispatch -.->|"delivers events"| node_merchant_endpoint
node_api_server -->|"routes billing"| node_billing
node_api_server -->|"routes usage"| node_usage
node_api_server -->|"routes analytics"| node_analytics
node_api_server -.->|"routes audit"| node_audit

click node_dashboard "https://github.com/rakshityadav1868/kairo-main/blob/main/frontend/app/(dashboard)/projects/%5BprojectId%5D/page.tsx"
click node_frontend_api "https://github.com/rakshityadav1868/kairo-main/blob/main/frontend/lib/api.ts"
click node_sdk "https://github.com/rakshityadav1868/kairo-main/blob/main/sdk/src/client.ts"
click node_sdk_http "https://github.com/rakshityadav1868/kairo-main/blob/main/sdk/src/http.ts"
click node_api_server "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/cmd/api/main.go"
click node_auth "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/auth/service.go"
click node_projects "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/project/handler.go"
click node_api_keys "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/apikey/handler.go"
click node_payments "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/payment/service.go"
click node_routing "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/payment/routing_engine.go"
click node_providers "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/provider/service.go"
click node_provider_registry "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/provider/registry.go"
click node_webhook_ingest "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/webhook/provider_handler.go"
click node_webhook_mapping "https://github.com/rakshityadav1868/kairo-main/tree/main/backend/internal/webhook/providers"
click node_webhook_dispatch "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/webhook/dispatcher.go"
click node_billing "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/billing/service.go"
click node_usage "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/usage/service.go"
click node_analytics "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/analytics/service.go"
click node_audit "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/audit/service.go"
click node_database "https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/db/queries/db.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_dashboard,node_frontend_api,node_sdk,node_sdk_http toneBlue
class node_api_server,node_auth,node_projects,node_api_keys toneAmber
class node_payments,node_routing,node_providers,node_provider_registry,node_webhook_ingest,node_webhook_mapping,node_webhook_dispatch,node_merchant_endpoint toneMint
class node_billing,node_usage,node_analytics,node_audit,node_database toneRose
class node_merchant,node_payment_provider toneIndigo
```

## Components

### Merchant interfaces

- [Dashboard](https://github.com/rakshityadav1868/kairo-main/blob/main/frontend/app/(dashboard)/projects/%5BprojectId%5D/page.tsx): `frontend/app/(dashboard)/projects/[projectId]/page.tsx`
- [Frontend API client](https://github.com/rakshityadav1868/kairo-main/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [TypeScript SDK](https://github.com/rakshityadav1868/kairo-main/blob/main/sdk/src/client.ts): `sdk/src/client.ts`
- [SDK HTTP transport](https://github.com/rakshityadav1868/kairo-main/blob/main/sdk/src/http.ts): `sdk/src/http.ts`

### API and identity

- [Go API server](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/cmd/api/main.go): `backend/cmd/api/main.go`
- [Authentication](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/auth/service.go): `backend/internal/auth/service.go`
- [Project management](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/project/handler.go): `backend/internal/project/handler.go`
- [API key management](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/apikey/handler.go): `backend/internal/apikey/handler.go`

### Payment orchestration

- [Payment operations](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/payment/service.go): `backend/internal/payment/service.go`
- [Provider routing](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/payment/routing_engine.go): `backend/internal/payment/routing_engine.go`
- [Provider integrations](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/provider/service.go): `backend/internal/provider/service.go`
- [Provider registry](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/provider/registry.go): `backend/internal/provider/registry.go`
- [Webhook ingestion](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/webhook/provider_handler.go): `backend/internal/webhook/provider_handler.go`
- [Event normalization](https://github.com/rakshityadav1868/kairo-main/tree/main/backend/internal/webhook/providers): `backend/internal/webhook/providers`
- [Webhook dispatch](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/webhook/dispatcher.go): `backend/internal/webhook/dispatcher.go`

### Operations and insight

- [Plan billing](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/billing/service.go): `backend/internal/billing/service.go`
- [Usage and limits](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/usage/service.go): `backend/internal/usage/service.go`
- [Analytics](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/analytics/service.go): `backend/internal/analytics/service.go`
- [Audit trail](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/audit/service.go): `backend/internal/audit/service.go`
- [PostgreSQL queries](https://github.com/rakshityadav1868/kairo-main/blob/main/backend/internal/db/queries/db.go): `backend/internal/db/queries/db.go`

### Other components

- **Merchant developer**
- **Payment providers**
- **Merchant webhook endpoint**

## Connections

- Merchant developer → Dashboard: configures
- Dashboard → Frontend API client: requests data
- Frontend API client → Go API server: calls API
- Merchant developer → TypeScript SDK: integrates
- TypeScript SDK → SDK HTTP transport: uses transport (evidence: `sdk/src/client.ts`)
- SDK HTTP transport → Go API server: sends requests
- Go API server → Authentication: routes auth (evidence: `backend/cmd/api/main.go`)
- Go API server → Project management: routes projects (evidence: `backend/cmd/api/main.go`)
- Go API server → API key management: routes keys (evidence: `backend/cmd/api/main.go`)
- Go API server → Payment operations: routes payments (evidence: `backend/cmd/api/main.go`)
- Go API server → Provider routing: routes decisions (evidence: `backend/cmd/api/main.go`)
- Go API server → Webhook ingestion: routes webhooks (evidence: `backend/cmd/api/main.go`)
- Go API server → Provider registry: registers providers (evidence: `backend/cmd/api/main.go`)
- Go API server → Webhook dispatch: starts worker (evidence: `backend/cmd/api/main.go`)
- Webhook ingestion → Event normalization: maps events (evidence: `backend/internal/webhook/provider_handler.go`)
- Webhook ingestion → Provider integrations: decrypts credentials (evidence: `backend/internal/webhook/provider_handler.go`)
- Webhook ingestion → Webhook dispatch: queues events (evidence: `backend/internal/webhook/provider_handler.go`)
- Webhook ingestion → PostgreSQL queries: records events (evidence: `backend/internal/webhook/provider_handler.go`)
- Payment operations → Provider routing: selects provider
- Payment operations → Provider integrations: executes payment
- Provider integrations → Payment providers: integrates
- Provider routing → PostgreSQL queries: loads rules (evidence: `backend/internal/payment/routing_engine.go`)
- Authentication → PostgreSQL queries: stores identities (evidence: `backend/internal/auth/service.go`)
- Plan billing → PostgreSQL queries: records plan transactions (evidence: `backend/internal/billing/service.go`)
- Usage and limits → PostgreSQL queries: reads usage (evidence: `backend/internal/usage/service.go`)
- Analytics → PostgreSQL queries: queries analytics (evidence: `backend/internal/analytics/service.go`)
- Webhook dispatch → Merchant webhook endpoint: delivers events
- Go API server → Plan billing: routes billing (evidence: `backend/cmd/api/main.go`)
- Go API server → Usage and limits: routes usage (evidence: `backend/cmd/api/main.go`)
- Go API server → Analytics: routes analytics (evidence: `backend/cmd/api/main.go`)
- Go API server → Audit trail: routes audit
