# adrian-obungu/synapse-reconciliation-engine architecture

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

- Interactive diagram: https://gitdiagram.com/adrian-obungu/synapse-reconciliation-engine
- Repository: https://github.com/adrian-obungu/synapse-reconciliation-engine

## Overview

Synapse receives M-Pesa callbacks, acknowledges novel events quickly, and processes them asynchronously into a ledger record and a KRA eTIMS invoice. Its web console provides authentication, dashboard, transaction, and tax-mapping workflows. The callback, storage, and worker paths are supported by sampled source; several UI capabilities and the KRA transformation details are documented or indicated by module names, so uncertain backend wiring is omitted.

Main entry points: [`app/api/router.py`](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/api/router.py) (Callback Router), [`frontend/src/App.tsx`](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/App.tsx) (Web App), [`app/services/storage.py`](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/storage.py) (Storage Engine), [`frontend/src/services/api/http.ts`](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/http.ts) (HTTP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Webhook Gateway"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_callback["Callback Router<br/>[router.py]"]
  node_otp_router["OTP Routes<br/>[otp.py]"]
  node_webhook_schema["Webhook Schema<br/>[mpesa.py]"]
end

subgraph group_processing["Compliance Processing"]
  node_ledger_service["Ledger Service<br/>[ledger.py]"]
  node_etims_service["eTIMS Service<br/>[etims.py]"]
  node_phone_normalizer["Phone Normalizer<br/>[phone.py]"]
  node_etims_schema["Invoice Schema<br/>[etims.py]"]
  node_worker["Reconciliation Worker<br/>[worker.py]"]
end

subgraph group_state["Persistence"]
  node_storage["Storage Engine<br/>[storage.py]"]
  node_ledger_db[("PostgreSQL Ledger<br/>[database.py]")]
end

subgraph group_console["Operations Console"]
  node_frontend_app["Web App<br/>[App.tsx]"]
  node_login["Login Page<br/>[LoginPage.tsx]"]
  node_auth_store["Auth Store<br/>[authStore.ts]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_transactions["Transactions"]
  node_mappings["Tax Mappings<br/>[MappingsPage.tsx]"]
  node_invoice_api["Invoice Client<br/>[invoiceService.ts]"]
  node_mapping_api["Mapping Client<br/>[mappingService.ts]"]
  node_dashboard_api["Dashboard Client"]
  node_http_client["HTTP Client<br/>[http.ts]"]
end

node_mpesa(("M-Pesa"))
node_kra(("KRA eTIMS"))
node_redis[("Redis")]
node_user(("Merchant Operator"))
node_supabase[("Supabase Auth")]
node_backend_api["Backend API"]

node_api_app -->|"mounts routes"| node_callback
node_api_app -->|"mounts routes"| node_otp_router
node_mpesa -->|"posts callback"| node_callback
node_callback -->|"validates payload"| node_webhook_schema
node_callback -->|"checks idempotency"| node_storage
node_callback -->|"dispatches background"| node_ledger_service
node_callback -->|"dispatches background"| node_etims_service
node_ledger_service -->|"commits ledger"| node_storage
node_storage -->|"locks duplicates"| node_redis
node_storage -->|"writes records"| node_ledger_db
node_etims_service -->|"builds invoice"| node_etims_schema
node_etims_service -->|"submits invoice"| node_kra
node_ledger_service -.->|"normalizes phone"| node_phone_normalizer
node_worker -->|"reads and updates"| node_ledger_db
node_user -->|"uses console"| node_frontend_app
node_frontend_app -->|"routes to"| node_login
node_frontend_app -->|"routes to"| node_dashboard
node_frontend_app -->|"routes to"| node_transactions
node_frontend_app -->|"routes to"| node_mappings
node_login -->|"uses auth state"| node_auth_store
node_auth_store -->|"manages session"| node_supabase
node_transactions -->|"requests transactions"| node_invoice_api
node_mappings -->|"requests mappings"| node_mapping_api
node_dashboard -->|"requests dashboard"| node_dashboard_api
node_invoice_api -->|"sends requests"| node_http_client
node_mapping_api -->|"sends requests"| node_http_client
node_dashboard_api -->|"sends requests"| node_http_client
node_http_client -->|"calls API"| node_backend_api
node_backend_api -->|"reaches service"| node_api_app

click node_api_app "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/main.py"
click node_callback "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/api/router.py"
click node_otp_router "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/api/otp.py"
click node_webhook_schema "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/schemas/mpesa.py"
click node_ledger_service "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/ledger.py"
click node_etims_service "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/etims.py"
click node_phone_normalizer "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/utils/phone.py"
click node_etims_schema "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/schemas/etims.py"
click node_storage "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/storage.py"
click node_ledger_db "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/database.py"
click node_worker "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/worker.py"
click node_frontend_app "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/LoginPage.tsx"
click node_auth_store "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/stores/authStore.ts"
click node_dashboard "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_transactions "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/TransactionsPage.tsx"
click node_mappings "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/MappingsPage.tsx"
click node_invoice_api "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/invoiceService.ts"
click node_mapping_api "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/mappingService.ts"
click node_dashboard_api "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/dashboardService.ts"
click node_http_client "https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/http.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_api_app,node_callback,node_otp_router,node_webhook_schema toneBlue
class node_ledger_service,node_etims_service,node_phone_normalizer,node_etims_schema,node_worker,node_redis,node_supabase toneAmber
class node_storage,node_ledger_db,node_backend_api toneMint
class node_frontend_app,node_login,node_auth_store,node_dashboard,node_transactions,node_mappings,node_invoice_api,node_mapping_api,node_dashboard_api,node_http_client toneRose
class node_mpesa,node_kra,node_user toneIndigo
```

## Components

### Webhook Gateway

- [FastAPI App](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/main.py): `app/main.py`
- [Callback Router](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/api/router.py): `app/api/router.py`
- [OTP Routes](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/api/otp.py): `app/api/otp.py`
- [Webhook Schema](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/schemas/mpesa.py): `app/schemas/mpesa.py`

### Compliance Processing

- [Ledger Service](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/ledger.py): `app/services/ledger.py`
- [eTIMS Service](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/etims.py): `app/services/etims.py`
- [Phone Normalizer](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/utils/phone.py): `app/utils/phone.py`
- [Invoice Schema](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/schemas/etims.py): `app/schemas/etims.py`
- [Reconciliation Worker](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/worker.py): `worker.py`

### Persistence

- [Storage Engine](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/app/services/storage.py): `app/services/storage.py`
- [PostgreSQL Ledger](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/database.py): `database.py`

### Operations Console

- [Web App](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login Page](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Auth Store](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/stores/authStore.ts): `frontend/src/stores/authStore.ts`
- [Dashboard](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Transactions](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/TransactionsPage.tsx): `frontend/src/pages/TransactionsPage.tsx`
- [Tax Mappings](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/pages/MappingsPage.tsx): `frontend/src/pages/MappingsPage.tsx`
- [Invoice Client](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/invoiceService.ts): `frontend/src/services/api/invoiceService.ts`
- [Mapping Client](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/mappingService.ts): `frontend/src/services/api/mappingService.ts`
- [Dashboard Client](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/dashboardService.ts): `frontend/src/services/api/dashboardService.ts`
- [HTTP Client](https://github.com/adrian-obungu/synapse-reconciliation-engine/blob/main/frontend/src/services/api/http.ts): `frontend/src/services/api/http.ts`

### Other components

- **M-Pesa**
- **KRA eTIMS**
- **Redis**
- **Merchant Operator**
- **Supabase Auth**
- **Backend API**

## Connections

- FastAPI App → Callback Router: mounts routes
- FastAPI App → OTP Routes: mounts routes
- M-Pesa → Callback Router: posts callback
- Callback Router → Webhook Schema: validates payload
- Callback Router → Storage Engine: checks idempotency
- Callback Router → Ledger Service: dispatches background
- Callback Router → eTIMS Service: dispatches background
- Ledger Service → Storage Engine: commits ledger
- Storage Engine → Redis: locks duplicates
- Storage Engine → PostgreSQL Ledger: writes records
- eTIMS Service → Invoice Schema: builds invoice
- eTIMS Service → KRA eTIMS: submits invoice
- Ledger Service → Phone Normalizer: normalizes phone
- Reconciliation Worker → PostgreSQL Ledger: reads and updates
- Merchant Operator → Web App: uses console
- Web App → Login Page: routes to
- Web App → Dashboard: routes to
- Web App → Transactions: routes to
- Web App → Tax Mappings: routes to
- Login Page → Auth Store: uses auth state
- Auth Store → Supabase Auth: manages session
- Transactions → Invoice Client: requests transactions
- Tax Mappings → Mapping Client: requests mappings
- Dashboard → Dashboard Client: requests dashboard
- Invoice Client → HTTP Client: sends requests
- Mapping Client → HTTP Client: sends requests
- Dashboard Client → HTTP Client: sends requests
- HTTP Client → Backend API: calls API
- Backend API → FastAPI App: reaches service