An enterprise-grade, multi-tenant retail management SaaS platform engineered with Next.js 15, React 19, Supabase, and PostgreSQL Row-Level Security.
- Product Overview
- Current Development Status
- Feature Roadmap
- Technology Stack
- Architecture Overview
- Security Architecture
- Database Design
- Project Structure
- Prerequisites
- Installation and Local Setup
- Environment Variables
- Running the Application
- Testing and Verification
- Development Workflow
- Contributing
- License
Retail businesses frequently struggle with fragmented operational tooling: one system for point-of-sale, another for inventory, spreadsheets for tracking employees, and disjointed software for analytics. This fragmentation creates data silos, causes stock discrepancies, slows checkout throughput, and limits operational visibility.
BizFlow AI is designed to solve this by providing a unified, multi-tenant retail management platform. The long-term product vision encompasses:
- Centralized store and branch management across multiple retail locations.
- Real-time inventory tracking with immutable stock movement audit trails.
- High-efficiency Point of Sale (POS) with receipt issuance and cash-drawer management.
- Granular Role-Based Access Control (RBAC) separating Owners, Admins, Managers, and Cashiers.
- AI-assisted business workflows, automated reordering suggestions, and executive operational insights.
The platform is being constructed using Spec-Driven Development (SDD) with formal constitutional rules and strict verification gates.
All 65 tasks across Feature 001 are fully implemented and verified against automated unit, integration, and end-to-end test suites:
- Authentication Infrastructure:
- Secure registration with client- and server-side Zod password complexity validation (min. 8 characters, uppercase, lowercase, numbers, special characters).
- Mandatory email verification gating; unverified accounts cannot create or access tenant workspaces.
- Credential authentication with constant-time anti-enumeration error handling.
- Supabase PKCE (Proof Key for Code Exchange) auth callbacks with open-redirect sanitization.
- Global session termination and single-device sign-out flows.
- Organization Onboarding & Provisioning:
- Store provisioning wizard with database-enforced ISO 3166-1 alpha-2 country, ISO 4217 currency, and IANA timezone validation.
- Creator-bound idempotency via
(created_by, client_mutation_id)composite constraints. - Atomic database transactions assigning the creator as
ownerupon organization creation. - Single-owner invariant enforcement preventing organizations from ever becoming ownerless.
- Multi-Tenant Context & Routing:
- Multi-organization membership support: users can belong to multiple stores with independent roles.
- In-app organization switcher with dynamic workspace navigation.
- Persistent active organization tracking via sanitized
bizflow_active_orgpreference cookies with deterministic oldest-membership fallback. - Server-side tenant context resolution (
getTenantContext()) in Next.js Server Components. - Anti-enumeration route protection: non-member or inactive store requests render
404 Not Foundrather than leaking tenant existence.
- Profile Management & Password Recovery:
- Personal profile viewing and editing with phone number formatting and validation.
- In-app authenticated password updates requiring current password verification and revoking other active sessions.
- Cryptographically verified password recovery flow utilizing Supabase Auth AMR claims.
- Atomic single-use recovery nonce tracking in PostgreSQL preventing concurrent replay attacks.
- Dedicated
RECOVERY_GRANT_SECRETcryptographically isolating recovery tokens from Supabase keys. - Global session revocation upon password reset across all active user devices.
All tasks across Feature 002 are fully implemented and verified against automated test suites:
- Granular Role-Based Access Control (RBAC):
- Predefined system roles (
owner,admin,manager,cashier) with granular, colon-delimited permissions (products:*,categories:*,inventory:*, etc.). - Database-enforced permission checks via
public.check_user_permission(org_id, auth.uid(), permission_key). - Dynamic Owner catalog override: organization owners hold full administrative capabilities dynamically across all catalog permissions.
- Role escalation prevention: users can only manage members and assign roles strictly below their own authority tier.
- Last-active-owner invariant enforcement (
P0008): organizations can never revoke or deactivate their final remaining active owner.
- Predefined system roles (
- Transactional Team Member Invitations:
- Email-based invitation workflow with cryptographic single-use token tracking.
- Expiration enforcement (7-day window) and status lifecycle (
pending,accepted,declined,revoked). - Idempotent invitation acceptance creating active memberships and role assignments within an atomic database transaction.
- Multi-tenant RLS isolation on
public.organization_invitationsandpublic.organization_memberships.
All tasks across Feature 003 are fully implemented and verified against automated test suites:
- Hierarchical Catalog & Category Management:
- Full CRUD operations for categories with case-insensitive unique naming within each tenant.
- Soft-archival lifecycle (
active,inactive,archived) with permanent SKU and barcode uniqueness reservation. - 13 standardized retail Units of Measure (
piece,kg,meter,box,pack,unit, etc.) with discrete vs. continuous classification. - Full-text search and trigram-accelerated index filtering via PostgreSQL
pg_trgm.
- Confidential Cost Separation & Security:
- Unit acquisition costs isolated in a dedicated 1:1 table
public.product_costs. - Enforced Row-Level Security requiring
products:read_costpermission; Cashiers receive zero cost or profit margin data. - Optimistic Concurrency Control (OCC) tracking using row
versioncounters to prevent silent overwrites. - Private Supabase Storage bucket (
product-images) with tenant-isolated RLS policies and dynamically signed 1-hour URLs.
- Unit acquisition costs isolated in a dedicated 1:1 table
All tasks across Feature 004 are fully implemented and verified with 905 passing automated tests:
- Dual-Tier Database Mutation Architecture:
- Layer 1 Core (
public._execute_inventory_mutation_core):SECURITY DEFINERfunction atomically locking inventory rows (FOR UPDATE), updating physical balances, inserting immutable movement records, snapshotting acquisition costs, and advancing OCCversion. - Layer 2 Gateway (
public.execute_stock_movement): Public RPC validating session authentication, active tenant membership, granular permissions (inventory:receive,inventory:adjust), quantity semantics (P0033), advisory locking, and canonical RFC 8785 idempotency.
- Layer 1 Core (
- Immutable Stock Movement Audit Ledger (Constitution Principle II):
- Every committed balance change writes an immutable audit record in
public.stock_movements. - Direct client mutations (
INSERT,UPDATE,DELETE) are unconditionally denied via RLS. - Deferrable tripartite foreign keys protect against orphaned movements while enabling atomic tenant purges.
- Every committed balance change writes an immutable audit record in
- Cycle-Count Stocktake & Zero-Delta Idempotency:
- Physical count reconciliations (
quantity_semantics = 'target_physical_count') calculate signed deltas atomically. - Zero-delta confirmations (physical count equals recorded inventory) are safely persisted in
public.zero_delta_stocktakesfor replay protection without generating artificial movement rows.
- Physical count reconciliations (
- Initial Opening Stock Singularity Guard:
- Opening stock is permitted strictly once per product lifecycle when zero prior movement history exists across all movement types (
P0026). - Prominent "Opening Stock" action button and guidance banner dynamically gated by movement history, active status, and receipt permissions.
- Opening stock is permitted strictly once per product lifecycle when zero prior movement history exists across all movement types (
- Low-Stock Alerts & Valuation Protection:
- Reorder point and reorder quantity threshold configuration with OCC versioning.
- Dynamic stock status alerts (
in_stock,low_stock,out_of_stock). - Dedicated acquisition cost snapshot table
public.stock_movement_costsrequiring dual permissions (inventory:read_valuationANDproducts:read_cost) to view monetary valuations.
┌────────────────────────────────────────────────────────────────────────┐
│ COMPLETED MILESTONES │
├────────────────────────────────────────────────────────────────────────┤
│ [x] Feature 001: Authentication, Onboarding & Multi-Tenant Foundation │
│ [x] Feature 002: Team Member Invitations & RBAC Management │
│ [x] Feature 003: Product Catalog & Category Taxonomy │
│ [x] Feature 004: Inventory & Stock Management │
└────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────┐
│ UPCOMING MILESTONES │
├────────────────────────────────────────────────────────────────────────┤
│ [ ] Feature 005: Customers, Sales & Point of Sale (POS) Checkout │
│ [ ] Feature 006: Invoicing, Receipts, Tax Compliance & Returns │
│ [ ] Feature 007: Expense Management & Financial Ledger │
│ [ ] Feature 008: Business Intelligence, Analytics & AI Assistant │
└────────────────────────────────────────────────────────────────────────┘
- Next.js 15.1.6: React framework utilizing the App Router, React Server Components (RSC), Server Actions, and Edge Middleware.
- React 19.0.0 / React DOM 19.0.0: Foundation for interactive component state, server rendering, and form action primitives.
- TypeScript 5.7.3: Strict static type checking with zero
anyassertions across all application and test code.
- Tailwind CSS 3.4.17: Utility-first styling framework.
- Lucide React 0.474.0: Accessible iconography suite.
- clsx 2.1.1 & tailwind-merge 2.6.0: Dynamic CSS class composition and conflict resolution.
- React Hook Form 7.54.2: High-performance, un-opinionated form state management.
- Zod 3.24.1: Schema-first validation library enforcing contracts at runtime boundaries across forms, server actions, and environment variables.
- @hookform/resolvers 3.10.0: Zod validation integration bridge for React Hook Form.
- PostgreSQL 17: Relational database engine configured via the local Supabase CLI stack.
- Supabase Auth (GoTrue): User identity service with PKCE email confirmations, recovery flows, and JWT issuance.
- @supabase/ssr 0.5.2: Cookie-based server client adapter for Next.js App Router and Server Actions.
- @supabase/supabase-js 2.48.1: Isomorphic Supabase client library.
- pg 8.23.1: PostgreSQL client driver for direct database verification in test suites.
- Vitest 3.0.4: Unit and integration test runner executing across Node.js and JSDOM environments.
- @testing-library/react 16.2.0: Component behavior testing primitives.
- Playwright 1.50.1: Headless Chromium end-to-end browser test automation framework.
- ESLint 9.19.0 & eslint-config-next 15.1.6: Static code analysis and linting.
BizFlow AI enforces strict separation between client-side rendering, server-side authorization, and database-level multi-tenancy.
flowchart TD
Client["Client Browser\n(React 19 / Client Components)"]
subgraph Edge["Next.js Server Runtime (App Router)"]
MW["Edge Middleware (src/middleware.ts)\n• Session token refresh\n• Unauthenticated redirects\n• Safe return URL preservation"]
SC["Server Components & Layouts\n• src/app/[slug]/layout.tsx\n• src/app/(auth)/*\n• src/app/settings/*"]
TC["Tenant Context Guard (src/lib/auth/context.ts)\n• getUser() verified identity\n• Email confirmation check\n• Active org & membership resolution\n• 404 anti-enumeration on unauthorized"]
SA["Server Actions (src/actions/*)\n• auth-actions.ts\n• organization-actions.ts\n• profile-actions.ts\n• Zod runtime validation"]
end
subgraph SupabasePlatform["Supabase & PostgreSQL Platform (Docker Local / Cloud)"]
AuthSvc["Supabase GoTrue Auth Server\n• Cryptographic JWT signing\n• PKCE authorization exchange\n• Global session revocation"]
subgraph PostgresEngine["PostgreSQL Database (Port 54322)"]
RLS["Universal FORCE ROW LEVEL SECURITY\n• profiles (own & peer read, own update)\n• organizations (member-only read)\n• organization_memberships (deny-all direct client mutation)\n• organization_audit_events (deny-all direct mutation)\n• recovery_grants (deny-all direct client access)"]
DBRPC["Stored Procedures & Triggers (SECURITY DEFINER)\n• create_organization_with_owner()\n• create_recovery_grant()\n• verify_recovery_grant()\n• consume_recovery_grant() (atomic row lock)\n• trg_check_owner_invariant"]
Tables["PostgreSQL Tables\n• profiles\n• organizations\n• organization_memberships\n• organization_audit_events\n• recovery_grants"]
end
end
Client -->|"HTTPS / Cookie Session"| MW
MW -->|"Session Refreshed"| SC
MW -->|"API Route / PKCE Exchange"| AuthSvc
SC --> TC
SC --> SA
TC -->|"Authenticated Client (ANON key + Cookie)"| RLS
SA -->|"Zod Validated Mutation"| DBRPC
DBRPC --> Tables
RLS --> Tables
AuthSvc -.->|"Session & AMR verification"| SC
- Server Actions for Mutations: All state modifications (registration, sign-in, store creation, profile edits, password resets) occur via Next.js Server Actions with strict Zod validation before database execution.
- Server-Side Tenant Resolution: Workspace routes (
src/app/[slug]/...) resolve tenant access server-side viagetTenantContext(). Client-supplied tenant IDs or cookies are never trusted for authorization. - Database as the Ultimate Authority: Even if application code were compromised, PostgreSQL Row-Level Security prevents cross-tenant data leakage.
The platform adheres to non-negotiable security requirements defined in the BizFlow AI Constitution:
- PostgreSQL Row-Level Security with FORCE RLS:
All tenant tables have
ENABLE ROW LEVEL SECURITYandFORCE ROW LEVEL SECURITY. This ensures RLS rules apply to table owners and authenticated clients alike, guaranteeing that no query returns data outside the caller's active memberships. - Deny-All Direct Client Mutations on Memberships:
organization_membershipsdenies direct clientINSERT,UPDATE, andDELETEvia RLS policies (WITH CHECK (false)). Role modifications must execute through authorized, audited server stored procedures. - Single-Owner Invariant Protection:
A database trigger (
trg_check_owner_invariant) enforces an organization-level row lock on any role update or deletion. It is impossible to delete or demote the last remainingownerof an organization. - Creator-Bound Idempotency:
The
organizationstable enforces a composite unique constraint(created_by, client_mutation_id). Replaying an organization creation request returns the creator's existing store, preventing duplicate store creation while blocking other users from hijacking or discovering mutations. - Anti-Enumeration Gating:
- Authentication errors for non-existent vs. wrong-password credentials return generic alerts.
- Accessing unauthorized or closed tenant slugs triggers
notFound()(HTTP 404), preventing malicious actors from probing whether an organization exists. - Password reset requests return identical success notifications regardless of whether the email is registered.
- Atomic Single-Use Recovery Nonce Consumption:
Password reset links establish a cryptographic recovery grant stored in PostgreSQL (
recovery_grants). When resetting a password, an atomicUPDATEwith row locking consumes the grant. Concurrent requests with the same token race on the lock; exactly one succeeds, and the other is rejected withUNAUTHORIZED_RECOVERY. - Cryptographic JWT Verification:
The recovery pipeline validates authentication sessions using
supabase.auth.getUser(), requiring the Supabase Auth server to cryptographically verify token signatures, expiry, and AMR (method: "recovery") claims. - Decoupled Authoritative Profile Store:
public.profilesis the authoritative source of record for user profiles. Synchronization with Supabase Authuser_metadatais handled best-effort with non-fatal logging, eliminating distributed two-phase rollback hazards. - Dedicated Secrets & Zero Service-Role Exposure:
RECOVERY_GRANT_SECRETis a dedicated, server-only 256-bit secret (min 32 characters) used exclusively for signing and verifying recovery grants.SUPABASE_SERVICE_ROLE_KEYis never used as a recovery fallback and is never referenced in client-side bundles or client components. Client operations strictly use the Supabase Anon key combined with verified HTTP-only session cookies. - Clean Production Surface:
Temporary development/testing RPCs (such as
demote_member_role_for_testing) are permanently dropped from the database schema.
The PostgreSQL database schema is managed via sequential Supabase migrations in supabase/migrations/:
erDiagram
AUTH_USERS ||--|| PROFILES : "has profile (1:1)"
PROFILES ||--o{ ORGANIZATIONS : "created by (1:N)"
PROFILES ||--o{ ORGANIZATIONS : "closed by (0:1)"
PROFILES ||--o{ ORGANIZATION_MEMBERSHIPS : "belongs to (1:N)"
ORGANIZATIONS ||--|{ ORGANIZATION_MEMBERSHIPS : "has members (1:N)"
ORGANIZATIONS ||--o{ ORGANIZATION_AUDIT_EVENTS : "logs (1:N)"
PROFILES ||--o{ ORGANIZATION_AUDIT_EVENTS : "acted by (1:N)"
AUTH_USERS ||--o{ RECOVERY_GRANTS : "issues (1:N)"
PROFILES {
uuid id PK "references auth.users(id)"
text first_name "1-50 chars"
text last_name "1-50 chars"
text phone "nullable, 7-20 chars"
timestamptz created_at
timestamptz updated_at
}
ORGANIZATIONS {
uuid id PK
text name "2-100 chars"
text slug "unique"
text business_type "2-50 chars"
text country "ISO 3166-1 alpha-2"
text currency "ISO 4217"
text timezone "IANA timezone"
text tax_id "nullable"
text phone "nullable"
text email "nullable"
text address "nullable"
uuid created_by FK
uuid client_mutation_id "idempotency key"
boolean is_active "default true"
timestamptz closed_at "nullable"
uuid closed_by FK "nullable"
timestamptz created_at
timestamptz updated_at
}
ORGANIZATION_MEMBERSHIPS {
uuid id PK
uuid organization_id FK
uuid user_id FK
app_role role "owner | admin | manager | cashier"
membership_status status "active | suspended | revoked"
timestamptz created_at
timestamptz updated_at
}
ORGANIZATION_AUDIT_EVENTS {
uuid id PK
uuid organization_id FK
uuid actor_id FK
text event_type "1-100 chars"
jsonb metadata
timestamptz created_at
}
RECOVERY_GRANTS {
uuid id PK
uuid user_id FK
text session_id
text nonce_hash "unique SHA-256"
timestamptz expires_at
timestamptz consumed_at "nullable, single-use"
timestamptz created_at
}
public.app_role: Enum ('owner','admin','manager','cashier').public.membership_status: Enum ('active','suspended','revoked').
BizFlow-AI/
├── .specify/ # Spec Kit constitutional rules, scripts, & extensions
├── specs/ # Formal feature specifications & implementation plans
│ └── 001-auth-organization/ # Feature 001 spec, plan, tasks, data-model, & quickstart
├── src/
│ ├── actions/ # Server Actions (Zod-validated boundary mutations)
│ │ ├── auth-actions.ts # Sign-up, sign-in, sign-out, password recovery
│ │ ├── organization-actions.ts # Store creation, organization switching
│ │ └── profile-actions.ts # Profile updates, authenticated password change
│ ├── app/ # Next.js 15 App Router pages, layouts, & route handlers
│ │ ├── (auth)/ # Auth group (sign-in, sign-up, verify-email, etc.)
│ │ ├── api/auth/callback/ # PKCE authentication callback route handler
│ │ ├── onboarding/ # Store onboarding wizard pages
│ │ ├── settings/profile/ # User profile and account security settings
│ │ ├── [slug]/ # Multi-tenant workspace layouts and dashboards
│ │ ├── globals.css # Tailwind CSS styles and custom utilities
│ │ ├── layout.tsx # Root HTML layout shell
│ │ ├── not-found.tsx # Global 404 Not Found screen
│ │ └── page.tsx # Root landing redirect resolver
│ ├── components/ # Reusable React components
│ │ ├── auth/ # Auth forms (sign-in, sign-up, password reset)
│ │ ├── layout/ # Tenant header, organization switcher
│ │ ├── organization/ # Store creation forms
│ │ ├── settings/ # Profile editing & password change forms
│ │ └── ui/ # Accessible UI primitives (Button, Card, Input, etc.)
│ ├── lib/ # Shared business logic and platform adapters
│ │ ├── auth/ # Tenant context resolver, guards, recovery helpers
│ │ ├── supabase/ # SSR client, middleware client, server client
│ │ ├── validations/ # Zod schemas for auth and organization models
│ │ ├── env.ts # Runtime environment variable validation
│ │ └── utils.ts # CSS class merger utilities
│ ├── types/ # TypeScript type definitions
│ │ ├── auth.ts # Application domain types & action results
│ │ └── database.ts # Generated Supabase database schema types
│ └── middleware.ts # Edge middleware for session refresh & routing
├── supabase/
│ ├── config.toml # Local Supabase service definitions & port mappings
│ └── migrations/ # Ordered PostgreSQL migration files (01 through 08)
├── tests/
│ ├── e2e/ # Playwright end-to-end browser user journey tests
│ ├── integration/ # Vitest integration tests against local Supabase / RLS
│ ├── unit/ # Vitest unit tests for schemas, utilities, & components
│ └── setup.ts # Test environment initialization and matchers
├── .env.example # Template for required environment variables
├── next.config.ts # Next.js configuration
├── package.json # Package dependencies and npm scripts
├── playwright.config.ts # Playwright E2E configuration
├── tailwind.config.ts # Tailwind CSS design system tokens
├── tsconfig.json # Strict TypeScript compiler options
└── vitest.config.ts # Vitest test runner configuration
Before running the project locally, ensure the following software is installed:
- Node.js:
v20.xor later (tested on Node.js v22). - npm:
v10.xor later. - Git:
v2.xor later. - Docker Desktop: Required to run the local Supabase container stack (PostgreSQL, GoTrue, Mailpit).
- Supabase CLI: Required for database migration and local service management. You can install it globally or run it via
npx supabase:npm install -g supabase
Follow these steps to configure and run BizFlow AI on your local development machine:
git clone https://github.com/your-username/BizFlow-AI.git
cd BizFlow-AInpm installEnsure Docker Desktop is running, then start the Supabase local container services:
npx supabase startUpon startup, the Supabase CLI outputs your local service URLs and development keys:
- API URL:
http://127.0.0.1:54321 - GraphQL URL:
http://127.0.0.1:54321/graphql/v1 - DB URL:
postgresql://postgres:postgres@127.0.0.1:54322/postgres - Studio URL:
http://127.0.0.1:54323 - Inbucket / Mailpit:
http://127.0.0.1:54324 - anon key:
<your-local-anon-key> - service_role key:
<your-local-service-role-key>
Create a local environment file by copying .env.example:
cp .env.example .env.localPopulate .env.local with the values printed by supabase start:
# Supabase Public API (Accessible by client & server)
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
# Application Base URL (Used for auth redirects and callbacks)
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Supabase Service Role Key (Server-only; used for integration test seeding; NEVER exposed to browser)
SUPABASE_SERVICE_ROLE_KEY=your-local-service-role-key
# Dedicated Server-Only Recovery Secret (min 32 characters; NEVER exposed to browser)
RECOVERY_GRANT_SECRET=bizflow-local-recovery-grant-secret-at-least-32-chars-longWarning: Never commit
.env.localto version control. The repository's.gitignoreexplicitly excludes all.env*.localfiles.
Apply the sequential database migrations, triggers, and Row-Level Security policies:
npx supabase db resetThis applies migrations 01 through 08 cleanly onto your local PostgreSQL database.
npm run devOpen http://localhost:3000 in your browser to view the application.
| Variable | Scope | Purpose | Required | Default |
|---|---|---|---|---|
NEXT_PUBLIC_SUPABASE_URL |
Public / Browser | URL of the Supabase API Gateway | Yes | http://127.0.0.1:54321 |
NEXT_PUBLIC_SUPABASE_ANON_KEY |
Public / Browser | Anonymous API key safe for browser client requests | Yes | — |
NEXT_PUBLIC_APP_URL |
Public / Browser | Root URL of the Next.js app for auth callbacks | No | http://localhost:3000 |
RECOVERY_GRANT_SECRET |
Server-Only | Dedicated 256-bit secret (min 32 chars) for recovery token HMAC signing | Yes | — |
SUPABASE_SERVICE_ROLE_KEY |
Server-Only | Privileged admin key for integration test harness seeding | Yes (Tests) | — |
All available scripts from package.json:
# Start local Next.js development server with hot-reload
npm run dev
# Compile an optimized production build
npm run build
# Start production server from compiled build
npm run start
# Run strict TypeScript compiler verification without emitting files
npm run typecheck
# Run Next.js and ESLint code quality checks
npm run lint
# Run all unit tests with Vitest
npm run test:unit
# Run all integration tests against local Supabase / RLS
npm run test:integration
# Run all tests (unit + integration)
npm test
# Run Playwright end-to-end browser test suites
npm run test:e2eBizFlow AI maintains a comprehensive, three-tier automated verification architecture. Over 1,440 automated tests cover the platform:
================================================================================
Test Category Runner Scope Count Result
================================================================================
Unit Tests Vitest Schemas, utilities, components 905 PASS
Integration Tests Vitest Real Supabase JWT / RLS / RPCs 500 PASS
End-to-End Tests Playwright Full browser user journeys 38 PASS
────────────────────────────────────────────────────────────────────────────────
Total Automated Tests Passing: 1,443 PASS
================================================================================
- Validates Zod boundary schemas: registration, sign-in, ISO country/currency rules, profile edits, password complexity.
- Tests foundational UI primitives (
Button,Card,Input,Form,Alert). - Tests environment variable validation and safe redirect URL sanitization.
- Tests dedicated recovery grant secret isolation: enforces minimum 32 characters, prevents fallback to other keys, and verifies token minting and signature validation.
- Executes against the live local PostgreSQL instance using real Supabase JWT sessions.
- RLS Multi-Tenant Isolation: Confirms User A cannot read or modify User B's store data under
FORCE ROW LEVEL SECURITY. - Membership Direct Mutation Denial: Verifies direct client
INSERT/UPDATE/DELETEcalls are rejected with 0 rows affected. - Creator-Bound Idempotency: Asserts replaying store creation with the same
client_mutation_idreturns the existing store without duplicating rows. - Atomic Single-Use Recovery Nonce Consumption: Concurrently executes two password reset submissions with the same grant; verifies PostgreSQL row locks allow exactly one to succeed while rejecting the competitor.
- Profile Decoupling: Verifies profile updates persist authoritatively even if auth metadata sync fails.
Playwright tests simulate complete user journeys across Chromium:
auth-flow.spec.ts: Registration, verification pending card, email resend, invalid credentials rejection, and route protection.onboarding-flow.spec.ts: Store creation wizard, inline form validation, store provisioning, and dashboard transition.organization-switch.spec.ts: Multi-store navigation, organization switching, active preference cookie persistence, fallback resolution, and tampered cookie rejection.profile-password.spec.ts: Profile detail editing, in-app password changes, and complete email link password recovery with session revocation.tenant-isolation.spec.ts: Cross-tenant URL slug tampering rejection, suspended user gating, and verified tenant context resolution.
The project follows Spec-Driven Development (SDD) with structured specifications located in specs/:
- Constitution & Principles:
.specify/memory/constitution.mdsets non-negotiable architectural rules (PostgreSQL RLS, financial invariants, strict TypeScript, server-side authorization). - Feature Branching: Development proceeds on dedicated feature branches (e.g.,
001-auth-organization). - Specification & Contracts: Before implementation,
spec.md,plan.md,data-model.md, and contracts incontracts/define requirements and acceptance scenarios. - Task-Driven Execution:
tasks.mdbreaks implementation into sequential phases with explicit dependencies and checkpoints. - Quality Gates: Every pull request must satisfy the seven mandatory verification gates: clean database migration, typecheck, lint, unit tests, integration tests, E2E tests, and production build.
Contributions from collaborators and team members are welcome. Please follow this workflow:
- Check Prerequisites: Ensure Docker Desktop and the Supabase CLI are operational.
- Create a Feature Branch:
git checkout -b feature/your-feature-name
- Adhere to Code Standards:
- Write strict TypeScript with zero
anyassertions. - Validate all server action inputs using Zod.
- Maintain multi-tenant isolation; never query tenant tables without enforcing
organization_idvia RLS.
- Write strict TypeScript with zero
- Run Verification Gates:
npm run typecheck npm run lint npm run test:unit npm run test:integration npm run test:e2e npm run build
- Submit a Pull Request: Provide a detailed description of the changes, referencing the relevant specification or issue.
This project is currently private and does not have an open-source license assigned. All rights are reserved. Unauthorized copying, distribution, modification, or commercial deployment of this software is strictly prohibited without prior written permission from the project owner.
BizFlow AI is engineered from the ground up for high reliability, strict multi-tenant security, and scalable retail operations. With Features 001 through 004 complete, the platform provides a verified, production-grade foundation ready for Feature 005 (Customers, Sales & Point of Sale).