# Anglo-Suisse Capital CRM Assistant

Rapid prototype for an internal Anglo-Suisse Capital assistant focused on the Sales Leads workflow in SuiteCRM.

## What is scaffolded

- `apps/api`: Fastify API with:
  - demo sign-in
  - Cognito-ready bearer-token verification scaffolding
  - AI interpretation orchestration with OpenAI-ready and heuristic fallback modes
  - business-rule validation
  - confirmation-first proposal flow
  - persistent prototype state in `prototype-data/state.json`
  - document upload proposal endpoint with TXT, PDF and DOCX text extraction
  - selected Gmail proposal endpoint
  - server-side speech transcription endpoint ready for OpenAI audio transcription
  - follow-up task proposal preview linked to the selected Sales Lead
  - SuiteCRM adapter with mock mode plus live V8 scaffolding
  - SuiteCRM diagnostics endpoint for module and field discovery
  - audit logging
- `apps/web`: Next.js mobile-first interface with:
  - sign-in
  - chat/action home
  - browser-based voice dictation in supported browsers
  - recorded-audio upload for server-side transcription when configured
  - confirmation panel
  - Sales Lead search
  - Sales Lead detail
- `packages/domain`: shared Sales Lead terminology, schemas, and business rules
- `packages/ai`: prompt and structured-output schema helpers
- `packages/suitecrm`: config-driven SuiteCRM payload helpers

## Current prototype identity model

The prototype separates:

- app user identity: the real Anglo-Suisse Capital human using the app
- SuiteCRM integration identity: a dedicated service user such as `codex.crm.assistant`

This means the backend can write to SuiteCRM through one controlled technical account while still recording the real human actor for audit and using that human as the default assignee when required.

## Important SuiteCRM note

The user-facing object is always called `Sales Leads`, but the actual SuiteCRM module may be `Cases` or another module in the target instance. This is configurable through environment variables:

- `SUITECRM_MODULE_NAME`
- `SUITECRM_FIELD_SALES_LEAD_NAME`
- `SUITECRM_FIELD_ASSIGNEE`
- `SUITECRM_FIELD_STATUS`
- `SUITECRM_FIELD_SOURCE`
- `SUITECRM_FIELD_CAMPAIGN`
- `SUITECRM_FIELD_CLIENT_NOTES`

The defaults in this scaffold are placeholders only.

For live SuiteCRM V8 scaffolding, the API also supports:

- `SUITECRM_AUTH_TYPE=client_credentials` for an OAuth client associated with a dedicated SuiteCRM service user such as `codex.crm.assistant`
- `SUITECRM_AUTH_TYPE=password` when the target environment only exposes username/password grant flow

The Settings screen now calls the SuiteCRM diagnostics endpoint to check:

- whether live mode is enabled
- whether the configured SuiteCRM module exists
- which fields are returned for that module
- whether the configured Sales Leads field mapping appears to match the live metadata

## Running locally

1. Copy the root `.env.example` values into your local environment if needed, or use:
   - `.env.api.example` for the API
   - `.env.web.example` for the web app
2. Start the API:

```bash
npm run dev:api
```

3. Start the web app in a second terminal:

```bash
npm run dev:web
```

4. Open [http://localhost:3000](http://localhost:3000)

If `OPENAI_API_KEY` is configured, the app can send recorded audio to the backend for transcription using `OPENAI_TRANSCRIPTION_MODEL`. If it is not configured, browser dictation remains available where the browser supports it.

Recommended local setup for OpenAI:

- keep `OPENAI_API_KEY` in the API process environment only
- do not commit it into `.env.example`, source control, or client code
- the Settings screen and main chat screen will show whether live server-side OpenAI is enabled for instruction interpretation and recorded-audio transcription

## Auth modes

- `AUTH_MODE=demo`: enables the current demo sign-in flow for internal prototype users
- `AUTH_MODE=cognito`: disables demo sign-in and enables Cognito bearer-token verification on the API when these are configured:
  - `COGNITO_ISSUER`
  - `COGNITO_AUDIENCE` or `COGNITO_CLIENT_ID`

The web app now detects the current auth mode from the API. In Cognito mode, the login screen shows readiness status instead of pretending demo sign-in still works.

## Verified

- `npm install`
- `npm run test:api`
- `npm run typecheck:api`
- `npm run typecheck:web`
- runtime smoke test for:
  - demo login
  - selected Gmail proposal creation
  - document upload proposal creation
  - speech transcription endpoint fallback behavior

## Current automated tests

The API test suite currently covers:

- required `d mmm yyyy` prefix formatting for new `Client notes` entries
- heuristic separation of `Client notes` text from follow-up task requests
- confirmation preview generation for follow-up task proposals
- mock-mode SuiteCRM diagnostics behavior
- required campaign name validation when source is `Campaign`
- default auth diagnostics behavior in demo mode

## Additional delivery notes

- AWS deployment notes: `docs/technical/aws-deployment-notes.md`
- Phase 2 roadmap: `docs/product/phase-2-roadmap.md`
- Technical design: `docs/technical/rapid-prototype-design.md`

## Next implementation priorities

1. Replace file-backed prototype state with PostgreSQL and S3-backed uploads.
2. Add real OpenAI speech-to-text and richer document summarisation behind env flags.
3. Add live SuiteCRM authentication and transport once the target module and field names are confirmed.
4. Add Cognito or SSO-based production auth while keeping the SuiteCRM service user separate.
