# aku-brecah/akubrecah-entertainment architecture

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

- Interactive diagram: https://gitdiagram.com/aku-brecah/akubrecah-entertainment
- Repository: https://github.com/aku-brecah/akubrecah-entertainment

## Overview

Akubrecah is a KRA taxpayer retrieval and certificate portal, with web and WhatsApp entry points. Taxpayers submit an ID or PIN, the server retrieves KRA data, masks it before payment, and supports paid certificate fulfillment; M-Pesa and Cyber Cafe subscriptions extend that journey. The product also includes a WhatsApp bot and an admin console. The graph emphasizes relationships visible in excerpts, the source index, or README; several admin and web subsystems are documented but unsampled, so their internal links are omitted.

Main entry points: [`app/api/kra/retrieve/route.ts`](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/kra/retrieve/route.ts) (Retrieval endpoint), [`app/api/whatsapp/chat/route.ts`](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/whatsapp/chat/route.ts) (WhatsApp chat), [`lib/certificate-fulfillment.ts`](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/certificate-fulfillment.ts) (Certificate fulfillment), [`lib/prisma.ts`](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/prisma.ts) (Postgres data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portal"]
  node_web_portal["Retrieval portal<br/>[page.tsx]"]
  node_kra_portal_ui["KRA portal UI<br/>[kra-portal.tsx]"]
  node_admin_console["Admin console<br/>[page.tsx]"]
  node_admin_apis["Admin APIs"]
  node_admin_auth["Admin access<br/>[admin-auth.ts]"]
end

subgraph group_retrieval["KRA retrieval"]
  node_retrieval_api["Retrieval endpoint<br/>[route.ts]"]
  node_kra_service["KRA API client<br/>[kra-api.ts]"]
  node_stations["TSO stations<br/>[kra-stations.ts]"]
  node_privacy["PIN masking<br/>[masking.ts]"]
end

subgraph group_payments["Payments and fulfillment"]
  node_certificate_api["Certificate endpoint<br/>[route.ts]"]
  node_payment_callback["M-Pesa callback<br/>[route.ts]"]
  node_mpesa_dispatch["STK dispatch<br/>[mpesa-dispatch.ts]"]
  node_certificate_fulfillment["Certificate fulfillment"]
  node_cyber_subscription["Cyber Cafe plans"]
  node_subscription["User subscriptions<br/>[subscription.ts]"]
end

subgraph group_operations["Bot and operations"]
  node_database[("Postgres data<br/>[prisma.ts]")]
  node_whatsapp_chat["WhatsApp chat<br/>[route.ts]"]
  node_whatsapp_webhook["WhatsApp webhook<br/>[route.ts]"]
  node_commands["Command parser<br/>[commands.ts]"]
  node_evolution["Evolution API client<br/>[evolution.ts]"]
  node_wa_payments["Bot payments<br/>[payments.ts]"]
  node_wa_fulfillment["Bot fulfillment<br/>[fulfillment.ts]"]
  node_monitoring["Structured logging<br/>[logger.ts]"]
end

node_taxpayer(("Taxpayer"))
node_mpesa["Safaricom Daraja"]
node_whatsapp(("WhatsApp user"))
node_evolution_service["Evolution WhatsApp"]

node_taxpayer -->|"submits lookup"| node_web_portal
node_web_portal -->|"renders"| node_kra_portal_ui
node_kra_portal_ui -.->|"requests lookup"| node_retrieval_api
node_retrieval_api -->|"fetches taxpayer"| node_kra_service
node_retrieval_api -->|"resolves station"| node_stations
node_retrieval_api -->|"masks results"| node_privacy
node_retrieval_api -->|"checks access"| node_subscription
node_kra_service -->|"reads records"| node_database
node_kra_service -->|"uses station data"| node_stations
node_certificate_api -->|"gets user"| node_subscription
node_payment_callback -->|"maps result"| node_mpesa_dispatch
node_payment_callback -->|"updates payments"| node_database
node_mpesa_dispatch -->|"sends STK push"| node_mpesa
node_mpesa -->|"posts result"| node_payment_callback
node_certificate_fulfillment -->|"records downloads"| node_database
node_certificate_fulfillment -->|"gets user"| node_subscription
node_certificate_fulfillment -->|"sends documents"| node_evolution
node_cyber_subscription -->|"stores plans"| node_database
node_whatsapp -.->|"sends messages"| node_whatsapp_webhook
node_whatsapp_webhook -->|"dispatches chat"| node_whatsapp_chat
node_whatsapp_chat -->|"parses commands"| node_commands
node_whatsapp_chat -->|"sends replies"| node_evolution
node_whatsapp_chat -->|"checks status"| node_cyber_subscription
node_whatsapp_chat -->|"starts renewal"| node_wa_payments
node_wa_fulfillment -->|"checks plan"| node_cyber_subscription
node_wa_fulfillment -->|"delivers certificate"| node_certificate_fulfillment
node_wa_fulfillment -->|"starts payment"| node_wa_payments
node_wa_payments -->|"dispatches STK"| node_mpesa_dispatch
node_evolution -->|"sends messages"| node_evolution_service
node_admin_console -.->|"manages records"| node_admin_apis
node_admin_apis -.->|"checks access"| node_admin_auth
node_retrieval_api -->|"logs events"| node_monitoring

click node_web_portal "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/retrieval-portal/page.tsx"
click node_kra_portal_ui "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/components/kra-portal.tsx"
click node_admin_console "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/admin/page.tsx"
click node_admin_apis "https://github.com/aku-brecah/akubrecah-entertainment/tree/main/app/api/admin"
click node_admin_auth "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/admin-auth.ts"
click node_retrieval_api "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/kra/retrieve/route.ts"
click node_kra_service "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/kra-api.ts"
click node_stations "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/kra-stations.ts"
click node_privacy "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/masking.ts"
click node_certificate_api "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/generate-certificate/route.ts"
click node_payment_callback "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/mpesa/callback/route.ts"
click node_mpesa_dispatch "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/mpesa-dispatch.ts"
click node_certificate_fulfillment "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/certificate-fulfillment.ts"
click node_cyber_subscription "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/cyber-subscription.ts"
click node_subscription "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/subscription.ts"
click node_database "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/prisma.ts"
click node_whatsapp_chat "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/whatsapp/chat/route.ts"
click node_whatsapp_webhook "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/whatsapp/webhook/route.ts"
click node_commands "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/commands.ts"
click node_evolution "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/evolution.ts"
click node_wa_payments "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/payments.ts"
click node_wa_fulfillment "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/fulfillment.ts"
click node_monitoring "https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/monitoring/logger.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_web_portal,node_kra_portal_ui,node_admin_console,node_admin_apis,node_admin_auth,node_whatsapp toneBlue
class node_retrieval_api,node_kra_service,node_stations,node_privacy toneAmber
class node_certificate_api,node_payment_callback,node_mpesa_dispatch,node_certificate_fulfillment,node_cyber_subscription,node_subscription toneMint
class node_database,node_whatsapp_chat,node_whatsapp_webhook,node_commands,node_evolution,node_wa_payments,node_wa_fulfillment,node_monitoring toneRose
class node_taxpayer,node_mpesa,node_evolution_service toneIndigo
```

## Components

### Web portal

- [Retrieval portal](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/retrieval-portal/page.tsx): `app/retrieval-portal/page.tsx`
- [KRA portal UI](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/components/kra-portal.tsx): `components/kra-portal.tsx`
- [Admin console](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/admin/page.tsx): `app/admin/page.tsx`
- [Admin APIs](https://github.com/aku-brecah/akubrecah-entertainment/tree/main/app/api/admin): `app/api/admin`
- [Admin access](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/admin-auth.ts): `lib/admin-auth.ts`

### KRA retrieval

- [Retrieval endpoint](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/kra/retrieve/route.ts): `app/api/kra/retrieve/route.ts`
- [KRA API client](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/kra-api.ts): `lib/kra-api.ts`
- [TSO stations](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/kra-stations.ts): `lib/kra-stations.ts`
- [PIN masking](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/masking.ts): `lib/masking.ts`

### Payments and fulfillment

- [Certificate endpoint](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/generate-certificate/route.ts): `app/api/generate-certificate/route.ts`
- [M-Pesa callback](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/mpesa/callback/route.ts): `app/api/mpesa/callback/route.ts`
- [STK dispatch](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/mpesa-dispatch.ts): `lib/whatsapp/mpesa-dispatch.ts`
- [Certificate fulfillment](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/certificate-fulfillment.ts): `lib/certificate-fulfillment.ts`
- [Cyber Cafe plans](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/cyber-subscription.ts): `lib/cyber-subscription.ts`
- [User subscriptions](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/subscription.ts): `lib/subscription.ts`

### Bot and operations

- [Postgres data](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/prisma.ts): `lib/prisma.ts`
- [WhatsApp chat](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/whatsapp/chat/route.ts): `app/api/whatsapp/chat/route.ts`
- [WhatsApp webhook](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/app/api/whatsapp/webhook/route.ts): `app/api/whatsapp/webhook/route.ts`
- [Command parser](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/commands.ts): `lib/whatsapp/commands.ts`
- [Evolution API client](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/evolution.ts): `lib/evolution.ts`
- [Bot payments](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/payments.ts): `lib/whatsapp/payments.ts`
- [Bot fulfillment](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/whatsapp/fulfillment.ts): `lib/whatsapp/fulfillment.ts`
- [Structured logging](https://github.com/aku-brecah/akubrecah-entertainment/blob/main/lib/monitoring/logger.ts): `lib/monitoring/logger.ts`

### Other components

- **Taxpayer**
- **Safaricom Daraja**
- **WhatsApp user**
- **Evolution WhatsApp**

## Connections

- Taxpayer → Retrieval portal: submits lookup
- Retrieval portal → KRA portal UI: renders (evidence: `app/retrieval-portal/page.tsx`)
- KRA portal UI → Retrieval endpoint: requests lookup
- Retrieval endpoint → KRA API client: fetches taxpayer (evidence: `app/api/kra/retrieve/route.ts`)
- Retrieval endpoint → TSO stations: resolves station (evidence: `app/api/kra/retrieve/route.ts`)
- Retrieval endpoint → PIN masking: masks results (evidence: `app/api/kra/retrieve/route.ts`)
- Retrieval endpoint → User subscriptions: checks access (evidence: `app/api/kra/retrieve/route.ts`)
- KRA API client → Postgres data: reads records (evidence: `lib/kra-api.ts`)
- KRA API client → TSO stations: uses station data (evidence: `lib/kra-api.ts`)
- Certificate endpoint → User subscriptions: gets user (evidence: `app/api/generate-certificate/route.ts`)
- M-Pesa callback → STK dispatch: maps result (evidence: `app/api/mpesa/callback/route.ts`)
- M-Pesa callback → Postgres data: updates payments (evidence: `app/api/mpesa/callback/route.ts`)
- STK dispatch → Safaricom Daraja: sends STK push
- Safaricom Daraja → M-Pesa callback: posts result
- Certificate fulfillment → Postgres data: records downloads (evidence: `lib/certificate-fulfillment.ts`)
- Certificate fulfillment → User subscriptions: gets user (evidence: `lib/certificate-fulfillment.ts`)
- Certificate fulfillment → Evolution API client: sends documents (evidence: `lib/certificate-fulfillment.ts`)
- Cyber Cafe plans → Postgres data: stores plans (evidence: `lib/cyber-subscription.ts`)
- WhatsApp user → WhatsApp webhook: sends messages
- WhatsApp webhook → WhatsApp chat: dispatches chat (evidence: `app/api/whatsapp/webhook/route.ts`)
- WhatsApp chat → Command parser: parses commands (evidence: `app/api/whatsapp/chat/route.ts`)
- WhatsApp chat → Evolution API client: sends replies (evidence: `app/api/whatsapp/chat/route.ts`)
- WhatsApp chat → Cyber Cafe plans: checks status (evidence: `app/api/whatsapp/chat/route.ts`)
- WhatsApp chat → Bot payments: starts renewal (evidence: `app/api/whatsapp/chat/route.ts`)
- Bot fulfillment → Cyber Cafe plans: checks plan (evidence: `lib/whatsapp/fulfillment.ts`)
- Bot fulfillment → Certificate fulfillment: delivers certificate (evidence: `lib/whatsapp/fulfillment.ts`)
- Bot fulfillment → Bot payments: starts payment (evidence: `lib/whatsapp/fulfillment.ts`)
- Bot payments → STK dispatch: dispatches STK (evidence: `lib/whatsapp/payments.ts`)
- Evolution API client → Evolution WhatsApp: sends messages (evidence: `lib/evolution.ts`)
- Admin console → Admin APIs: manages records
- Admin APIs → Admin access: checks access
- Retrieval endpoint → Structured logging: logs events (evidence: `app/api/kra/retrieve/route.ts`)
