# Rapid Prototype Design

## Confirmed implementation choices

- Front end: Next.js PWA-style web app for fastest shared mobile and desktop delivery
- Backend: Fastify with TypeScript
- AI layer: OpenAI-ready orchestration with heuristic fallback in the absence of credentials
- CRM boundary: backend-only integration, never direct client-to-SuiteCRM
- Confirmation model: every write is staged as a proposal and must be confirmed before application
- Identity model: human app user for sign-in and audit, dedicated SuiteCRM service user for technical writes

## Why "Sales Leads may map to Cases"

Anglo-Suisse Capital users may refer to the workflow as Sales Leads, while SuiteCRM may expose that workflow under a different module such as `Cases`. The prototype therefore uses:

- user-facing language: always `Sales Leads`
- CRM integration language: configurable module name and field mapping

## Why exact field names are still open

SuiteCRM instances often use a mix of standard and custom fields. For this reason, the scaffold does not hardcode the final production field IDs for:

- assignee
- status or stage
- source
- campaign
- `Client notes`

Instead, these are parameterised in environment config.

## Current data flow

1. User signs in to the app.
2. User submits a Sales Lead instruction.
3. Backend interprets the instruction into structured data.
4. Business rules validate the interpretation.
5. If needed, the backend returns clarification or record selection.
6. If valid, the backend returns a confirmation proposal.
7. On confirmation, the SuiteCRM adapter applies the write and logs the action.

## Current gaps

- no database yet
- prototype persistence is file-backed, not database-backed
- uploaded files are stored locally in `prototype-data/uploads`
- image OCR is not enabled yet
- SuiteCRM live transport is mocked until credentials and API details are available
- app auth is demo-mode only; production auth remains pluggable
