oceans2alaska
25e660dfa9
Some checks failed
CI / verify (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
86 lines
3.6 KiB
Markdown
86 lines
3.6 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. Interactive analytics drill-downs let you inspect inventory value, revenue, freshness, and at-risk exposure by branch, category, and product. 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.
|