# ikramsarfraz/fluxora-oss architecture

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

- Interactive diagram: https://gitdiagram.com/ikramsarfraz/fluxora-oss
- Repository: https://github.com/ikramsarfraz/fluxora-oss

## Overview

Fluxora is a multi-tenant operations platform for food and wholesale distributors. Users enter a tenant workspace, then manage purchasing and receiving, inventory traceability, sales fulfillment, invoices, payments, and related finance operations. Tenant membership, roles, authentication, and subscription status frame access to those workflows; bank synchronization and platform administration are supporting capabilities. The graph combines README-described product stages with the sampled auth, database, invoice-parsing, and Plaid relationships. Several distribution modules are represented at their documented directory level because their implementation excerpts were not provided.

Main entry points: [`modules/distribution/supplier-invoices/services/parsing-pipeline.ts`](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/services/parsing-pipeline.ts) (Supplier invoices), [`lib/auth.ts`](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/lib/auth.ts) (Authentication), [`modules/distribution/plaid/services/transaction-sync.ts`](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/plaid/services/transaction-sync.ts) (Bank synchronization), [`modules/core/billing`](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/core/billing) (Tenant billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity & Workspace"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_membership["Tenant membership<br/>[portal-users.ts]"]
  node_tenant["Tenant context<br/>[tenants.ts]"]
  node_tenant_host["Tenant host routing<br/>[tenant-host.ts]"]
end

subgraph group_distribution["Distribution Operations"]
  node_customers_products["Customers &amp; products"]
  node_supplier_invoices["Supplier invoices"]
  node_pdf_prefill["PDF prefill<br/>[pdf-prefill.ts]"]
  node_invoice_ai["Invoice AI extraction<br/>[ai-provider.ts]"]
  node_invoice_normalize["Line normalization<br/>[normalization.ts]"]
  node_review_mapping["Invoice review mapping"]
  node_inventory_lots["Inventory &amp; lots"]
  node_orders["Sales orders"]
  node_invoices["Sales invoices"]
end

subgraph group_finance["Finance &amp; Integrations"]
  node_payments_expenses["Payments &amp; expenses"]
  node_bank_sync["Bank synchronization"]
  node_plaid_api["Plaid API"]
end

subgraph group_platform["Platform Services"]
  node_billing["Tenant billing"]
  node_stripe["Stripe"]
  node_database[("Application database<br/>[schema.ts]")]
  node_db_client["Database client<br/>[index.ts]"]
  node_platform_admin["Platform administration"]
end

node_user(("Workspace user"))

node_user -->|"signs in"| node_auth
node_auth -->|"resolves workspace"| node_tenant
node_auth -->|"provisions access"| node_membership
node_tenant -->|"resolves host"| node_tenant_host
node_user -->|"manages records"| node_customers_products
node_user -->|"receives supplier bills"| node_supplier_invoices
node_supplier_invoices -->|"parses PDF text"| node_pdf_prefill
node_supplier_invoices -->|"extracts with vision"| node_invoice_ai
node_supplier_invoices -->|"normalizes lines"| node_invoice_normalize
node_supplier_invoices -->|"maps for review"| node_review_mapping
node_user -->|"tracks stock"| node_inventory_lots
node_user -->|"fulfills orders"| node_orders
node_user -->|"generates invoices"| node_invoices
node_user -->|"records finances"| node_payments_expenses
node_user -->|"connects bank"| node_bank_sync
node_plaid_api -->|"sends updates"| node_bank_sync
node_bank_sync -->|"fetches transactions"| node_plaid_api
node_user -->|"manages subscription"| node_billing
node_billing -->|"uses billing services"| node_stripe
node_stripe -->|"updates by webhook"| node_billing
node_db_client -->|"configures schema"| node_database
node_platform_admin -.->|"manages platform data"| node_database

click node_auth "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/lib/auth.ts"
click node_membership "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/shared/services/portal-users.ts"
click node_tenant "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/core/tenants/services/tenants.ts"
click node_tenant_host "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/lib/tenant-host.ts"
click node_customers_products "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution"
click node_supplier_invoices "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/services/parsing-pipeline.ts"
click node_pdf_prefill "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/utils/pdf-prefill.ts"
click node_invoice_ai "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/services/ai-provider.ts"
click node_invoice_normalize "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/utils/normalization.ts"
click node_review_mapping "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/components/review/map-pipeline-to-review-data.ts"
click node_inventory_lots "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution"
click node_orders "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution/orders"
click node_invoices "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution/invoices"
click node_payments_expenses "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution"
click node_bank_sync "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/plaid/services/transaction-sync.ts"
click node_billing "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/core/billing"
click node_database "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/db/schema.ts"
click node_db_client "https://github.com/ikramsarfraz/fluxora-oss/blob/develop/db/index.ts"
click node_platform_admin "https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/core/platform-admin"

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_auth,node_membership,node_tenant,node_tenant_host,node_user toneBlue
class node_customers_products,node_supplier_invoices,node_pdf_prefill,node_invoice_ai,node_invoice_normalize,node_review_mapping,node_inventory_lots,node_orders,node_invoices toneAmber
class node_payments_expenses,node_bank_sync,node_plaid_api toneMint
class node_billing,node_stripe,node_database,node_db_client,node_platform_admin toneRose
```

## Components

### Identity & Workspace

- [Authentication](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/lib/auth.ts): `lib/auth.ts`
- [Tenant membership](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/shared/services/portal-users.ts): `modules/shared/services/portal-users.ts`
- [Tenant context](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/core/tenants/services/tenants.ts): `modules/core/tenants/services/tenants.ts`
- [Tenant host routing](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/lib/tenant-host.ts): `lib/tenant-host.ts`

### Distribution Operations

- [Customers & products](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution): `modules/distribution`
- [Supplier invoices](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/services/parsing-pipeline.ts): `modules/distribution/supplier-invoices/services/parsing-pipeline.ts`
- [PDF prefill](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/utils/pdf-prefill.ts): `modules/distribution/supplier-invoices/utils/pdf-prefill.ts`
- [Invoice AI extraction](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/services/ai-provider.ts): `modules/distribution/supplier-invoices/services/ai-provider.ts`
- [Line normalization](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/utils/normalization.ts): `modules/distribution/supplier-invoices/utils/normalization.ts`
- [Invoice review mapping](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/supplier-invoices/components/review/map-pipeline-to-review-data.ts): `modules/distribution/supplier-invoices/components/review/map-pipeline-to-review-data.ts`
- [Inventory & lots](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution): `modules/distribution`
- [Sales orders](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution/orders): `modules/distribution/orders`
- [Sales invoices](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution/invoices): `modules/distribution/invoices`

### Finance & Integrations

- [Payments & expenses](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/distribution): `modules/distribution`
- [Bank synchronization](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/modules/distribution/plaid/services/transaction-sync.ts): `modules/distribution/plaid/services/transaction-sync.ts`
- **Plaid API**

### Platform Services

- [Tenant billing](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/core/billing): `modules/core/billing`
- **Stripe**
- [Application database](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/db/schema.ts): `db/schema.ts`
- [Database client](https://github.com/ikramsarfraz/fluxora-oss/blob/develop/db/index.ts): `db/index.ts`
- [Platform administration](https://github.com/ikramsarfraz/fluxora-oss/tree/develop/modules/core/platform-admin): `modules/core/platform-admin`

### Other components

- **Workspace user**

## Connections

- Workspace user → Authentication: signs in (evidence: `README.md`)
- Authentication → Tenant context: resolves workspace (evidence: `lib/auth.ts`)
- Authentication → Tenant membership: provisions access (evidence: `lib/auth.ts`)
- Tenant context → Tenant host routing: resolves host (evidence: `modules/core/tenants/services/tenants.ts`)
- Workspace user → Customers & products: manages records (evidence: `README.md`)
- Workspace user → Supplier invoices: receives supplier bills (evidence: `README.md`)
- Supplier invoices → PDF prefill: parses PDF text (evidence: `modules/distribution/supplier-invoices/services/parsing-pipeline.ts`)
- Supplier invoices → Invoice AI extraction: extracts with vision (evidence: `modules/distribution/supplier-invoices/services/parsing-pipeline.ts`)
- Supplier invoices → Line normalization: normalizes lines (evidence: `modules/distribution/supplier-invoices/services/parsing-pipeline.ts`)
- Supplier invoices → Invoice review mapping: maps for review (evidence: `modules/distribution/supplier-invoices/components/review/map-pipeline-to-review-data.ts`)
- Workspace user → Inventory & lots: tracks stock (evidence: `README.md`)
- Workspace user → Sales orders: fulfills orders (evidence: `README.md`)
- Workspace user → Sales invoices: generates invoices (evidence: `README.md`)
- Workspace user → Payments & expenses: records finances (evidence: `README.md`)
- Workspace user → Bank synchronization: connects bank (evidence: `README.md`)
- Plaid API → Bank synchronization: sends updates
- Bank synchronization → Plaid API: fetches transactions (evidence: `modules/distribution/plaid/services/transaction-sync.ts`)
- Workspace user → Tenant billing: manages subscription (evidence: `README.md`)
- Tenant billing → Stripe: uses billing services (evidence: `README.md`)
- Stripe → Tenant billing: updates by webhook
- Database client → Application database: configures schema (evidence: `db/index.ts`)
- Platform administration → Application database: manages platform data