oceans2alaska
135be480e5
Some checks failed
CI / verify (push) Has been cancelled
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>
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# Solaire Inventory Intelligence
|
||
|
||
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.
|
||
|
||
## 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
|
||
```
|
||
|
||
Open http://localhost:3000. Demo mode does not require a database.
|
||
|
||
To exercise authentication, set `REQUIRE_AUTH=true`. The default pilot login is:
|
||
|
||
- Email: `demo@solaire.app`
|
||
- Password: `solaire-demo`
|
||
|
||
Change all demo secrets before deployment.
|
||
|
||
## PostgreSQL and migrations
|
||
|
||
```bash
|
||
docker compose up -d postgres
|
||
npm run db:generate
|
||
npm run db:migrate
|
||
```
|
||
|
||
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.
|
||
|
||
## Quality checks
|
||
|
||
```bash
|
||
npm run check
|
||
npm run build
|
||
npx playwright install chromium
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 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.
|