# alphacodeke/alphacode-shop architecture

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

- Interactive diagram: https://gitdiagram.com/alphacodeke/alphacode-shop
- Repository: https://github.com/alphacodeke/alphacode-shop

## Overview

Alphacode Shop is a Django M-Pesa STK Push payment application. A customer uses the payment page to submit a phone number and amount; the server validates the request, records a pending transaction, and requests an STK push from Safaricom. Safaricom later posts a callback, which updates the transaction record; the page can display transaction status and history. The README also describes automatic status updates and sandbox/production support. The graph follows the sampled routes and source calls; UI behavior beyond the excerpts is represented only where documented.

Main entry points: [`mpesa_app/mpesa_api.py`](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/mpesa_api.py) (STK and query API), [`mpesa_app/views.py`](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/views.py) (Payment and callback views), [`mpesa_app/templates/mpesa_app/index.html`](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/templates/mpesa_app/index.html) (Payment page), [`mpesa_app/urls.py`](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/urls.py) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Payment interface"]
  node_payment_page["Payment page<br/>[index.html]"]
end

subgraph group_app["Django payment app"]
  node_routes["App routes<br/>[urls.py]"]
  node_payment_views["Payment and callback views<br/>[views.py]"]
  node_status_views["Status and history views<br/>[views.py]"]
  node_configuration["Django and M-Pesa settings<br/>[settings.py]"]
end

subgraph group_mpesa["M-Pesa integration"]
  node_mpesa_api["STK and query API<br/>[mpesa_api.py]"]
  node_credentials["Credentials and token"]
end

subgraph group_state["Transaction state"]
  node_transaction_model["Transaction model<br/>[models.py]"]
  node_transaction_store[("SQLite transaction store<br/>[settings.py]")]
end

node_customer(("Customer"))
node_safaricom{{"Safaricom Daraja"}}

node_customer -->|"uses"| node_payment_page
node_payment_page -->|"submits requests"| node_routes
node_routes -->|"routes payment and callback"| node_payment_views
node_routes -->|"routes status and history"| node_status_views
node_payment_views -->|"creates and updates"| node_transaction_model
node_payment_views -->|"initiates STK push"| node_mpesa_api
node_status_views -->|"reads status and history"| node_transaction_model
node_transaction_model -->|"persists records"| node_transaction_store
node_mpesa_api -->|"gets token and password"| node_credentials
node_mpesa_api -->|"reads configuration"| node_configuration
node_mpesa_api -->|"sends API requests"| node_safaricom
node_safaricom -->|"posts payment callback"| node_payment_views
node_payment_page -->|"refreshes transaction status"| node_status_views

click node_payment_page "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/templates/mpesa_app/index.html"
click node_routes "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/urls.py"
click node_payment_views "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/views.py"
click node_status_views "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/views.py"
click node_transaction_model "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/models.py"
click node_transaction_store "https://github.com/alphacodeke/alphacode-shop/blob/main/alphacode_shop/settings.py"
click node_mpesa_api "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/mpesa_api.py"
click node_credentials "https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/mpesa_credentials.py"
click node_configuration "https://github.com/alphacodeke/alphacode-shop/blob/main/alphacode_shop/settings.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_payment_page toneBlue
class node_routes,node_payment_views,node_status_views,node_configuration toneAmber
class node_mpesa_api,node_credentials toneMint
class node_transaction_model,node_transaction_store toneRose
class node_customer,node_safaricom toneIndigo
```

## Components

### Payment interface

- [Payment page](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/templates/mpesa_app/index.html): `mpesa_app/templates/mpesa_app/index.html`

### Django payment app

- [App routes](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/urls.py): `mpesa_app/urls.py`
- [Payment and callback views](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/views.py): `mpesa_app/views.py`
- [Status and history views](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/views.py): `mpesa_app/views.py`
- [Django and M-Pesa settings](https://github.com/alphacodeke/alphacode-shop/blob/main/alphacode_shop/settings.py): `alphacode_shop/settings.py`

### M-Pesa integration

- [STK and query API](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/mpesa_api.py): `mpesa_app/mpesa_api.py`
- [Credentials and token](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/mpesa_credentials.py): `mpesa_app/mpesa_credentials.py`

### Transaction state

- [Transaction model](https://github.com/alphacodeke/alphacode-shop/blob/main/mpesa_app/models.py): `mpesa_app/models.py`
- [SQLite transaction store](https://github.com/alphacodeke/alphacode-shop/blob/main/alphacode_shop/settings.py): `alphacode_shop/settings.py`

### Other components

- **Customer**
- **Safaricom Daraja**

## Connections

- Customer → Payment page: uses (evidence: `readme.md`)
- Payment page → App routes: submits requests (evidence: `readme.md`)
- App routes → Payment and callback views: routes payment and callback (evidence: `mpesa_app/urls.py`)
- App routes → Status and history views: routes status and history (evidence: `mpesa_app/urls.py`)
- Payment and callback views → Transaction model: creates and updates (evidence: `mpesa_app/views.py`)
- Payment and callback views → STK and query API: initiates STK push (evidence: `mpesa_app/views.py`)
- Status and history views → Transaction model: reads status and history (evidence: `mpesa_app/views.py`)
- Transaction model → SQLite transaction store: persists records (evidence: `alphacode_shop/settings.py`)
- STK and query API → Credentials and token: gets token and password (evidence: `mpesa_app/mpesa_api.py`)
- STK and query API → Django and M-Pesa settings: reads configuration (evidence: `mpesa_app/mpesa_api.py`)
- STK and query API → Safaricom Daraja: sends API requests (evidence: `mpesa_app/mpesa_api.py`)
- Safaricom Daraja → Payment and callback views: posts payment callback (evidence: `readme.md`)
- Payment page → Status and history views: refreshes transaction status (evidence: `readme.md`)
