# alkama2022/debt-collector-backend architecture

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

- Interactive diagram: https://gitdiagram.com/alkama2022/debt-collector-backend
- Repository: https://github.com/alkama2022/debt-collector-backend

## Overview

CollectNaija is a multi-tenant debt-collection and payment-management API. The primary workflow is an organization user managing customers and invoices, then scheduling reminders that are sent through configured communication channels; payments and provider webhooks update collection state. The graph also preserves the documented AI, language, voice, billing, reporting, and audit capabilities. Several domain links are described by the README, while source excerpts substantiate reminder scheduling, communication dispatch, webhook processing, and language routing; unsampled implementation details are not assumed.

Main entry points: [`config/urls.py`](https://github.com/alkama2022/debt-collector-backend/blob/main/config/urls.py) (REST API), [`apps/ai/views.py`](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/ai/views.py) (AI Collection Support), [`apps/invoices/models.py`](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/invoices/models.py) (Invoices), [`apps/collections/tasks.py`](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/collections/tasks.py) (Reminder Scheduling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Tenancy"]
  node_api["REST API<br/>[urls.py]"]
  node_accounts["Accounts<br/>[views.py]"]
  node_tenancy[("Organizations<br/>[models.py]")]
end

subgraph group_debt["Debt Management"]
  node_customers[("Customers<br/>[models.py]")]
  node_invoices[("Invoices<br/>[models.py]")]
  node_collections["Reminder Scheduling<br/>[tasks.py]"]
end

subgraph group_messaging["Collection Communications"]
  node_commsdata[("Communication Records<br/>[models.py]")]
  node_dispatch["Message Dispatch<br/>[tasks.py]"]
  node_providers["Channel Providers<br/>[factory.py]"]
  node_voice["Voice Communication<br/>[views.py]"]
  node_language["Language Routing<br/>[router.py]"]
end

subgraph group_payments["Payments and Billing"]
  node_payments["Payment Processing<br/>[views.py]"]
  node_paystack["Paystack Integration<br/>[paystack.py]"]
  node_webhooks["Webhook Processing<br/>[tasks.py]"]
  node_subscriptions[("Subscriptions<br/>[models.py]")]
  node_reports["Reporting"]
end

subgraph group_intelligence["AI and Oversight"]
  node_ai["AI Collection Support<br/>[views.py]"]
  node_audit[("Audit Records<br/>[models.py]")]
  node_celery["Background Tasks<br/>[celery.py]"]
end

node_client(("Business Client"))

node_client -->|"uses REST API"| node_api
node_api -->|"supports authentication"| node_accounts
node_api -->|"serves organizations"| node_tenancy
node_tenancy -->|"scopes customer data"| node_customers
node_tenancy -->|"scopes invoice data"| node_invoices
node_client -->|"manages customers"| node_customers
node_client -->|"manages invoices"| node_invoices
node_collections -->|"selects due invoices"| node_invoices
node_collections -->|"queues reminders"| node_commsdata
node_collections -->|"runs scheduled"| node_celery
node_dispatch -->|"loads queued events"| node_commsdata
node_dispatch -->|"sends through provider"| node_providers
node_dispatch -.->|"resolves message language"| node_language
node_providers -.->|"delivers messages"| node_client
node_client -->|"uses voice channel"| node_voice
node_api -->|"records payments"| node_payments
node_payments -.->|"integrates payments"| node_paystack
node_webhooks -->|"records successful charges"| node_payments
node_webhooks -->|"resolves invoice"| node_invoices
node_webhooks -->|"queues AI replies"| node_commsdata
node_api -->|"manages billing"| node_subscriptions
node_api -->|"provides analytics"| node_reports
node_ai -->|"detects language"| node_language
node_ai -->|"looks up customer"| node_customers
node_ai -.->|"records communications"| node_audit
node_api -->|"supports AI workflows"| node_ai

click node_api "https://github.com/alkama2022/debt-collector-backend/blob/main/config/urls.py"
click node_accounts "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/accounts/views.py"
click node_tenancy "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/tenancy/models.py"
click node_customers "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/customers/models.py"
click node_invoices "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/invoices/models.py"
click node_collections "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/collections/tasks.py"
click node_commsdata "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/models.py"
click node_dispatch "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/tasks.py"
click node_providers "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/providers/factory.py"
click node_voice "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/voice/views.py"
click node_language "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/languages/router.py"
click node_payments "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/payments/views.py"
click node_paystack "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/payments/paystack.py"
click node_webhooks "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/webhooks/tasks.py"
click node_subscriptions "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/subscriptions/models.py"
click node_reports "https://github.com/alkama2022/debt-collector-backend/tree/main/apps/reports"
click node_ai "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/ai/views.py"
click node_audit "https://github.com/alkama2022/debt-collector-backend/blob/main/apps/audit/models.py"
click node_celery "https://github.com/alkama2022/debt-collector-backend/blob/main/config/celery.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_api,node_accounts,node_tenancy,node_client toneBlue
class node_customers,node_invoices,node_collections toneAmber
class node_commsdata,node_dispatch,node_providers,node_voice,node_language toneMint
class node_payments,node_paystack,node_webhooks,node_subscriptions,node_reports toneRose
class node_ai,node_audit,node_celery toneIndigo
```

## Components

### Access and Tenancy

- [REST API](https://github.com/alkama2022/debt-collector-backend/blob/main/config/urls.py): `config/urls.py`
- [Accounts](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/accounts/views.py): `apps/accounts/views.py`
- [Organizations](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/tenancy/models.py): `apps/tenancy/models.py`

### Debt Management

- [Customers](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/customers/models.py): `apps/customers/models.py`
- [Invoices](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/invoices/models.py): `apps/invoices/models.py`
- [Reminder Scheduling](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/collections/tasks.py): `apps/collections/tasks.py`

### Collection Communications

- [Communication Records](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/models.py): `apps/comms/models.py`
- [Message Dispatch](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/tasks.py): `apps/comms/tasks.py`
- [Channel Providers](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/comms/providers/factory.py): `apps/comms/providers/factory.py`
- [Voice Communication](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/voice/views.py): `apps/voice/views.py`
- [Language Routing](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/languages/router.py): `apps/languages/router.py`

### Payments and Billing

- [Payment Processing](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/payments/views.py): `apps/payments/views.py`
- [Paystack Integration](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/payments/paystack.py): `apps/payments/paystack.py`
- [Webhook Processing](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/webhooks/tasks.py): `apps/webhooks/tasks.py`
- [Subscriptions](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/subscriptions/models.py): `apps/subscriptions/models.py`
- [Reporting](https://github.com/alkama2022/debt-collector-backend/tree/main/apps/reports): `apps/reports`

### AI and Oversight

- [AI Collection Support](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/ai/views.py): `apps/ai/views.py`
- [Audit Records](https://github.com/alkama2022/debt-collector-backend/blob/main/apps/audit/models.py): `apps/audit/models.py`
- [Background Tasks](https://github.com/alkama2022/debt-collector-backend/blob/main/config/celery.py): `config/celery.py`

### Other components

- **Business Client**

## Connections

- Business Client → REST API: uses REST API
- REST API → Accounts: supports authentication
- REST API → Organizations: serves organizations
- Organizations → Customers: scopes customer data (evidence: `apps/customers/models.py`)
- Organizations → Invoices: scopes invoice data (evidence: `apps/invoices/models.py`)
- Business Client → Customers: manages customers
- Business Client → Invoices: manages invoices
- Reminder Scheduling → Invoices: selects due invoices (evidence: `apps/collections/tasks.py`)
- Reminder Scheduling → Communication Records: queues reminders (evidence: `apps/collections/tasks.py`)
- Reminder Scheduling → Background Tasks: runs scheduled (evidence: `apps/collections/tasks.py`)
- Message Dispatch → Communication Records: loads queued events (evidence: `apps/comms/tasks.py`)
- Message Dispatch → Channel Providers: sends through provider (evidence: `apps/comms/tasks.py`)
- Message Dispatch → Language Routing: resolves message language
- Channel Providers → Business Client: delivers messages
- Business Client → Voice Communication: uses voice channel
- REST API → Payment Processing: records payments
- Payment Processing → Paystack Integration: integrates payments
- Webhook Processing → Payment Processing: records successful charges (evidence: `apps/webhooks/tasks.py`)
- Webhook Processing → Invoices: resolves invoice (evidence: `apps/webhooks/tasks.py`)
- Webhook Processing → Communication Records: queues AI replies (evidence: `apps/webhooks/tasks.py`)
- REST API → Subscriptions: manages billing
- REST API → Reporting: provides analytics
- AI Collection Support → Language Routing: detects language (evidence: `apps/ai/views.py`)
- AI Collection Support → Customers: looks up customer (evidence: `apps/ai/views.py`)
- AI Collection Support → Audit Records: records communications (evidence: `apps/ai/views.py`)
- REST API → AI Collection Support: supports AI workflows