# lethabomohapi/stockvelsync_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/lethabomohapi/stockvelsync_v2
- Repository: https://github.com/lethabomohapi/stockvelsync_v2

## Overview

StokvelSync is an ASP.NET Core stokvel savings-group application with a JavaScript browser client and MySQL persistence. Members and treasurers sign in, manage groups, record contributions, review claims, and view a confirmed ledger; the product also supports rotation schedules, offline contribution capture and later synchronization, payments, and SMS commands/reminders. The graph includes documented capabilities whose controller internals were not sampled. Some integration wiring and unsampled routes are therefore shown only where the README documents them; uncertain links are omitted or dashed.

Main entry points: [`src/StokvelSync.Web/wwwroot/js/app.js`](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/app.js) (StokvelSync UI), [`src/StokvelSync.Web/Core/StokvelService.cs`](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/StokvelService.cs) (Group and account rules), [`src/StokvelSync.Web/Controllers/GroupsController.cs`](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs) (Group and member APIs), [`src/StokvelSync.Web/Core/Providers.cs`](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Providers.cs) (Payment and SMS providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_browser["StokvelSync UI<br/>[app.js]"]
  node_browserdata["Offline data and sync<br/>[data.js]"]
  node_translations["Translations<br/>[i18n.js]"]
  node_serviceworker["Offline app shell<br/>[sw.js]"]
end

subgraph group_workflows["Accounts and groups"]
  node_auth["Registration and sessions<br/>[AuthController.cs]"]
  node_groups["Group and member APIs"]
  node_groupdomain["Group and account rules<br/>[StokvelService.cs]"]
end

subgraph group_finance["Contributions and payouts"]
  node_contributions["Contribution review"]
  node_ledger["Confirmed ledger and export<br/>[Controllers]"]
  node_rotations["Rotation schedule and payouts<br/>[Controllers]"]
end

subgraph group_communications["Payments and messaging"]
  node_paymentflow["Payment intents"]
  node_webhooks["Payment and SMS webhooks"]
  node_providers["Payment and SMS providers<br/>[Providers.cs]"]
  node_smscommands["SMS commands and reminders"]
  node_smsworker["Outbound SMS worker<br/>[Providers.cs]"]
end

subgraph group_platform["Application platform"]
  node_api["ASP.NET request pipeline<br/>[ApiMiddleware.cs]"]
  node_rules["Validation and domain rules<br/>[Domain.cs]"]
  node_db[("MySQL persistence<br/>[Db.cs]")]
  node_demo["Sample data seeding<br/>[DemoSeed.cs]"]
end

node_member(("Member / treasurer"))
node_payfast{{"Payfast"}}
node_twilio{{"Twilio SMS"}}
node_mysql[("MySQL server")]

node_member -->|"uses"| node_browser
node_browser -->|"uses"| node_browserdata
node_browser -->|"renders text with"| node_translations
node_browserdata -->|"requests"| node_api
node_serviceworker -.->|"serves offline shell"| node_browser
node_api -->|"routes requests to"| node_auth
node_api -->|"routes requests to"| node_groups
node_auth -->|"loads user groups"| node_groupdomain
node_groups -->|"delegates group operations"| node_groupdomain
node_groups -->|"reads and writes"| node_db
node_groups -->|"validates input with"| node_rules
node_contributions -->|"uses mutations"| node_groupdomain
node_ledger -.->|"exports CSV for"| node_browser
node_rotations -.->|"provides schedules to"| node_browser
node_paymentflow -.->|"creates checkout with"| node_providers
node_webhooks -->|"completes payments and commands"| node_groupdomain
node_webhooks -.->|"validates provider notifications with"| node_providers
node_smscommands -->|"dispatches commands to"| node_groupdomain
node_providers -->|"validates checkout notifications"| node_payfast
node_providers -.->|"sends messages through"| node_twilio
node_smsworker -.->|"sends queued messages"| node_twilio
node_demo -->|"seeds sample records"| node_db
node_db -->|"persists data in"| node_mysql

click node_browser "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/app.js"
click node_browserdata "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/data.js"
click node_translations "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/i18n.js"
click node_serviceworker "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/sw.js"
click node_auth "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/AuthController.cs"
click node_groups "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs"
click node_groupdomain "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/StokvelService.cs"
click node_contributions "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs"
click node_ledger "https://github.com/lethabomohapi/stockvelsync_v2/tree/master/src/StokvelSync.Web/Controllers"
click node_rotations "https://github.com/lethabomohapi/stockvelsync_v2/tree/master/src/StokvelSync.Web/Controllers"
click node_paymentflow "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs"
click node_webhooks "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/WebhooksController.cs"
click node_providers "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Providers.cs"
click node_smscommands "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/WebhooksController.cs"
click node_smsworker "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Providers.cs"
click node_api "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/ApiMiddleware.cs"
click node_rules "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Domain.cs"
click node_db "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Db.cs"
click node_demo "https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/DemoSeed.cs"

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_browser,node_browserdata,node_translations,node_serviceworker toneBlue
class node_auth,node_groups,node_groupdomain,node_mysql toneAmber
class node_contributions,node_ledger,node_rotations toneMint
class node_paymentflow,node_webhooks,node_providers,node_smscommands,node_smsworker toneRose
class node_api,node_rules,node_db,node_demo,node_member,node_payfast,node_twilio toneIndigo
```

## Components

### Browser client

- [StokvelSync UI](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/app.js): `src/StokvelSync.Web/wwwroot/js/app.js`
- [Offline data and sync](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/data.js): `src/StokvelSync.Web/wwwroot/js/data.js`
- [Translations](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/js/i18n.js): `src/StokvelSync.Web/wwwroot/js/i18n.js`
- [Offline app shell](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/wwwroot/sw.js): `src/StokvelSync.Web/wwwroot/sw.js`

### Accounts and groups

- [Registration and sessions](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/AuthController.cs): `src/StokvelSync.Web/Controllers/AuthController.cs`
- [Group and member APIs](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs): `src/StokvelSync.Web/Controllers/GroupsController.cs`
- [Group and account rules](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/StokvelService.cs): `src/StokvelSync.Web/Core/StokvelService.cs`

### Contributions and payouts

- [Contribution review](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs): `src/StokvelSync.Web/Controllers/GroupsController.cs`
- [Confirmed ledger and export](https://github.com/lethabomohapi/stockvelsync_v2/tree/master/src/StokvelSync.Web/Controllers): `src/StokvelSync.Web/Controllers`
- [Rotation schedule and payouts](https://github.com/lethabomohapi/stockvelsync_v2/tree/master/src/StokvelSync.Web/Controllers): `src/StokvelSync.Web/Controllers`

### Payments and messaging

- [Payment intents](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/GroupsController.cs): `src/StokvelSync.Web/Controllers/GroupsController.cs`
- [Payment and SMS webhooks](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/WebhooksController.cs): `src/StokvelSync.Web/Controllers/WebhooksController.cs`
- [Payment and SMS providers](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Providers.cs): `src/StokvelSync.Web/Core/Providers.cs`
- [SMS commands and reminders](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Controllers/WebhooksController.cs): `src/StokvelSync.Web/Controllers/WebhooksController.cs`
- [Outbound SMS worker](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Providers.cs): `src/StokvelSync.Web/Core/Providers.cs`

### Application platform

- [ASP.NET request pipeline](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/ApiMiddleware.cs): `src/StokvelSync.Web/Core/ApiMiddleware.cs`
- [Validation and domain rules](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Domain.cs): `src/StokvelSync.Web/Core/Domain.cs`
- [MySQL persistence](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/Db.cs): `src/StokvelSync.Web/Core/Db.cs`
- [Sample data seeding](https://github.com/lethabomohapi/stockvelsync_v2/blob/master/src/StokvelSync.Web/Core/DemoSeed.cs): `src/StokvelSync.Web/Core/DemoSeed.cs`

### Other components

- **Member / treasurer**
- **Payfast**
- **Twilio SMS**
- **MySQL server**

## Connections

- Member / treasurer → StokvelSync UI: uses (evidence: `README.md`)
- StokvelSync UI → Offline data and sync: uses (evidence: `src/StokvelSync.Web/wwwroot/js/app.js`)
- StokvelSync UI → Translations: renders text with (evidence: `src/StokvelSync.Web/wwwroot/js/app.js`)
- Offline data and sync → ASP.NET request pipeline: requests (evidence: `src/StokvelSync.Web/wwwroot/js/data.js`)
- Offline app shell → StokvelSync UI: serves offline shell (evidence: `README.md`)
- ASP.NET request pipeline → Registration and sessions: routes requests to
- ASP.NET request pipeline → Group and member APIs: routes requests to
- Registration and sessions → Group and account rules: loads user groups (evidence: `src/StokvelSync.Web/Controllers/AuthController.cs`)
- Group and member APIs → Group and account rules: delegates group operations (evidence: `src/StokvelSync.Web/Controllers/GroupsController.cs`)
- Group and member APIs → MySQL persistence: reads and writes (evidence: `src/StokvelSync.Web/Controllers/GroupsController.cs`)
- Group and member APIs → Validation and domain rules: validates input with (evidence: `src/StokvelSync.Web/Controllers/GroupsController.cs`)
- Contribution review → Group and account rules: uses mutations (evidence: `src/StokvelSync.Web/Controllers/GroupsController.cs`)
- Confirmed ledger and export → StokvelSync UI: exports CSV for (evidence: `README.md`)
- Rotation schedule and payouts → StokvelSync UI: provides schedules to (evidence: `README.md`)
- Payment intents → Payment and SMS providers: creates checkout with (evidence: `src/StokvelSync.Web/Controllers/GroupsController.cs`)
- Payment and SMS webhooks → Group and account rules: completes payments and commands (evidence: `src/StokvelSync.Web/Controllers/WebhooksController.cs`)
- Payment and SMS webhooks → Payment and SMS providers: validates provider notifications with (evidence: `src/StokvelSync.Web/Controllers/WebhooksController.cs`)
- SMS commands and reminders → Group and account rules: dispatches commands to (evidence: `src/StokvelSync.Web/Controllers/WebhooksController.cs`)
- Payment and SMS providers → Payfast: validates checkout notifications (evidence: `src/StokvelSync.Web/Core/Providers.cs`)
- Payment and SMS providers → Twilio SMS: sends messages through (evidence: `README.md`)
- Outbound SMS worker → Twilio SMS: sends queued messages (evidence: `README.md`)
- Sample data seeding → MySQL persistence: seeds sample records (evidence: `src/StokvelSync.Web/Core/DemoSeed.cs`)
- MySQL persistence → MySQL server: persists data in (evidence: `README.md`)
