Build the Solaire inventory intelligence MVP

Add the tenant-ready dashboard, freshness and pricing analytics, mock integration adapters, persistence schema, and verification tooling needed for the initial pilot.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,36 +1,85 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Solaire Inventory Intelligence
 
-## Getting Started
+Solaire is a single-customer pilot for understanding produce inventory health, freshness risk, branch and salesperson performance, and advisory pricing opportunities. It currently runs on deterministic demo data and is structured to connect to Odoo Inventory and Salesforce later.
 
-First, run the development server:
+## What is included
+
+- Friendly, responsive overview with inventory value, revenue, sell-through, and freshness risk
+- Batch-level stock health estimated from received date and configurable product shelf life
+- Product, branch, and salesperson performance views
+- Explainable pricing and promotion recommendations with protected margin floors
+- Odoo and Salesforce adapter boundaries plus working mock syncs
+- Tenant-scoped PostgreSQL schema, signed pilot sessions, CI, Docker, and automated tests
+
+Pricing is advisory only. Solaire does not write price changes to external systems.
+
+## Run locally
+
+Requirements: Node.js 22+ and npm.
 
 ```bash
+npm install
+cp .env.example .env.local
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open http://localhost:3000. Demo mode does not require a database.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+To exercise authentication, set `REQUIRE_AUTH=true`. The default pilot login is:
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+- Email: `demo@solaire.app`
+- Password: `solaire-demo`
 
-## Learn More
+Change all demo secrets before deployment.
 
-To learn more about Next.js, take a look at the following resources:
+## PostgreSQL and migrations
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+```bash
+docker compose up -d postgres
+npm run db:generate
+npm run db:migrate
+```
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+The UI intentionally uses the in-memory demo source until real integration credentials are available. The Drizzle schema is the persistence contract for the production sync service.
 
-## Deploy on Vercel
+## Quality checks
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```bash
+npm run check
+npm run build
+npx playwright install chromium
+npm run test:e2e
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+## Architecture
+
+- `src/app` — Next.js routes, APIs, and dashboard pages
+- `src/components` — reusable dashboard and interactive UI
+- `src/domain` — freshness, analytics, and pricing recommendation logic
+- `src/integrations` — normalized adapters, mock sources, and sync orchestration
+- `src/db` — tenant-aware Drizzle schema and PostgreSQL client
+- `src/lib/demo-data.ts` — repeatable pilot scenarios
+
+Every business entity carries an `organizationId`. The seeded pilot has one organization, but authorization boundaries, indexes, and source-system uniqueness constraints are ready for multiple tenants.
+
+## Real integration handoff
+
+### Odoo
+
+Confirm the customer’s Odoo version, hosting model, database name, and external API entitlement. Odoo 19+ can use JSON-2 with a bearer API key. Older supported versions require a version-specific XML-RPC/JSON-RPC adapter. Map products, warehouses/locations, received stock, quantities, and completed stock moves into Solaire’s normalized types.
+
+### Salesforce
+
+Create a Salesforce External Client App and dedicated integration user, then confirm which standard or custom objects represent branches, salespeople, completed orders, and line items. Mapping belongs in the adapter configuration; analytics must not depend on Salesforce object names.
+
+### Freshness assumptions
+
+The pilot does not claim sensor, harvest, or inspection data. Freshness is:
+
+`remaining shelf life = configured shelf-life days - days since received`
+
+Staff should always confirm physical quality before disposal, transfer, markdown, or promotion.
+
+## Deployment notes
+
+The Dockerfile uses Next.js standalone output. For production, provide PostgreSQL, a strong `SESSION_SECRET`, encrypted integration credentials, HTTPS, and a scheduled worker process for PostgreSQL-backed sync jobs. Add audit retention and secret rotation policies before onboarding additional customers.