Fluxora

Fluxora is a multi-tenant operations platform for food and wholesale distribution teams. It helps tenants manage customers, suppliers, products, lots, inventory, sales orders, invoices, payments, expenses, and user access from one workspace-scoped application. The app supports tenant subdomains, role-aware workflows, warehouse traceability, supplier receiving, sales order fulfillment, invoice generation, tenant branding, and file uploads backed by Cloudflare R2.

Documentation

Detailed guides live under docs/ so this page stays lean. Start here:

Topic	Doc
Index of all docs	docs/README.md
Local setup, env, subdomain routing, UAT	docs/local-development.md
Account signup vs onboarding, invites	docs/account-and-workspace-setup.md
Stripe (Checkout, Customer Portal, webhooks, CLI testing, catalog sync, signing secrets)	docs/stripe-subscriptions.md
Subscription system overview	docs/subscription-system-overview.md
Billing release checklist	docs/billing-release-checklist.md
Support tickets (tenant vs platform workflows)	docs/support-workflow.md
Business rules & permissions	docs/rules/README.md
Misc. workspace notes	docs/monorepo-notes.md

Tech stack

Layer	Technology
Framework	Next.js 16 (App Router, React 19)
Language	TypeScript 5
Styling	Tailwind CSS 4, shadcn/ui (Radix UI + Base UI primitives)
Auth	Better Auth — root, tenant, and platform-admin host auth
Database	Neon serverless Postgres
ORM	Drizzle ORM + Drizzle Kit
Data fetching	TanStack Query v5, TanStack Table v8
Forms	React Hook Form + Zod
Email	Resend + React Email
Charts / PDF	Recharts, @react-pdf/renderer
File storage	Cloudflare R2
Deployment	Vercel

Local dev (minimal)

See docs/local-development.md for host routing (localtest.me, admin. subdomain behavior) and UAT URLs.

1. pnpm install
2. Copy .env.local.example → .env.local — set at minimum DATABASE_URL, BETTER_AUTH_*, ROOT_DOMAIN; add Stripe vars if you exercise billing. For Subscription Checkout use STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET; configure STRIPE_PRICE_* ids or populate the Stripe catalog with metadata plan=starter, growth, or enterprise (stripe subscriptions).
3. pnpm db:migrate
4. pnpm dev

Billing in brief

Tenant billing is Stripe-backed. Workspace admins and owners start paid subscriptions from /account/billing using Stripe Checkout, then manage payment methods, invoices, and cancellation through Stripe Customer Portal once the workspace has a stored Stripe customer id. Stripe webhooks update the tenant’s plan, status, and billing dates, and the app uses those persisted fields for subscription health, access blocking, feature gating, and numeric plan limits.

Billing local test

To test billing locally, forward Stripe webhooks to the app with:

stripe listen --forward-to http://localtest.me:3000/api/stripe/webhook

Then sign in as a tenant owner or admin, open /account/billing, start Checkout, and verify the Billing page updates after webhook sync. See docs/stripe-subscriptions.md for setup details and docs/billing-release-checklist.md for the full launch checklist.

Layout

Domain logic lives under modules/ (see CLAUDE.md and docs/module-architecture.md for the rationale and full rules). The App Router carries thin route files that re-export from the owning module.

app/
  (app)/                          # Authenticated tenant app shell
    (subscription-guard)/         # Routes gated by an active subscription
      orders/, customers/, products/, inventory/, lots/,
      invoices/, supplier-invoices/, suppliers/, payments/,
      bill-payments/, expenses/, categories/, price-chart/,
      bank-activity/, inbox/, configuration/, units-of-measure/,
      (dashboard)/, (settings)/, settings/, support/,
      tenant-admin/, user-management/
    account/                      # User account & profile
    invoice-import/               # Marketing demo (PDF → order lines)
  (auth)/                         # Sign-in, sign-up, invite, password reset
  (marketing)/, pricing/, features/, changelog/, reel/
  (onboarding)/, onboarding/, select-destination/
  admin/                          # Platform-admin host (admin.<root>)
  api/                            # Better Auth, ERP APIs, Stripe + Plaid webhooks

modules/
  core/                           # Tenant-agnostic infra
    feature-flags/, tenants/, billing/, platform-admin/, workspace-settings/
  distribution/                   # Business vertical (each is self-contained:
    orders/, customers/, products/, inventory/, lots/,
    invoices/, supplier-invoices/, suppliers/, payments/,
    supplier-payments/, expenses/, categories/, units-of-measure/,
    price-chart/, configuration/, plaid/, inbox/, onboarding/
  shared/                         # Domain-agnostic primitives used by 2+ modules

components/                       # Shared React (app shell, auth, UI primitives)
  ui/                             # shadcn/ui components
db/                               # Drizzle schema, migrations, relations, seed
emails/                           # React Email templates
hooks/                            # Cross-cutting React Query hooks
lib/                              # Pure utilities, query keys, auth helpers
proxy.ts                          # Next.js 16 middleware (host routing, rate limits)

Each module's index.ts is its only public entry point — external code imports @/modules/distribution/orders, never the internals.

License

Copyright (C) 2026 Ikram Sarfraz.

Fluxora is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See LICENSE for the full text. Notably, if you run a modified version of this software as a network service, the AGPL requires you to make its complete source available to that service's users.