# llewellynkearney/jagspoor_v4_2 architecture

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

- Interactive diagram: https://gitdiagram.com/llewellynkearney/jagspoor_v4_2
- Repository: https://github.com/llewellynkearney/jagspoor_v4_2

## Overview

JagSpoor is presented as a Flutter app, with supporting Firebase Cloud Functions and a Telegram bot. The main user-facing Flutter source is not present in the supplied tree, so its hunting, navigation, and booking workflows cannot be traced here. The visible backend supports account administration, subscriptions and billing, notifications, referrals, and KPIs; the bot exposes hunting and outfitter commands backed by Firebase. The graph focuses on these evidenced runtime components. Unsampled modules are included where the source index identifies them, but their internal behavior and some links remain unverified.

Main entry points: [`functions/src/index.ts`](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/index.ts) (Function exports), [`functions/src/payfast/payfast.ts`](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/payfast.ts) (PayFast handlers), [`functions/src/firebase.ts`](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/firebase.ts) (Admin Firebase), [`functions/src/alternative_billing.ts`](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/alternative_billing.ts) (Alternative billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cloud["Firebase backend"]
  node_functions["Function exports<br/>[index.ts]"]
  node_firebase["Admin Firebase<br/>[firebase.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_email["Email delivery<br/>[email.ts]"]
  node_params["Runtime parameters<br/>[params.ts]"]
  node_kpis["Admin KPIs<br/>[kpis.ts]"]
  node_referrals["Referrals<br/>[referral.ts]"]
  node_onboarding["Trial onboarding"]
end

subgraph group_billing["Billing and entitlements"]
  node_entitlement["Entitlements<br/>[entitlement.ts]"]
  node_alternative["Alternative billing"]
  node_payfast["PayFast handlers<br/>[payfast.ts]"]
  node_payfast_service["PayFast signing<br/>[payfast.service.ts]"]
  node_plans["Plan catalog<br/>[plans.ts]"]
end

subgraph group_bot["Telegram bot"]
  node_webhook["Bot webhook<br/>[webhook_server.py]"]
  node_commands["Hunter commands"]
  node_outfitter_commands["Outfitter commands"]
  node_bot_firebase["Bot Firebase service"]
end

subgraph group_platform["App and data utilities"]
  node_desktop["Windows app runner<br/>[main.cpp]"]
  node_scraper["SAPS scraper template"]
  node_animal_register["Animal register generator"]
end

node_client(("Flutter clients"))
node_store[("Firestore and Auth")]
node_telegram(("Telegram users"))

node_client -.->|"calls billing"| node_functions
node_functions -->|"uses admin SDK"| node_firebase
node_functions -->|"exports triggers"| node_notifications
node_functions -->|"exports handlers"| node_entitlement
node_functions -->|"exports handlers"| node_referrals
node_functions -->|"exports handlers"| node_payfast
node_functions -->|"exports handlers"| node_alternative
node_functions -->|"exports handlers"| node_kpis
node_functions -->|"exports handlers"| node_onboarding
node_notifications -->|"uses delivery"| node_email
node_notifications -->|"reads settings"| node_params
node_notifications -->|"uses admin SDK"| node_firebase
node_kpis -->|"uses admin SDK"| node_firebase
node_onboarding -->|"uses admin SDK"| node_firebase
node_onboarding -->|"reads settings"| node_params
node_entitlement -->|"writes entitlements"| node_firebase
node_entitlement -.->|"reads Play status"| node_store
node_alternative -->|"uses admin SDK"| node_firebase
node_alternative -->|"updates access"| node_entitlement
node_alternative -->|"resolves plans"| node_plans
node_payfast -->|"uses signing"| node_payfast_service
node_payfast -->|"resolves plans"| node_plans
node_payfast -->|"reads settings"| node_params
node_payfast -->|"updates access"| node_entitlement
node_payfast -->|"uses billing"| node_alternative
node_payfast -.->|"verifies payments"| node_store
node_telegram -.->|"sends commands"| node_webhook
node_webhook -->|"dispatches"| node_commands
node_webhook -->|"dispatches"| node_outfitter_commands
node_commands -->|"loads user data"| node_bot_firebase
node_outfitter_commands -->|"loads business data"| node_bot_firebase
node_bot_firebase -.->|"reads records"| node_store

click node_functions "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/index.ts"
click node_firebase "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/firebase.ts"
click node_notifications "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/notifications.ts"
click node_email "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/email.ts"
click node_params "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/params.ts"
click node_kpis "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/admin/kpis.ts"
click node_referrals "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/referral.ts"
click node_onboarding "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/user_trial_onboarding.ts"
click node_entitlement "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/entitlement.ts"
click node_alternative "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/alternative_billing.ts"
click node_payfast "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/payfast.ts"
click node_payfast_service "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/payfast.service.ts"
click node_plans "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/plans.ts"
click node_webhook "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/webhook_server.py"
click node_commands "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/command_handlers.py"
click node_outfitter_commands "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/command_handlers_part2.py"
click node_bot_firebase "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/firebase_service.py"
click node_desktop "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/windows/runner/main.cpp"
click node_scraper "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/lib/features/hunter_mode/services/saps_scraper_template.js"
click node_animal_register "https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/data/animals/generate_register.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_functions,node_firebase,node_notifications,node_email,node_params,node_kpis,node_referrals,node_onboarding,node_client,node_telegram toneBlue
class node_entitlement,node_alternative,node_payfast,node_payfast_service,node_plans,node_store toneAmber
class node_webhook,node_commands,node_outfitter_commands,node_bot_firebase toneMint
class node_desktop,node_scraper,node_animal_register toneRose
```

## Components

### Firebase backend

- [Function exports](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/index.ts): `functions/src/index.ts`
- [Admin Firebase](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/firebase.ts): `functions/src/firebase.ts`
- [Notifications](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/notifications.ts): `functions/src/notifications.ts`
- [Email delivery](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/email.ts): `functions/src/email.ts`
- [Runtime parameters](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/params.ts): `functions/src/params.ts`
- [Admin KPIs](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/admin/kpis.ts): `functions/src/admin/kpis.ts`
- [Referrals](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/referral.ts): `functions/src/referral.ts`
- [Trial onboarding](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/user_trial_onboarding.ts): `functions/src/user_trial_onboarding.ts`

### Billing and entitlements

- [Entitlements](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/entitlement.ts): `functions/src/entitlement.ts`
- [Alternative billing](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/alternative_billing.ts): `functions/src/alternative_billing.ts`
- [PayFast handlers](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/payfast.ts): `functions/src/payfast/payfast.ts`
- [PayFast signing](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/payfast.service.ts): `functions/src/payfast/payfast.service.ts`
- [Plan catalog](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/functions/src/payfast/plans.ts): `functions/src/payfast/plans.ts`

### Telegram bot

- [Bot webhook](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/webhook_server.py): `telegram_bot/webhook_server.py`
- [Hunter commands](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/command_handlers.py): `telegram_bot/command_handlers.py`
- [Outfitter commands](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/command_handlers_part2.py): `telegram_bot/command_handlers_part2.py`
- [Bot Firebase service](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/telegram_bot/firebase_service.py): `telegram_bot/firebase_service.py`

### App and data utilities

- [Windows app runner](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/windows/runner/main.cpp): `windows/runner/main.cpp`
- [SAPS scraper template](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/lib/features/hunter_mode/services/saps_scraper_template.js): `lib/features/hunter_mode/services/saps_scraper_template.js`
- [Animal register generator](https://github.com/llewellynkearney/jagspoor_v4_2/blob/main/data/animals/generate_register.py): `data/animals/generate_register.py`

### Other components

- **Flutter clients**
- **Firestore and Auth**
- **Telegram users**

## Connections

- Flutter clients → Function exports: calls billing
- Function exports → Admin Firebase: uses admin SDK (evidence: `functions/src/index.ts`)
- Function exports → Notifications: exports triggers (evidence: `functions/src/index.ts`)
- Function exports → Entitlements: exports handlers (evidence: `functions/src/index.ts`)
- Function exports → Referrals: exports handlers (evidence: `functions/src/index.ts`)
- Function exports → PayFast handlers: exports handlers (evidence: `functions/src/index.ts`)
- Function exports → Alternative billing: exports handlers (evidence: `functions/src/index.ts`)
- Function exports → Admin KPIs: exports handlers (evidence: `functions/src/index.ts`)
- Function exports → Trial onboarding: exports handlers (evidence: `functions/src/index.ts`)
- Notifications → Email delivery: uses delivery (evidence: `functions/src/notifications.ts`)
- Notifications → Runtime parameters: reads settings (evidence: `functions/src/notifications.ts`)
- Notifications → Admin Firebase: uses admin SDK (evidence: `functions/src/notifications.ts`)
- Admin KPIs → Admin Firebase: uses admin SDK (evidence: `functions/src/admin/kpis.ts`)
- Trial onboarding → Admin Firebase: uses admin SDK (evidence: `functions/src/user_trial_onboarding.ts`)
- Trial onboarding → Runtime parameters: reads settings (evidence: `functions/src/user_trial_onboarding.ts`)
- Entitlements → Admin Firebase: writes entitlements (evidence: `functions/src/entitlement.ts`)
- Entitlements → Firestore and Auth: reads Play status
- Alternative billing → Admin Firebase: uses admin SDK (evidence: `functions/src/alternative_billing.ts`)
- Alternative billing → Entitlements: updates access (evidence: `functions/src/alternative_billing.ts`)
- Alternative billing → Plan catalog: resolves plans (evidence: `functions/src/alternative_billing.ts`)
- PayFast handlers → PayFast signing: uses signing (evidence: `functions/src/payfast/payfast.ts`)
- PayFast handlers → Plan catalog: resolves plans (evidence: `functions/src/payfast/payfast.ts`)
- PayFast handlers → Runtime parameters: reads settings (evidence: `functions/src/payfast/payfast.ts`)
- PayFast handlers → Entitlements: updates access (evidence: `functions/src/payfast/payfast.ts`)
- PayFast handlers → Alternative billing: uses billing (evidence: `functions/src/payfast/payfast.ts`)
- PayFast handlers → Firestore and Auth: verifies payments
- Telegram users → Bot webhook: sends commands
- Bot webhook → Hunter commands: dispatches (evidence: `telegram_bot/webhook_server.py`)
- Bot webhook → Outfitter commands: dispatches (evidence: `telegram_bot/webhook_server.py`)
- Hunter commands → Bot Firebase service: loads user data (evidence: `telegram_bot/command_handlers.py`)
- Outfitter commands → Bot Firebase service: loads business data (evidence: `telegram_bot/command_handlers_part2.py`)
- Bot Firebase service → Firestore and Auth: reads records