Language: PT-BR | English

Plataforma de concierge digital para turismo no litoral do Piauí, com frontend React autenticado via Supabase, backend Fastify para orquestração segura e n8n como motor de automação e IA.

• Visão geral
• Arquitetura atual
• Fluxo do chat
• Estrutura do repositório
• Stack
• Ambiente local
• Variáveis de ambiente
• Contrato entre backend e n8n
• Persistência do histórico
• Deploy e operação
• Documentação complementar

O projeto foi organizado para separar claramente as responsabilidades:

• apps/frontend: aplicação web do cliente
• apps/backend: API autenticada para chat, SSE, histórico e integração com n8n
• supabase/: assets relacionados ao Supabase
• docs/: documentação de arquitetura e diagramas operacionais

O fluxo atual prioriza:

• autenticação e contexto do usuário no frontend e backend
• n8n como camada de automação e IA, sem expor segredos ao cliente
• persistência do histórico oficial no Supabase
• experiência de chat resiliente com cache local + reidratação remota

Frontend React
  |
  |  POST /api/chat/messages
  |  GET  /api/chat/events/:sessionId   (SSE)
  |  GET  /api/chat/history/:sessionId
  v
Backend Fastify
  |
  |  valida auth no Supabase
  |  carrega user_profiles
  |  persiste chat_sessions/chat_messages
  |  chama webhook do n8n
  v
n8n
  |
  |  processa mensagem
  |  usa Prompt Builder / Agent / Tools
  |  faz callback assíncrono
  v
Backend Fastify
  |
  |  POST /api/chat/callback
  |  publica SSE para o cliente
  |  persiste reply da assistente
  v
Frontend React

• autenticação do usuário via Supabase
• UI do chat
• cache local de sessão e transcript
• assinatura do stream SSE
• recuperação do histórico persistido

• validação de bearer token
• montagem de userInfo a partir de auth.users + user_profiles
• criação e isolamento de sessão por usuário
• orquestração do fluxo assíncrono com n8n
• persistência oficial do histórico no Supabase

• automação do atendimento
• montagem de prompt
• execução do modelo
• uso futuro de tools, como Google Places
• callback para o backend com processing, reply e error

1. o frontend autenticado envia message e sessionId para POST /api/chat/messages
2. o backend valida o token e monta userInfo
3. o backend registra a sessão no event bus e persiste a mensagem do usuário
4. o backend dispara o webhook do n8n
5. o backend devolve 202 Accepted imediatamente
6. o frontend abre SSE em GET /api/chat/events/:sessionId
7. o n8n processa e chama POST /api/chat/callback
8. o backend publica eventos buffering, processing, reply ou error
9. o frontend atualiza a UI em tempo real

• GET /healthz
• POST /api/chat
  • rota legada síncrona
• POST /api/chat/messages
  • rota principal do fluxo assíncrono
• GET /api/chat/events/:sessionId
  • SSE do atendimento
• GET /api/chat/history/:sessionId
  • histórico persistido da conversa
• POST /api/chat/callback
  • callback autenticado do n8n

concicerge/
├── apps/
│   ├── backend/
│   │   ├── src/
│   │   │   ├── config/
│   │   │   ├── lib/
│   │   │   ├── routes/
│   │   │   └── services/
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── frontend/
│       ├── public/
│       ├── src/
│       │   ├── components/
│       │   ├── contexts/
│       │   ├── lib/
│       │   └── services/
│       ├── Dockerfile
│       ├── nginx/
│       └── package.json
├── docs/
│   └── n8n-final-workflow-with-tools.svg
├── packages/
├── scripts/
├── supabase/
├── package.json
└── README.md

• React 19
• TypeScript
• Vite
• CSS Modules
• Supabase JS

• Node.js
• Fastify
• TypeScript
• Supabase JS

• Supabase self-hosted
• n8n self-hosted
• Docker
• Coolify
• Traefik

• Node.js 22+
• npm 10+
• instância Supabase acessível
• backend e frontend configurados com .env

npm install

npm run dev:frontend

Frontend local:

http://localhost:5173

npm run dev:backend

Backend local:

http://localhost:3000

npm run build:frontend
npm run build:backend

cd apps/frontend
npm run dev
npm run build
npm run preview
npm run lint

cd apps/backend
npm run dev
npm run build
npm run start

Arquivo base: apps/frontend/.env.example

Obrigatórias para login e fluxo principal:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_API_URL

Observações:

• quando VITE_API_URL está presente, o frontend usa o fluxo assíncrono com backend + SSE
• sem VITE_API_URL, o frontend pode cair no fluxo legado

Arquivo base: apps/backend/.env.example

Obrigatórias para o fluxo atual:

• PORT
• ALLOWED_ORIGIN
• SUPABASE_URL
• SUPABASE_ANON_KEY
• N8N_CHAT_WEBHOOK_URL
• N8N_CHAT_CALLBACK_SECRET
• N8N_CHAT_CHANNEL
• N8N_CHAT_SOURCE

Obrigatória para persistência oficial do histórico:

• SUPABASE_SERVICE_ROLE_KEY

Opcional:

• CHAT_BUFFER_WINDOW_MS

O backend envia ao webhook do n8n um payload limpo com:

{
  "message": "texto atual do cliente",
  "sessionId": "uuid",
  "channel": "web",
  "source": "concierge-web",
  "userInfo": {
    "id": "uuid",
    "email": "user@example.com",
    "fullName": "Nome do usuário",
    "preferredLanguage": "pt-BR",
    "originCity": "cidade",
    "interests": ["praia", "gastronomia"],
    "travelStyle": ["casal"],
    "budgetProfile": "luxo",
    "companionsSummary": "casal",
    "notes": null,
    "updatedAt": "2026-04-03T11:50:03.066265+00:00"
  }
}

O backend espera:

{
  "sessionId": "uuid",
  "status": "processing | reply | error",
  "reply": "texto final da assistente",
  "messageId": "uuid-opcional-mas-recomendado"
}

Fluxo principal recomendado:

1. Webhook
2. Payload
3. Callback Processing
4. Prompt Builder
5. Basic LLM Chain ou AI Agent
6. Reply Payload
7. CallBackReply
8. Respond to Webhook

Se houver tools:

• preferir AI Agent
• usar Call n8n Workflow Tool para integrações externas

Diagrama de referência:

• docs/n8n-final-workflow-with-tools.svg

O histórico oficial da conversa fica no Supabase:

• chat_sessions
• chat_messages

• mensagem do usuário em POST /api/chat/messages
• resposta da assistente em POST /api/chat/callback

Mensagens de onboarding local e saudações efêmeras do frontend permanecem fora do histórico oficial por decisão de produto. O contexto definitivo do usuário deve ficar em:

• auth.users
• user_profiles
• chat_sessions
• chat_messages

A UI usa duas camadas:

1. cache local por sessionId
2. reidratação remota por GET /api/chat/history/:sessionId

Isso melhora:

• refresh de página
• retomada de conversa
• resiliência contra latência momentânea do histórico remoto

Topologia atual recomendada:

GitHub
  |
  v
Coolify
  |
  +-- Frontend
  +-- Backend
  +-- n8n
  +-- Supabase

• frontend web
• backend Fastify
• n8n principal
• n8n worker / webhook, quando aplicável
• Supabase

Backend:

GET /healthz

• o backend precisa do mesmo ALLOWED_ORIGIN do frontend publicado
• SUPABASE_SERVICE_ROLE_KEY deve ficar apenas no backend
• N8N_CHAT_CALLBACK_SECRET deve ser conhecido só por backend e n8n
• se houver troca de usuário na mesma máquina, o frontend agora isola a sessão por identidade
• o backend faz recuperação defensiva para chat-session-owner-mismatch, gerando nova sessão quando necessário

• docs/n8n-final-workflow-with-tools.svg
• docs/README.md
• packages/README.md
• scripts/README.md

Este README descreve o estado atual do sistema orientado ao fluxo:

• frontend autenticado
• backend como camada de confiança
• n8n como automação e IA
• Supabase como identidade, perfil e histórico persistido

Se o fluxo de IA ou de tools mudar, atualize primeiro:

1. contrato do backend
2. payload do n8n
3. variáveis de ambiente
4. esta documentação

Back to top

Digital concierge platform focused on travel experiences in the Piauí coastline, with a React frontend authenticated through Supabase, a Fastify backend for secure orchestration, and n8n as the automation and AI runtime.

• Overview
• Current architecture
• Chat flow
• Repository structure
• Stack
• Local environment
• Environment variables
• Backend and n8n contract
• Chat history persistence
• Deployment and operations
• Additional documentation

The repository is organized around clear responsibility boundaries:

• apps/frontend: customer-facing web application
• apps/backend: authenticated API for chat, SSE, history, and n8n integration
• supabase/: Supabase-related assets
• docs/: architecture notes and operational diagrams

The current platform priorities are:

• authentication and user context handled in frontend and backend
• n8n as the automation and AI layer, without exposing secrets to the client
• official chat history persisted in Supabase
• resilient chat UX with local cache plus remote rehydration

React Frontend
  |
  |  POST /api/chat/messages
  |  GET  /api/chat/events/:sessionId   (SSE)
  |  GET  /api/chat/history/:sessionId
  v
Fastify Backend
  |
  |  validates auth with Supabase
  |  loads user_profiles
  |  persists chat_sessions/chat_messages
  |  calls n8n webhook
  v
n8n
  |
  |  processes the message
  |  uses Prompt Builder / Agent / Tools
  |  sends async callback
  v
Fastify Backend
  |
  |  POST /api/chat/callback
  |  publishes SSE to the client
  |  persists assistant reply
  v
React Frontend

• user authentication through Supabase
• chat UI
• local session and transcript cache
• SSE subscription
• persisted history recovery

• bearer token validation
• userInfo composition from auth.users + user_profiles
• per-user session creation and isolation
• async orchestration with n8n
• official history persistence in Supabase

• chat automation
• prompt composition
• model execution
• future tool usage, such as Google Places
• callback to the backend with processing, reply, and error

1. the authenticated frontend sends message and sessionId to POST /api/chat/messages
2. the backend validates the token and builds userInfo
3. the backend registers the session in the event bus and persists the user message
4. the backend dispatches the n8n webhook
5. the backend immediately returns 202 Accepted
6. the frontend opens SSE on GET /api/chat/events/:sessionId
7. n8n processes the request and calls POST /api/chat/callback
8. the backend publishes buffering, processing, reply, or error
9. the frontend updates the UI in real time

• GET /healthz
• POST /api/chat
  • legacy synchronous route
• POST /api/chat/messages
  • main asynchronous route
• GET /api/chat/events/:sessionId
  • SSE for chat delivery
• GET /api/chat/history/:sessionId
  • persisted chat history
• POST /api/chat/callback
  • authenticated n8n callback

concicerge/
├── apps/
│   ├── backend/
│   │   ├── src/
│   │   │   ├── config/
│   │   │   ├── lib/
│   │   │   ├── routes/
│   │   │   └── services/
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── frontend/
│       ├── public/
│       ├── src/
│       │   ├── components/
│       │   ├── contexts/
│       │   ├── lib/
│       │   └── services/
│       ├── Dockerfile
│       ├── nginx/
│       └── package.json
├── docs/
│   └── n8n-final-workflow-with-tools.svg
├── packages/
├── scripts/
├── supabase/
├── package.json
└── README.md

• React 19
• TypeScript
• Vite
• CSS Modules
• Supabase JS

• Node.js
• Fastify
• TypeScript
• Supabase JS

• self-hosted Supabase
• self-hosted n8n
• Docker
• Coolify
• Traefik

• Node.js 22+
• npm 10+
• accessible Supabase instance
• backend and frontend configured with .env

npm install

npm run dev:frontend

Local frontend:

http://localhost:5173

npm run dev:backend

Local backend:

http://localhost:3000

npm run build:frontend
npm run build:backend

cd apps/frontend
npm run dev
npm run build
npm run preview
npm run lint

cd apps/backend
npm run dev
npm run build
npm run start

Base file: apps/frontend/.env.example

Required for login and the main chat flow:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_API_URL

Notes:

• when VITE_API_URL is present, the frontend uses the asynchronous backend + SSE flow
• without VITE_API_URL, the frontend may fall back to the legacy path

Base file: apps/backend/.env.example

Required for the current flow:

• PORT
• ALLOWED_ORIGIN
• SUPABASE_URL
• SUPABASE_ANON_KEY
• N8N_CHAT_WEBHOOK_URL
• N8N_CHAT_CALLBACK_SECRET
• N8N_CHAT_CHANNEL
• N8N_CHAT_SOURCE

Required for official history persistence:

• SUPABASE_SERVICE_ROLE_KEY

Optional:

• CHAT_BUFFER_WINDOW_MS

The backend sends a normalized payload to the n8n webhook:

{
  "message": "latest user message",
  "sessionId": "uuid",
  "channel": "web",
  "source": "concierge-web",
  "userInfo": {
    "id": "uuid",
    "email": "user@example.com",
    "fullName": "User Name",
    "preferredLanguage": "pt-BR",
    "originCity": "city",
    "interests": ["praia", "gastronomia"],
    "travelStyle": ["casal"],
    "budgetProfile": "luxo",
    "companionsSummary": "casal",
    "notes": null,
    "updatedAt": "2026-04-03T11:50:03.066265+00:00"
  }
}

The backend expects:

{
  "sessionId": "uuid",
  "status": "processing | reply | error",
  "reply": "final assistant text",
  "messageId": "uuid-optional-but-recommended"
}

Recommended main flow:

1. Webhook
2. Payload
3. Callback Processing
4. Prompt Builder
5. Basic LLM Chain or AI Agent
6. Reply Payload
7. CallBackReply
8. Respond to Webhook

If tools are introduced:

• prefer AI Agent
• use Call n8n Workflow Tool for external integrations

Reference diagram:

• docs/n8n-final-workflow-with-tools.svg

Official conversation history lives in Supabase:

• chat_sessions
• chat_messages

• user messages in POST /api/chat/messages
• assistant replies in POST /api/chat/callback

Local onboarding prompts and ephemeral frontend greetings stay outside the official history by product decision. The definitive user context should live in:

• auth.users
• user_profiles
• chat_sessions
• chat_messages

The UI uses two layers:

1. local cache keyed by sessionId
2. remote rehydration via GET /api/chat/history/:sessionId

This improves:

• page refresh recovery
• conversation resumption
• resilience against temporary latency in remote history

Recommended production topology:

GitHub
  |
  v
Coolify
  |
  +-- Frontend
  +-- Backend
  +-- n8n
  +-- Supabase

• frontend web app
• Fastify backend
• main n8n instance
• n8n worker / webhook, when applicable
• Supabase

Backend:

GET /healthz

• the backend must allow the same ALLOWED_ORIGIN used by the published frontend
• SUPABASE_SERVICE_ROLE_KEY must stay backend-only
• N8N_CHAT_CALLBACK_SECRET must be shared only between backend and n8n
• when users switch accounts on the same machine, the frontend now isolates chat sessions by identity
• the backend performs defensive recovery for chat-session-owner-mismatch by issuing a new session when needed

• docs/n8n-final-workflow-with-tools.svg
• docs/README.md
• packages/README.md
• scripts/README.md

This README documents the current system as it actually operates:

• authenticated frontend
• backend as the trust boundary
• n8n as the automation and AI layer
• Supabase as identity, profile, and persisted chat history

If the AI flow or tool layer changes, update these in order:

1. backend contract
2. n8n payload shape
3. environment variables
4. this documentation

Back to top