# dev-wyp/lwal-kuu architecture

> Architecture diagram of the GitHub repository dev-wyp/lwal-kuu, 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/dev-wyp/lwal-kuu
- Repository: https://github.com/dev-wyp/lwal-kuu

## Overview

Lwal Kuu is a multi-tenant wholesale and shop-management SaaS, with a separate marketing workspace and platform-admin experience. The main shop workflow spans catalog and supplier purchasing, stock management, POS invoicing, customer payments and credit ledgers, then reporting. React routes expose these workflows; organization/auth contexts scope users, while Supabase provides the application backend. README-documented capabilities are included even where their implementation was not sampled. Edges are limited to route references, indexed imports, sampled calls, or README statements; unsampled links are omitted.

Main entry points: [`src/routes/index.tsx`](https://github.com/dev-wyp/lwal-kuu/blob/main/src/routes/index.tsx) (Application routes), [`src/context/OrgContext.tsx`](https://github.com/dev-wyp/lwal-kuu/blob/main/src/context/OrgContext.tsx) (Organization context), [`src/lib/supabase.ts`](https://github.com/dev-wyp/lwal-kuu/blob/main/src/lib/supabase.ts) (Supabase client), [`src/modules/sales/SalesPage.tsx`](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/sales/SalesPage.tsx) (POS and invoices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shop["Shop Operations"]
  node_dashboard["Shop dashboard<br/>[DashboardPage.tsx]"]
  node_products["Product catalog<br/>[ProductsPage.tsx]"]
  node_purchases["Purchases and receiving<br/>[PurchasesPage.tsx]"]
  node_suppliers["Supplier accounts<br/>[SuppliersPage.tsx]"]
  node_inventory["Stock ledger<br/>[InventoryPage.tsx]"]
  node_sales["POS and invoices<br/>[SalesPage.tsx]"]
  node_customers["Customer ledgers<br/>[CustomersPage.tsx]"]
  node_payments["Customer payments<br/>[PaymentsPage.tsx]"]
  node_expenses["Expense tracking<br/>[ExpensesPage.tsx]"]
  node_reports["Business reports<br/>[ReportsPage.tsx]"]
end

subgraph group_tenant["Tenant and SaaS"]
  node_routes["Application routes<br/>[index.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_org["Organization context<br/>[OrgContext.tsx]"]
  node_onboard["Shop onboarding<br/>[OnboardingPage.tsx]"]
  node_entitlements["Plan entitlements<br/>[useEntitlements.ts]"]
  node_platform_admin["Platform administration"]
end

subgraph group_marketing["Marketing Workspace"]
  node_marketing_workspace["Marketing workspace"]
  node_marketing_pages["Campaigns and content"]
  node_marketing_ai["Marketing AI<br/>[index.ts]"]
  node_marketing_oauth["Social account OAuth<br/>[index.ts]"]
  node_marketing_jobs["Publishing jobs<br/>[index.ts]"]
  node_publish_worker["Publish worker<br/>[publish-worker.ts]"]
  node_providers["Social provider adapters<br/>[providers.ts]"]
end

subgraph group_platform["Platform Services"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_supabase_backend[("Supabase backend")]
  node_publish_service(("Social platforms"))
end

node_shop_user(("Shop user"))

node_shop_user -->|"opens app"| node_routes
node_routes -->|"provides auth"| node_auth
node_routes -->|"provides organization"| node_org
node_routes -->|"routes onboarding"| node_onboard
node_routes -->|"routes dashboard"| node_dashboard
node_routes -->|"routes catalog"| node_products
node_routes -->|"routes purchasing"| node_purchases
node_routes -->|"routes inventory"| node_inventory
node_routes -->|"routes POS"| node_sales
node_routes -->|"routes customers"| node_customers
node_routes -->|"routes suppliers"| node_suppliers
node_routes -->|"routes payments"| node_payments
node_routes -->|"routes expenses"| node_expenses
node_routes -->|"routes reports"| node_reports
node_routes -->|"routes administration"| node_platform_admin
node_auth -->|"queries auth"| node_supabase_client
node_org -->|"reads identity"| node_auth
node_org -->|"loads membership"| node_supabase_client
node_entitlements -->|"reads organization"| node_org
node_entitlements -->|"queries limits"| node_supabase_client
node_sales -.->|"records credit sales"| node_customers
node_purchases -.->|"increments stock"| node_inventory
node_sales -.->|"records movements"| node_inventory
node_payments -.->|"allocates receipts"| node_customers
node_sales -.->|"feeds sales metrics"| node_reports
node_routes -->|"routes marketing"| node_marketing_pages
node_marketing_pages -->|"loads workspace"| node_marketing_workspace
node_marketing_workspace -->|"scopes workspace"| node_org
node_marketing_workspace -->|"loads workspace data"| node_supabase_client
node_marketing_pages -.->|"requests AI features"| node_marketing_ai
node_marketing_pages -.->|"connects accounts"| node_marketing_oauth
node_marketing_jobs -->|"dispatches jobs"| node_publish_worker
node_publish_worker -->|"selects adapter"| node_providers
node_publish_worker -->|"claims and updates jobs"| node_supabase_backend
node_publish_worker -->|"publishes content"| node_publish_service
node_supabase_client -->|"reads and writes"| node_supabase_backend

click node_routes "https://github.com/dev-wyp/lwal-kuu/blob/main/src/routes/index.tsx"
click node_auth "https://github.com/dev-wyp/lwal-kuu/blob/main/src/context/AuthContext.tsx"
click node_org "https://github.com/dev-wyp/lwal-kuu/blob/main/src/context/OrgContext.tsx"
click node_onboard "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/onboarding/OnboardingPage.tsx"
click node_entitlements "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/subscription/useEntitlements.ts"
click node_platform_admin "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/platform/PlatformAdminPage.tsx"
click node_dashboard "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/dashboard/DashboardPage.tsx"
click node_products "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/products/ProductsPage.tsx"
click node_purchases "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/purchases/PurchasesPage.tsx"
click node_suppliers "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/suppliers/SuppliersPage.tsx"
click node_inventory "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/inventory/InventoryPage.tsx"
click node_sales "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/sales/SalesPage.tsx"
click node_customers "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/customers/CustomersPage.tsx"
click node_payments "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/payments/PaymentsPage.tsx"
click node_expenses "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/expenses/ExpensesPage.tsx"
click node_reports "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/reports/ReportsPage.tsx"
click node_marketing_workspace "https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/marketing/hooks/useMarketingWorkspace.ts"
click node_marketing_pages "https://github.com/dev-wyp/lwal-kuu/tree/main/src/modules/marketing/pages"
click node_marketing_ai "https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-ai/index.ts"
click node_marketing_oauth "https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-oauth/index.ts"
click node_marketing_jobs "https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-jobs/index.ts"
click node_publish_worker "https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/_shared/publish-worker.ts"
click node_providers "https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/_shared/providers.ts"
click node_supabase_client "https://github.com/dev-wyp/lwal-kuu/blob/main/src/lib/supabase.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_dashboard,node_products,node_purchases,node_suppliers,node_inventory,node_sales,node_customers,node_payments,node_expenses,node_reports,node_shop_user toneBlue
class node_routes,node_auth,node_org,node_onboard,node_entitlements,node_platform_admin toneAmber
class node_marketing_workspace,node_marketing_pages,node_marketing_ai,node_marketing_oauth,node_marketing_jobs,node_publish_worker,node_providers toneMint
class node_supabase_client,node_supabase_backend,node_publish_service toneRose
```

## Components

### Shop Operations

- [Shop dashboard](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/dashboard/DashboardPage.tsx): `src/modules/dashboard/DashboardPage.tsx`
- [Product catalog](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/products/ProductsPage.tsx): `src/modules/products/ProductsPage.tsx`
- [Purchases and receiving](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/purchases/PurchasesPage.tsx): `src/modules/purchases/PurchasesPage.tsx`
- [Supplier accounts](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/suppliers/SuppliersPage.tsx): `src/modules/suppliers/SuppliersPage.tsx`
- [Stock ledger](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/inventory/InventoryPage.tsx): `src/modules/inventory/InventoryPage.tsx`
- [POS and invoices](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/sales/SalesPage.tsx): `src/modules/sales/SalesPage.tsx`
- [Customer ledgers](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/customers/CustomersPage.tsx): `src/modules/customers/CustomersPage.tsx`
- [Customer payments](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/payments/PaymentsPage.tsx): `src/modules/payments/PaymentsPage.tsx`
- [Expense tracking](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/expenses/ExpensesPage.tsx): `src/modules/expenses/ExpensesPage.tsx`
- [Business reports](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/reports/ReportsPage.tsx): `src/modules/reports/ReportsPage.tsx`

### Tenant and SaaS

- [Application routes](https://github.com/dev-wyp/lwal-kuu/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Authentication](https://github.com/dev-wyp/lwal-kuu/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Organization context](https://github.com/dev-wyp/lwal-kuu/blob/main/src/context/OrgContext.tsx): `src/context/OrgContext.tsx`
- [Shop onboarding](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/onboarding/OnboardingPage.tsx): `src/modules/onboarding/OnboardingPage.tsx`
- [Plan entitlements](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/subscription/useEntitlements.ts): `src/modules/subscription/useEntitlements.ts`
- [Platform administration](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/platform/PlatformAdminPage.tsx): `src/modules/platform/PlatformAdminPage.tsx`

### Marketing Workspace

- [Marketing workspace](https://github.com/dev-wyp/lwal-kuu/blob/main/src/modules/marketing/hooks/useMarketingWorkspace.ts): `src/modules/marketing/hooks/useMarketingWorkspace.ts`
- [Campaigns and content](https://github.com/dev-wyp/lwal-kuu/tree/main/src/modules/marketing/pages): `src/modules/marketing/pages`
- [Marketing AI](https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-ai/index.ts): `supabase/functions/marketing-ai/index.ts`
- [Social account OAuth](https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-oauth/index.ts): `supabase/functions/marketing-oauth/index.ts`
- [Publishing jobs](https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/marketing-jobs/index.ts): `supabase/functions/marketing-jobs/index.ts`
- [Publish worker](https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/_shared/publish-worker.ts): `supabase/functions/_shared/publish-worker.ts`
- [Social provider adapters](https://github.com/dev-wyp/lwal-kuu/blob/main/supabase/functions/_shared/providers.ts): `supabase/functions/_shared/providers.ts`

### Platform Services

- [Supabase client](https://github.com/dev-wyp/lwal-kuu/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- **Supabase backend**
- **Social platforms**

### Other components

- **Shop user**

## Connections

- Shop user → Application routes: opens app (evidence: `src/routes/index.tsx`)
- Application routes → Authentication: provides auth (evidence: `src/App.tsx`)
- Application routes → Organization context: provides organization (evidence: `src/App.tsx`)
- Application routes → Shop onboarding: routes onboarding (evidence: `src/routes/index.tsx`)
- Application routes → Shop dashboard: routes dashboard (evidence: `src/routes/index.tsx`)
- Application routes → Product catalog: routes catalog (evidence: `src/routes/index.tsx`)
- Application routes → Purchases and receiving: routes purchasing (evidence: `src/routes/index.tsx`)
- Application routes → Stock ledger: routes inventory (evidence: `src/routes/index.tsx`)
- Application routes → POS and invoices: routes POS (evidence: `src/routes/index.tsx`)
- Application routes → Customer ledgers: routes customers (evidence: `src/routes/index.tsx`)
- Application routes → Supplier accounts: routes suppliers (evidence: `src/routes/index.tsx`)
- Application routes → Customer payments: routes payments (evidence: `src/routes/index.tsx`)
- Application routes → Expense tracking: routes expenses (evidence: `src/routes/index.tsx`)
- Application routes → Business reports: routes reports (evidence: `src/routes/index.tsx`)
- Application routes → Platform administration: routes administration (evidence: `src/routes/index.tsx`)
- Authentication → Supabase client: queries auth (evidence: `src/context/AuthContext.tsx`)
- Organization context → Authentication: reads identity (evidence: `src/context/OrgContext.tsx`)
- Organization context → Supabase client: loads membership (evidence: `src/context/OrgContext.tsx`)
- Plan entitlements → Organization context: reads organization (evidence: `src/modules/subscription/useEntitlements.ts`)
- Plan entitlements → Supabase client: queries limits (evidence: `src/modules/subscription/useEntitlements.ts`)
- POS and invoices → Customer ledgers: records credit sales (evidence: `README.md`)
- Purchases and receiving → Stock ledger: increments stock (evidence: `README.md`)
- POS and invoices → Stock ledger: records movements (evidence: `README.md`)
- Customer payments → Customer ledgers: allocates receipts (evidence: `README.md`)
- POS and invoices → Business reports: feeds sales metrics (evidence: `README.md`)
- Application routes → Campaigns and content: routes marketing (evidence: `src/routes/index.tsx`)
- Campaigns and content → Marketing workspace: loads workspace (evidence: `src/modules/marketing/hooks/useMarketingWorkspace.ts`)
- Marketing workspace → Organization context: scopes workspace (evidence: `src/modules/marketing/hooks/useMarketingWorkspace.ts`)
- Marketing workspace → Supabase client: loads workspace data (evidence: `src/modules/marketing/hooks/useMarketingWorkspace.ts`)
- Campaigns and content → Marketing AI: requests AI features
- Campaigns and content → Social account OAuth: connects accounts
- Publishing jobs → Publish worker: dispatches jobs (evidence: `supabase/functions/marketing-jobs/index.ts`)
- Publish worker → Social provider adapters: selects adapter (evidence: `supabase/functions/_shared/publish-worker.ts`)
- Publish worker → Supabase backend: claims and updates jobs (evidence: `supabase/functions/_shared/publish-worker.ts`)
- Publish worker → Social platforms: publishes content (evidence: `supabase/functions/_shared/publish-worker.ts`)
- Supabase client → Supabase backend: reads and writes (evidence: `src/lib/supabase.ts`)
