# njogubless/changa architecture

> Architecture diagram of the GitHub repository njogubless/changa, 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/njogubless/changa
- Repository: https://github.com/njogubless/changa

## Overview

Changa is a group-contribution platform: members use the mobile app to sign in, discover or create projects, and contribute money toward shared goals. The FastAPI application exposes authentication, project, group, budget, and payment routes. Payment initiation and reconciliation run through a background worker; confirmed contributions are credited to an append-only ledger that maintains project funding totals. The README documents Flutter capabilities, but the supplied tree omits its Dart source, so mobile feature internals and their detailed API wiring cannot be shown. Backend router details beyond sampled files are likewise represented only at the documented capability level.

Main entry points: [`backend/app/main.py`](https://github.com/njogubless/changa/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database.py`](https://github.com/njogubless/changa/blob/main/backend/app/database.py) (Database sessions), [`backend/app/workers/payment_worker.py`](https://github.com/njogubless/changa/blob/main/backend/app/workers/payment_worker.py) (Payment worker), [`backend/app/routers/auth.py`](https://github.com/njogubless/changa/blob/main/backend/app/routers/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobile["Changa app"]
end

subgraph group_api["API capabilities"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_auth_schemas["Auth validation<br/>[auth.py]"]
  node_projects["Project management<br/>[projects.py]"]
  node_chamas["Group management<br/>[chamas.py]"]
  node_budgets["Budgeting<br/>[budgets.py]"]
  node_payments_api["Contribution endpoints<br/>[payments.py]"]
end

subgraph group_payments["Payment processing"]
  node_payment_worker["Payment worker<br/>[payment_worker.py]"]
  node_mpesa["M-Pesa integration<br/>[mpesa.py]"]
  node_airtel["Airtel integration<br/>[airtel.py]"]
  node_ledger["Contribution ledger<br/>[ledger_service.py]"]
end

subgraph group_data["Persistence and controls"]
  node_database_access["Database sessions<br/>[database.py]"]
  node_domain_models["Domain records<br/>[models.py]"]
  node_compliance["Consent and KYC<br/>[compliance.py]"]
  node_audit["Audit events<br/>[audit.py]"]
  node_audit_hooks["Audit hooks<br/>[audit.py]"]
end

node_member(("Group member"))
node_payment_networks["Payment providers"]
node_postgres[("PostgreSQL")]

node_member -->|"uses"| node_mobile
node_mobile -->|"sends requests"| node_api_app
node_api_app -->|"mounts routes"| node_auth
node_api_app -->|"mounts routes"| node_projects
node_api_app -->|"mounts routes"| node_chamas
node_api_app -->|"mounts routes"| node_budgets
node_api_app -->|"mounts routes"| node_payments_api
node_api_app -->|"starts worker"| node_payment_worker
node_auth -->|"validates with"| node_auth_schemas
node_auth -->|"uses sessions"| node_database_access
node_auth -->|"records consent"| node_compliance
node_api_app -->|"checks readiness"| node_database_access
node_database_access -->|"connects to"| node_postgres
node_payment_worker -->|"reads and writes"| node_database_access
node_payment_worker -->|"initiates or queries"| node_mpesa
node_payment_worker -->|"initiates or queries"| node_airtel
node_mpesa -.->|"calls provider"| node_payment_networks
node_airtel -.->|"calls provider"| node_payment_networks
node_payment_worker -->|"credits success"| node_ledger
node_ledger -->|"writes ledger and totals"| node_database_access
node_database_access -->|"persists records"| node_domain_models
node_api_app -->|"loads hooks"| node_audit_hooks
node_audit_hooks -->|"populates events"| node_audit
node_database_access -->|"stores events"| node_audit

click node_mobile "https://github.com/njogubless/changa/tree/main/mobile/changa"
click node_api_app "https://github.com/njogubless/changa/blob/main/backend/app/main.py"
click node_auth "https://github.com/njogubless/changa/blob/main/backend/app/routers/auth.py"
click node_auth_schemas "https://github.com/njogubless/changa/blob/main/backend/app/schemas/auth.py"
click node_projects "https://github.com/njogubless/changa/blob/main/backend/app/routers/projects.py"
click node_chamas "https://github.com/njogubless/changa/blob/main/backend/app/routers/chamas.py"
click node_budgets "https://github.com/njogubless/changa/blob/main/backend/app/routers/budgets.py"
click node_payments_api "https://github.com/njogubless/changa/blob/main/backend/app/routers/payments.py"
click node_payment_worker "https://github.com/njogubless/changa/blob/main/backend/app/workers/payment_worker.py"
click node_mpesa "https://github.com/njogubless/changa/blob/main/backend/app/services/mpesa.py"
click node_airtel "https://github.com/njogubless/changa/blob/main/backend/app/services/airtel.py"
click node_ledger "https://github.com/njogubless/changa/blob/main/backend/app/services/ledger_service.py"
click node_database_access "https://github.com/njogubless/changa/blob/main/backend/app/database.py"
click node_domain_models "https://github.com/njogubless/changa/blob/main/backend/app/models/models.py"
click node_compliance "https://github.com/njogubless/changa/blob/main/backend/app/models/compliance.py"
click node_audit "https://github.com/njogubless/changa/blob/main/backend/app/models/audit.py"
click node_audit_hooks "https://github.com/njogubless/changa/blob/main/backend/app/core/audit.py"

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_mobile toneBlue
class node_api_app,node_auth,node_auth_schemas,node_projects,node_chamas,node_budgets,node_payments_api,node_postgres toneAmber
class node_payment_worker,node_mpesa,node_airtel,node_ledger toneMint
class node_database_access,node_domain_models,node_compliance,node_audit,node_audit_hooks toneRose
class node_member,node_payment_networks toneIndigo
```

## Components

### Mobile client

- [Changa app](https://github.com/njogubless/changa/tree/main/mobile/changa): `mobile/changa`

### API capabilities

- [FastAPI application](https://github.com/njogubless/changa/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/njogubless/changa/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Auth validation](https://github.com/njogubless/changa/blob/main/backend/app/schemas/auth.py): `backend/app/schemas/auth.py`
- [Project management](https://github.com/njogubless/changa/blob/main/backend/app/routers/projects.py): `backend/app/routers/projects.py`
- [Group management](https://github.com/njogubless/changa/blob/main/backend/app/routers/chamas.py): `backend/app/routers/chamas.py`
- [Budgeting](https://github.com/njogubless/changa/blob/main/backend/app/routers/budgets.py): `backend/app/routers/budgets.py`
- [Contribution endpoints](https://github.com/njogubless/changa/blob/main/backend/app/routers/payments.py): `backend/app/routers/payments.py`

### Payment processing

- [Payment worker](https://github.com/njogubless/changa/blob/main/backend/app/workers/payment_worker.py): `backend/app/workers/payment_worker.py`
- [M-Pesa integration](https://github.com/njogubless/changa/blob/main/backend/app/services/mpesa.py): `backend/app/services/mpesa.py`
- [Airtel integration](https://github.com/njogubless/changa/blob/main/backend/app/services/airtel.py): `backend/app/services/airtel.py`
- [Contribution ledger](https://github.com/njogubless/changa/blob/main/backend/app/services/ledger_service.py): `backend/app/services/ledger_service.py`

### Persistence and controls

- [Database sessions](https://github.com/njogubless/changa/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain records](https://github.com/njogubless/changa/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Consent and KYC](https://github.com/njogubless/changa/blob/main/backend/app/models/compliance.py): `backend/app/models/compliance.py`
- [Audit events](https://github.com/njogubless/changa/blob/main/backend/app/models/audit.py): `backend/app/models/audit.py`
- [Audit hooks](https://github.com/njogubless/changa/blob/main/backend/app/core/audit.py): `backend/app/core/audit.py`

### Other components

- **Group member**
- **Payment providers**
- **PostgreSQL**

## Connections

- Group member → Changa app: uses
- Changa app → FastAPI application: sends requests
- FastAPI application → Authentication: mounts routes
- FastAPI application → Project management: mounts routes
- FastAPI application → Group management: mounts routes
- FastAPI application → Budgeting: mounts routes
- FastAPI application → Contribution endpoints: mounts routes
- FastAPI application → Payment worker: starts worker
- Authentication → Auth validation: validates with
- Authentication → Database sessions: uses sessions
- Authentication → Consent and KYC: records consent
- FastAPI application → Database sessions: checks readiness
- Database sessions → PostgreSQL: connects to
- Payment worker → Database sessions: reads and writes
- Payment worker → M-Pesa integration: initiates or queries
- Payment worker → Airtel integration: initiates or queries
- M-Pesa integration → Payment providers: calls provider
- Airtel integration → Payment providers: calls provider
- Payment worker → Contribution ledger: credits success
- Contribution ledger → Database sessions: writes ledger and totals
- Database sessions → Domain records: persists records
- FastAPI application → Audit hooks: loads hooks
- Audit hooks → Audit events: populates events
- Database sessions → Audit events: stores events