wave-link

Integra Jarvis (GoHighLevel) ai CRM dei clienti tramite un middleware ad adapter.

Stack

• Nx monorepo + pnpm + TypeScript
• apps/api: Fastify webhook API (Jarvis ingestion + auth + CRUD); entry main.ts → instrumentation.ts (OpenTelemetry opzionale, vedi .env.example)
• apps/web: React + Vite + Tailwind CSS + Lucide Icons admin console
• Prisma ORM + PostgreSQL per utenti, sessioni, flussi, mapping, inbox eventi, delivery tracking
• Redis/BullMQ per code delivery con retry esponenziale e stato DEAD_LETTER (se REDIS_URL assente, consegna inline come prima)

Workspace layout

• apps/api
• apps/web
• libs/core-domain
• libs/connectors
• libs/shared
• prisma/
• VERSION
• scripts/release.sh
• scripts/rollback.sh
• CHECKLIST.md
• docs/OBSERVABILITY_AND_TRACING_PLAN.md — piano tracciamento / debug / AI-friendly (pre-connettori)

MVP scope

• contact.created
• contact.updated
• appointment.created
• appointment.updated
• appointment.cancelled

Sync iniziale solo unidirezionale: Jarvis -> CRM esterno.

Current implementation status

• HubSpot adapter implementato in libs/connectors (contact + appointment methods).
• Login funzionante con session token persistito lato frontend.
• CRUD utenti (ADMIN) in webapp + API.
• Frontend mini-zapier con flow creation e import/export JSON (file + clipboard).
• Persistenza idempotency/event inbox su PostgreSQL via Prisma.
• Mapping campi Jarvis → modelli canonici per tenant/connettore/evento (FieldMapping + UI /mappings).
• Logging backend strutturato con request lifecycle.

First admin login

Se non esiste un admin, all'avvio API viene creato automaticamente:

• ADMIN_EMAIL (default admin@wavebridge.local)
• ADMIN_PASSWORD (default ChangeMe123!)

Cambiare subito le credenziali in produzione.

Environment variables

Copia .env.example in .env e compila i valori reali.

.env non è tracciato da git (.gitignore).

Database & migrations

Prisma gestisce il mapping modello -> tabelle.

Comandi utili:

pnpm db:generate
pnpm db:migrate:dev
pnpm db:migrate:deploy

All'avvio API vengono eseguite automaticamente le migrazioni con prisma migrate deploy.

Release flow (tags + environment branches)

Versione di deploy canonica in VERSION. package.json non pilota release o rollback.

Flusso standard:

• partire da main pulito
• creare il commit release che aggiorna VERSION
• creare il tag ambiente vX.Y.Z-test o vX.Y.Z-prod
• pushare main e il tag
• repuntare il branch remoto ambiente (test o production) a quel tag

Comandi:

pnpm release:test 1.0.0
pnpm release:prod 1.0.0

Rollback:

pnpm rollback:test 1.0.0
pnpm rollback:prod v1.0.0-prod

I branch ambiente sono il puntamento operativo usato da Dokploy; i tag ambiente restano il riferimento immutabile della release.

Prerequisiti iniziali:

• creare i branch remoti test e production
• configurare Dokploy per seguire test per l'ambiente di test e production per quello di produzione

Esempi Git diretti:

./scripts/release.sh test 1.0.0
./scripts/release.sh prod 1.0.0
./scripts/rollback.sh test 1.0.0
./scripts/rollback.sh prod v1.0.0-prod

Next tasks

Vedi CHECKLIST.md per task prioritizzate, stato avanzamento e roadmap integrazioni CRM (HubSpot, Salesforce, CRM in Cloud, Focus CRM, Treatwell, Optix, pattern export file).

Roadmap CRM (sintesi)

• Già in codice: adapter HubSpot e Salesforce (libs/connectors).
• Prossimi target API pubbliche: CRM in Cloud (TeamSystem), Optix — dopo consolidamento coda e mapping da DB.
• Focus iniziativa commerciale a tre: CRM in Cloud, Focus CRM (BluData), Treatwell (iCal + CSV contatti). Dettagli, vincoli e roadblock in CHECKLIST.md.