BizMind AI

GCC Marketplace Profit Intelligence. Which marketplace and which product actually make you money — and where the rest of it went.

BizMind helps sellers on Amazon, noon and Carrefour understand sales, marketplace fees, product costs, advertising, operating expenses, profit, settlements, payouts and cash — from the marketplaces' own settlement data, recorded in an immutable line-level ledger. It is not an ERP and not a traditional accounting system.

---

Status

GCC Phase 1 — ledger foundation built and verified live.

The platform underneath is in place and tested: Supabase Auth, database-enforced tenant isolation, exact money handling, file import with lineage and withdrawal, a checked AI layer, an integration engine with Google Sheets, and rule-based alerts. Phase 1 added the immutable financial ledger, its single writer and the marketplace adapter contract. No marketplace parser exists yet; Amazon arrives in Phase 2. See ROADMAP.md and ARCHITECTURE_BASELINE.md.

---

Quick start

npm install
npm run dev

Then open http://localhost:3000.

Full instructions, including how secrets are handled, are in SETUP.md.

---

Commands

Command	Purpose
npm run dev	Local development server
npm run build	Production build — must pass before committing
npm run start	Serve the production build
npm run lint	Code quality checks — must pass before committing
npm run verify	Typecheck, lint, the offline test suites and build, in one go
npm run test:analytics-data	Analytics against the live database
npm run test:costs	Historical cost stability against the live database
npm run test:source-truth	Blank-is-not-zero and the semantics gate, live
npm run test:mapping	Canonical vocabulary and the suggestion engine
npm run test:mapping-data	Mapping gates, profiles and isolation, live
npm run test:migration-0010	Live contract test for the coverage-gap columns
npm run test:money-guard	Fails the build on any money arithmetic in TypeScript
npm run test:money-boundary	Proves exact decimals survive database → AI, live
npm run test:integration-engine	The engine and fixture connector, no database
npm run test:woocommerce	The WooCommerce connector, no store needed
npm run test:marketplaces	The adapter contract, customer-data filter and ledger payload, offline
npm run test:ledger	The ledger against the real database: immutability, one writer, isolation, withdrawal
npm run test:amazon	The Amazon Flat File V2 adapter, offline
npm run test:amazon-ledger	An invented Amazon settlement end to end against the real database
npm run test:amazon-acceptance -- <file> <file> …	The named real Amazon files reproduce July (local only; files never committed)
npm run test:classification	The classification model and its TypeScript/SQL parity, offline

---

Stack

Next.js 16 (App Router) · TypeScript · Tailwind CSS v4 · shadcn/ui on Radix · Supabase (PostgreSQL, Auth, RLS) · OpenAI · Vercel

---

Documentation

File	What it covers
CLAUDE.md	Permanent development rules. Read first.
ARCHITECTURE.md	How the system fits together
DESIGN.md	Colour, typography, spacing, chart rules
SETUP.md	Getting it running, and how secrets work
DATABASE.md	Schema, tenant isolation, migrations
INTEGRATIONS.md	Import pipeline and the connector contract
MAPPING.md	Canonical vocabulary, and why a column name is not a definition
AI.md	How the AI is stopped from ever producing a figure
MONEY.md	Why money is a string, and what keeps it exact
INTEGRATION_ENGINE.md	The sync and webhook engine connectors plug into
ARCHITECTURE_BASELINE.md

API.md is written as its phase lands.

---

Two rules worth knowing up front

Tenant isolation is enforced in the database. Every business-owned table has a business_id and Row Level Security. The database refuses cross-tenant reads even if application code is wrong.

The AI never calculates a business number. Every financial figure is computed by our own code and verified; the AI only explains figures it was given. A wrong number here would be worse than no number at all.

---

Deployment

Hosted on Vercel, built from the main branch on github.com/stargoldgdt-cyber/bizmind-ai. A push to main triggers a production deploy automatically. Production environment variables (Supabase, OpenAI, Google OAuth, CRON_SECRET) are set in the Vercel project's Environment Variables screen, not in this repo.