# toyin-elankey/application-software- architecture

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

- Interactive diagram: https://gitdiagram.com/toyin-elankey/application-software-
- Repository: https://github.com/toyin-elankey/application-software-

## Overview

This is a Next.js commerce backend with storefront pages and APIs for catalogue, carts, checkout, customer identity and orders, staff administration, Paystack payments, refunds, and scheduled payment jobs. A shopper’s checkout request is validated by the API, handled by checkout services, and connected to payment-provider selection; webhooks and return routes support payment verification. Staff routes expose operational and refund capabilities behind role checks. The README describes an earlier data-layer status and planned AI/WhatsApp capabilities; those integrations are not represented as implemented here. Arrows rely on excerpts or SOURCE INDEX references, so unsampled relationships are omitted.

Main entry points: [`src/app/api/v1/checkout/route.ts`](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/checkout/route.ts) (Checkout API), [`src/server/http/api.ts`](https://github.com/toyin-elankey/application-software-/blob/main/src/server/http/api.ts) (API plumbing), [`src/server/checkout/checkout.ts`](https://github.com/toyin-elankey/application-software-/blob/main/src/server/checkout/checkout.ts) (Checkout service), [`src/app/api/v1/admin/staff/route.ts`](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/admin/staff/route.ts) (Staff APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shopper["Shopping and checkout"]
  node_storefront["Storefront<br/>[page.tsx]"]
  node_catalogue_api["Catalogue API<br/>[route.ts]"]
  node_cart_api["Cart API<br/>[route.ts]"]
  node_cart_service["Cart service<br/>[cart.ts]"]
  node_checkout_api["Checkout API<br/>[route.ts]"]
  node_checkout_service["Checkout service<br/>[checkout.ts]"]
  node_pricing["Pricing<br/>[pricing.ts]"]
  node_delivery["Delivery quotes<br/>[quote.ts]"]
end

subgraph group_identity["Identity and administration"]
  node_customer_api["Customer APIs<br/>[route.ts]"]
  node_customer_auth["Customer authentication<br/>[auth.ts]"]
  node_sessions["Customer sessions<br/>[sessions.ts]"]
  node_order_api["Order lookup API<br/>[route.ts]"]
  node_staff_api["Staff APIs<br/>[route.ts]"]
  node_staff_guard["Staff access guard<br/>[guard.ts]"]
  node_admin_reads["Admin reads<br/>[reads.ts]"]
end

subgraph group_payments["Payments and refunds"]
  node_pay_provider["Provider selection<br/>[resolve.ts]"]
  node_paystack_webhook["Paystack webhook<br/>[webhook.ts]"]
  node_webhook_api["Webhook API<br/>[route.ts]"]
  node_payment_jobs["Payment job drain<br/>[drain.ts]"]
  node_refunds["Refund service<br/>[service.ts]"]
end

subgraph group_platform["Runtime foundations"]
  node_api_plumbing["API plumbing<br/>[api.ts]"]
  node_errors["HTTP errors<br/>[problem.ts]"]
  node_database_client["Database client<br/>[client.ts]"]
  node_database[("PostgreSQL")]
  node_tenant["Tenant scope<br/>[tenant.ts]"]
end

node_shopper(("Shopper"))

node_shopper -->|"browses"| node_storefront
node_shopper -->|"requests products"| node_catalogue_api
node_shopper -->|"updates cart"| node_cart_api
node_cart_api -->|"calls"| node_cart_service
node_cart_api -->|"uses"| node_api_plumbing
node_shopper -->|"submits checkout"| node_checkout_api
node_checkout_api -->|"calls"| node_checkout_service
node_checkout_api -->|"selects provider"| node_pay_provider
node_checkout_api -->|"uses"| node_api_plumbing
node_checkout_service -->|"uses"| node_pricing
node_checkout_service -->|"uses"| node_delivery
node_customer_api -->|"calls"| node_customer_auth
node_customer_api -->|"uses"| node_sessions
node_customer_auth -->|"opens sessions"| node_sessions
node_order_api -->|"resolves access"| node_sessions
node_staff_api -->|"checks access"| node_staff_guard
node_staff_api -->|"uses"| node_api_plumbing
node_staff_api -->|"manages staff records"| node_database
node_admin_reads -->|"scopes queries"| node_tenant
node_admin_reads -->|"reads commerce data"| node_database
node_webhook_api -->|"accepts events"| node_paystack_webhook
node_webhook_api -->|"drains jobs"| node_payment_jobs
node_paystack_webhook -->|"stores events and jobs"| node_database
node_payment_jobs -->|"dispatches refund work"| node_refunds
node_checkout_service -->|"places orders"| node_database
node_database_client -->|"connects"| node_database
node_api_plumbing -->|"gets client"| node_database_client
node_api_plumbing -->|"uses responses"| node_errors
node_checkout_api -->|"handles errors"| node_errors

click node_storefront "https://github.com/toyin-elankey/application-software-/blob/main/src/app/page.tsx"
click node_catalogue_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/catalog/products/route.ts"
click node_cart_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/cart/items/route.ts"
click node_cart_service "https://github.com/toyin-elankey/application-software-/blob/main/src/server/cart/cart.ts"
click node_checkout_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/checkout/route.ts"
click node_checkout_service "https://github.com/toyin-elankey/application-software-/blob/main/src/server/checkout/checkout.ts"
click node_pricing "https://github.com/toyin-elankey/application-software-/blob/main/src/server/pricing/pricing.ts"
click node_delivery "https://github.com/toyin-elankey/application-software-/blob/main/src/server/delivery/quote.ts"
click node_customer_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/auth/logout/route.ts"
click node_customer_auth "https://github.com/toyin-elankey/application-software-/blob/main/src/server/customers/auth.ts"
click node_sessions "https://github.com/toyin-elankey/application-software-/blob/main/src/server/customers/sessions.ts"
click node_order_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/orders/%5BorderNumber%5D/route.ts"
click node_staff_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/admin/staff/route.ts"
click node_staff_guard "https://github.com/toyin-elankey/application-software-/blob/main/src/server/auth/guard.ts"
click node_admin_reads "https://github.com/toyin-elankey/application-software-/blob/main/src/server/admin/reads.ts"
click node_pay_provider "https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/resolve.ts"
click node_paystack_webhook "https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/webhook.ts"
click node_webhook_api "https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/webhooks/paystack/route.ts"
click node_payment_jobs "https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/drain.ts"
click node_refunds "https://github.com/toyin-elankey/application-software-/blob/main/src/server/refunds/service.ts"
click node_api_plumbing "https://github.com/toyin-elankey/application-software-/blob/main/src/server/http/api.ts"
click node_errors "https://github.com/toyin-elankey/application-software-/blob/main/src/server/http/problem.ts"
click node_database_client "https://github.com/toyin-elankey/application-software-/blob/main/src/server/db/client.ts"
click node_tenant "https://github.com/toyin-elankey/application-software-/blob/main/src/server/tenant.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_storefront,node_catalogue_api,node_cart_api,node_cart_service,node_checkout_api,node_checkout_service,node_pricing,node_delivery toneBlue
class node_customer_api,node_customer_auth,node_sessions,node_order_api,node_staff_api,node_staff_guard,node_admin_reads toneAmber
class node_pay_provider,node_paystack_webhook,node_webhook_api,node_payment_jobs,node_refunds toneMint
class node_api_plumbing,node_errors,node_database_client,node_database,node_tenant toneRose
class node_shopper toneIndigo
```

## Components

### Shopping and checkout

- [Storefront](https://github.com/toyin-elankey/application-software-/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Catalogue API](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/catalog/products/route.ts): `src/app/api/v1/catalog/products/route.ts`
- [Cart API](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/cart/items/route.ts): `src/app/api/v1/cart/items/route.ts`
- [Cart service](https://github.com/toyin-elankey/application-software-/blob/main/src/server/cart/cart.ts): `src/server/cart/cart.ts`
- [Checkout API](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/checkout/route.ts): `src/app/api/v1/checkout/route.ts`
- [Checkout service](https://github.com/toyin-elankey/application-software-/blob/main/src/server/checkout/checkout.ts): `src/server/checkout/checkout.ts`
- [Pricing](https://github.com/toyin-elankey/application-software-/blob/main/src/server/pricing/pricing.ts): `src/server/pricing/pricing.ts`
- [Delivery quotes](https://github.com/toyin-elankey/application-software-/blob/main/src/server/delivery/quote.ts): `src/server/delivery/quote.ts`

### Identity and administration

- [Customer APIs](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/auth/logout/route.ts): `src/app/api/v1/auth/logout/route.ts`
- [Customer authentication](https://github.com/toyin-elankey/application-software-/blob/main/src/server/customers/auth.ts): `src/server/customers/auth.ts`
- [Customer sessions](https://github.com/toyin-elankey/application-software-/blob/main/src/server/customers/sessions.ts): `src/server/customers/sessions.ts`
- [Order lookup API](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/orders/%5BorderNumber%5D/route.ts): `src/app/api/v1/orders/[orderNumber]/route.ts`
- [Staff APIs](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/v1/admin/staff/route.ts): `src/app/api/v1/admin/staff/route.ts`
- [Staff access guard](https://github.com/toyin-elankey/application-software-/blob/main/src/server/auth/guard.ts): `src/server/auth/guard.ts`
- [Admin reads](https://github.com/toyin-elankey/application-software-/blob/main/src/server/admin/reads.ts): `src/server/admin/reads.ts`

### Payments and refunds

- [Provider selection](https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/resolve.ts): `src/server/payments/resolve.ts`
- [Paystack webhook](https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/webhook.ts): `src/server/payments/webhook.ts`
- [Webhook API](https://github.com/toyin-elankey/application-software-/blob/main/src/app/api/webhooks/paystack/route.ts): `src/app/api/webhooks/paystack/route.ts`
- [Payment job drain](https://github.com/toyin-elankey/application-software-/blob/main/src/server/payments/drain.ts): `src/server/payments/drain.ts`
- [Refund service](https://github.com/toyin-elankey/application-software-/blob/main/src/server/refunds/service.ts): `src/server/refunds/service.ts`

### Runtime foundations

- [API plumbing](https://github.com/toyin-elankey/application-software-/blob/main/src/server/http/api.ts): `src/server/http/api.ts`
- [HTTP errors](https://github.com/toyin-elankey/application-software-/blob/main/src/server/http/problem.ts): `src/server/http/problem.ts`
- [Database client](https://github.com/toyin-elankey/application-software-/blob/main/src/server/db/client.ts): `src/server/db/client.ts`
- **PostgreSQL**
- [Tenant scope](https://github.com/toyin-elankey/application-software-/blob/main/src/server/tenant.ts): `src/server/tenant.ts`

### Other components

- **Shopper**

## Connections

- Shopper → Storefront: browses
- Shopper → Catalogue API: requests products
- Shopper → Cart API: updates cart
- Cart API → Cart service: calls (evidence: `src/app/api/v1/cart/items/route.ts`)
- Cart API → API plumbing: uses (evidence: `src/app/api/v1/cart/items/route.ts`)
- Shopper → Checkout API: submits checkout
- Checkout API → Checkout service: calls (evidence: `src/app/api/v1/checkout/route.ts`)
- Checkout API → Provider selection: selects provider (evidence: `src/app/api/v1/checkout/route.ts`)
- Checkout API → API plumbing: uses (evidence: `src/app/api/v1/checkout/route.ts`)
- Checkout service → Pricing: uses (evidence: `src/server/checkout/checkout.ts`)
- Checkout service → Delivery quotes: uses (evidence: `src/server/checkout/checkout.ts`)
- Customer APIs → Customer authentication: calls (evidence: `src/app/api/v1/auth/logout/route.ts`)
- Customer APIs → Customer sessions: uses (evidence: `src/app/api/v1/auth/logout/route.ts`)
- Customer authentication → Customer sessions: opens sessions (evidence: `src/server/customers/auth.ts`)
- Order lookup API → Customer sessions: resolves access (evidence: `src/app/api/v1/orders/[orderNumber]/route.ts`)
- Staff APIs → Staff access guard: checks access (evidence: `src/app/api/v1/admin/staff/route.ts`)
- Staff APIs → API plumbing: uses (evidence: `src/app/api/v1/admin/staff/route.ts`)
- Staff APIs → PostgreSQL: manages staff records (evidence: `src/app/api/v1/admin/staff/route.ts`)
- Admin reads → Tenant scope: scopes queries (evidence: `src/server/admin/reads.ts`)
- Admin reads → PostgreSQL: reads commerce data (evidence: `src/server/admin/reads.ts`)
- Webhook API → Paystack webhook: accepts events (evidence: `src/app/api/webhooks/paystack/route.ts`)
- Webhook API → Payment job drain: drains jobs (evidence: `src/app/api/webhooks/paystack/route.ts`)
- Paystack webhook → PostgreSQL: stores events and jobs (evidence: `src/server/payments/webhook.ts`)
- Payment job drain → Refund service: dispatches refund work (evidence: `src/server/payments/drain.ts`)
- Checkout service → PostgreSQL: places orders (evidence: `src/server/checkout/checkout.ts`)
- Database client → PostgreSQL: connects (evidence: `src/server/db/client.ts`)
- API plumbing → Database client: gets client (evidence: `src/server/http/api.ts`)
- API plumbing → HTTP errors: uses responses (evidence: `src/server/http/api.ts`)
- Checkout API → HTTP errors: handles errors (evidence: `src/app/api/v1/checkout/route.ts`)
