# khadimmbaye0/tontine-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/khadimmbaye0/tontine-pilot
- Repository: https://github.com/khadimmbaye0/tontine-pilot

## Overview

TontinePilot is a bilingual web app for managing community rotating-savings groups. A member signs in, selects a group, records a payment by text or receipt, and uses the shared ledger to review contributions, alerts, and rotation information. Backend functions parse declarations and receipts, support mediation and recommendations, and produce reminders, assistant actions, and audio digests. The README documents the broad frontend-to-AppSync flow; sampled handlers confirm several function-to-data and integration calls. Some UI wiring and unsampled function internals are therefore represented only at the documented subsystem level.

Main entry points: [`amplify/data/resource.ts`](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/data/resource.ts) (AppSync data API), [`amplify/functions/parse-receipt/handler.ts`](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/parse-receipt/handler.ts) (Receipt OCR), [`amplify/functions/reminders-worker/handler.ts`](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/reminders-worker/handler.ts) (Scheduled reminders), [`lib/remote.ts`](https://github.com/khadimmbaye0/tontine-pilot/blob/main/lib/remote.ts) (Remote data adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_auth_ui["Sign-in UI<br/>[auth-card.tsx]"]
  node_app_ui["Group workspace<br/>[page.tsx]"]
  node_declare_ui["Declare payment<br/>[page.tsx]"]
  node_alerts_ui["Alerts and mediation<br/>[page.tsx]"]
  node_export_ui["Ledger export<br/>[page.tsx]"]
  node_assistant_ui["Tonti assistant<br/>[assistant-chat.tsx]"]
end

subgraph group_data["Identity and ledger"]
  node_auth_service["Cognito auth<br/>[resource.ts]"]
  node_remote["Remote data adapter<br/>[remote.ts]"]
  node_api["AppSync data API<br/>[resource.ts]"]
  node_ledger[("Group ledger<br/>[resource.ts]")]
  node_receipt_store[("Receipt and audio storage<br/>[resource.ts]")]
end

subgraph group_workflows["Tontine workflows"]
  node_parse_declaration["Declaration parsing<br/>[handler.ts]"]
  node_parse_receipt["Receipt OCR<br/>[handler.ts]"]
  node_mediate["Empathic mediation<br/>[handler.ts]"]
  node_rotation["Rotation recommendation<br/>[handler.ts]"]
  node_digest["Audio digest<br/>[handler.ts]"]
  node_assistant["Assistant actions<br/>[handler.ts]"]
  node_reminders["Scheduled reminders<br/>[handler.ts]"]
  node_welcome["Group welcome notices<br/>[handler.ts]"]
end

subgraph group_integrations["AI and messaging"]
  node_bedrock{{"Bedrock models"}}
  node_textract{{"Textract OCR"}}
  node_polly{{"Polly speech"}}
  node_email_sms{{"SES and SNS"}}
  node_scheduler["EventBridge Scheduler"]
end

node_member(("Group member"))

node_member -->|"signs in"| node_auth_ui
node_auth_ui -->|"authenticates"| node_auth_service
node_member -->|"uses"| node_app_ui
node_app_ui -->|"requests data"| node_remote
node_declare_ui -->|"submits payment"| node_remote
node_alerts_ui -->|"manages alerts"| node_remote
node_export_ui -->|"requests ledger"| node_remote
node_assistant_ui -->|"asks assistant"| node_api
node_remote -->|"queries and mutates"| node_api
node_api -->|"reads and writes"| node_ledger
node_api -->|"dispatches"| node_parse_declaration
node_api -->|"dispatches"| node_parse_receipt
node_api -->|"dispatches"| node_mediate
node_api -->|"dispatches"| node_rotation
node_api -->|"dispatches"| node_digest
node_api -->|"dispatches"| node_assistant
node_api -->|"dispatches"| node_reminders
node_api -->|"dispatches"| node_welcome
node_parse_declaration -->|"reads context"| node_ledger
node_parse_declaration -->|"extracts details"| node_bedrock
node_parse_receipt -->|"reads group context"| node_ledger
node_parse_receipt -->|"reads receipt"| node_receipt_store
node_parse_receipt -.->|"parses image"| node_bedrock
node_parse_receipt -->|"extracts text"| node_textract
node_mediate -->|"reads alert context"| node_ledger
node_mediate -.->|"drafts proposal"| node_bedrock
node_rotation -->|"reads member history"| node_ledger
node_rotation -.->|"writes reasons"| node_bedrock
node_digest -->|"reads cycle data"| node_ledger
node_digest -.->|"synthesizes speech"| node_polly
node_digest -.->|"stores audio"| node_receipt_store
node_assistant -->|"reads and updates"| node_ledger
node_assistant -->|"answers and routes tools"| node_bedrock
node_assistant -.->|"sends email"| node_email_sms
node_reminders -->|"reads and updates alerts"| node_ledger
node_reminders -.->|"drafts reminder"| node_bedrock
node_reminders -->|"sends reminders"| node_email_sms
node_scheduler -->|"triggers"| node_reminders
node_welcome -->|"reads group members"| node_ledger
node_welcome -->|"sends welcome email"| node_email_sms

click node_auth_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/components/auth/auth-card.tsx"
click node_app_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/dashboard/page.tsx"
click node_declare_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/declare/page.tsx"
click node_alerts_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/alerts/page.tsx"
click node_export_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/export/page.tsx"
click node_assistant_ui "https://github.com/khadimmbaye0/tontine-pilot/blob/main/components/app/assistant-chat.tsx"
click node_auth_service "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/auth/resource.ts"
click node_remote "https://github.com/khadimmbaye0/tontine-pilot/blob/main/lib/remote.ts"
click node_api "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/data/resource.ts"
click node_ledger "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/data/resource.ts"
click node_receipt_store "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/storage/resource.ts"
click node_parse_declaration "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/parse-declaration/handler.ts"
click node_parse_receipt "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/parse-receipt/handler.ts"
click node_mediate "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/mediate/handler.ts"
click node_rotation "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/recommend-rotation/handler.ts"
click node_digest "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/digest-audio/handler.ts"
click node_assistant "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/assistant/handler.ts"
click node_reminders "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/reminders-worker/handler.ts"
click node_welcome "https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/notify/handler.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_auth_ui,node_app_ui,node_declare_ui,node_alerts_ui,node_export_ui,node_assistant_ui toneBlue
class node_auth_service,node_remote,node_api,node_ledger,node_receipt_store toneAmber
class node_parse_declaration,node_parse_receipt,node_mediate,node_rotation,node_digest,node_assistant,node_reminders,node_welcome toneMint
class node_bedrock,node_textract,node_polly,node_email_sms,node_scheduler toneRose
class node_member toneIndigo
```

## Components

### Web experience

- [Sign-in UI](https://github.com/khadimmbaye0/tontine-pilot/blob/main/components/auth/auth-card.tsx): `components/auth/auth-card.tsx`
- [Group workspace](https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/dashboard/page.tsx): `app/(app)/dashboard/page.tsx`
- [Declare payment](https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/declare/page.tsx): `app/(app)/declare/page.tsx`
- [Alerts and mediation](https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/alerts/page.tsx): `app/(app)/alerts/page.tsx`
- [Ledger export](https://github.com/khadimmbaye0/tontine-pilot/blob/main/app/(app)/export/page.tsx): `app/(app)/export/page.tsx`
- [Tonti assistant](https://github.com/khadimmbaye0/tontine-pilot/blob/main/components/app/assistant-chat.tsx): `components/app/assistant-chat.tsx`

### Identity and ledger

- [Cognito auth](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/auth/resource.ts): `amplify/auth/resource.ts`
- [Remote data adapter](https://github.com/khadimmbaye0/tontine-pilot/blob/main/lib/remote.ts): `lib/remote.ts`
- [AppSync data API](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/data/resource.ts): `amplify/data/resource.ts`
- [Group ledger](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/data/resource.ts): `amplify/data/resource.ts`
- [Receipt and audio storage](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/storage/resource.ts): `amplify/storage/resource.ts`

### Tontine workflows

- [Declaration parsing](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/parse-declaration/handler.ts): `amplify/functions/parse-declaration/handler.ts`
- [Receipt OCR](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/parse-receipt/handler.ts): `amplify/functions/parse-receipt/handler.ts`
- [Empathic mediation](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/mediate/handler.ts): `amplify/functions/mediate/handler.ts`
- [Rotation recommendation](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/recommend-rotation/handler.ts): `amplify/functions/recommend-rotation/handler.ts`
- [Audio digest](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/digest-audio/handler.ts): `amplify/functions/digest-audio/handler.ts`
- [Assistant actions](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/assistant/handler.ts): `amplify/functions/assistant/handler.ts`
- [Scheduled reminders](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/reminders-worker/handler.ts): `amplify/functions/reminders-worker/handler.ts`
- [Group welcome notices](https://github.com/khadimmbaye0/tontine-pilot/blob/main/amplify/functions/notify/handler.ts): `amplify/functions/notify/handler.ts`

### AI and messaging

- **Bedrock models**
- **Textract OCR**
- **Polly speech**
- **SES and SNS**
- **EventBridge Scheduler**

### Other components

- **Group member**

## Connections

- Group member → Sign-in UI: signs in
- Sign-in UI → Cognito auth: authenticates
- Group member → Group workspace: uses
- Group workspace → Remote data adapter: requests data
- Declare payment → Remote data adapter: submits payment
- Alerts and mediation → Remote data adapter: manages alerts
- Ledger export → Remote data adapter: requests ledger
- Tonti assistant → AppSync data API: asks assistant
- Remote data adapter → AppSync data API: queries and mutates
- AppSync data API → Group ledger: reads and writes
- AppSync data API → Declaration parsing: dispatches
- AppSync data API → Receipt OCR: dispatches
- AppSync data API → Empathic mediation: dispatches
- AppSync data API → Rotation recommendation: dispatches
- AppSync data API → Audio digest: dispatches
- AppSync data API → Assistant actions: dispatches
- AppSync data API → Scheduled reminders: dispatches
- AppSync data API → Group welcome notices: dispatches
- Declaration parsing → Group ledger: reads context
- Declaration parsing → Bedrock models: extracts details
- Receipt OCR → Group ledger: reads group context
- Receipt OCR → Receipt and audio storage: reads receipt
- Receipt OCR → Bedrock models: parses image
- Receipt OCR → Textract OCR: extracts text
- Empathic mediation → Group ledger: reads alert context
- Empathic mediation → Bedrock models: drafts proposal
- Rotation recommendation → Group ledger: reads member history
- Rotation recommendation → Bedrock models: writes reasons
- Audio digest → Group ledger: reads cycle data
- Audio digest → Polly speech: synthesizes speech
- Audio digest → Receipt and audio storage: stores audio
- Assistant actions → Group ledger: reads and updates
- Assistant actions → Bedrock models: answers and routes tools
- Assistant actions → SES and SNS: sends email
- Scheduled reminders → Group ledger: reads and updates alerts
- Scheduled reminders → Bedrock models: drafts reminder
- Scheduled reminders → SES and SNS: sends reminders
- EventBridge Scheduler → Scheduled reminders: triggers
- Group welcome notices → Group ledger: reads group members
- Group welcome notices → SES and SNS: sends welcome email