How adrian-obungu/synapse-reconciliation-engine works
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: router.py Callback Router · App.tsx Web App · storage.py Storage Engine · http.ts HTTP Client
Components 27
Webhook Gateway
- FastAPI App
app/main.py - Callback Router
app/api/router.py - OTP Routes
app/api/otp.py - Webhook Schema
app/schemas/mpesa.py
Compliance Processing
- Ledger Service
app/services/ledger.py - eTIMS Service
app/services/etims.py - Phone Normalizer
app/utils/phone.py - Invoice Schema
app/schemas/etims.py - Reconciliation Worker
worker.py
Persistence
- Storage Engine
app/services/storage.py - PostgreSQL Ledger
database.py
Operations Console
- Web App
frontend/src/App.tsx - Login Page
frontend/src/pages/LoginPage.tsx - Auth Store
frontend/src/stores/authStore.ts - Dashboard
frontend/src/pages/DashboardPage.tsx - Transactions
frontend/src/pages/TransactionsPage.tsx - Tax Mappings
frontend/src/pages/MappingsPage.tsx - Invoice Client
frontend/src/services/api/invoiceService.ts - Mapping Client
frontend/src/services/api/mappingService.ts - Dashboard Client
frontend/src/services/api/dashboardService.ts - HTTP Client
frontend/src/services/api/http.ts
Other components
- M-Pesa
- KRA eTIMS
- Redis
- Merchant Operator
- Supabase Auth
- Backend API
Connections 29
- 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