Guia dev completo

Documentation Index

Fetch the complete documentation index at: https://docs.pingoai.com.br/llms.txt

Use this file to discover all available pages before exploring further.

​

Objetivo desta pagina

Se um dev novo pegar apenas esta documentacao, ele deve conseguir:

• subir o ambiente
• entender a arquitetura
• localizar qualquer parte do codigo
• implementar features em backend, channel e frontend
• criar migration/seed com seguranca
• debugar erro de request, socket, fila e integracao

​

1) Mapa do monorepo

Raiz: C:\Users\guilh\crm

• Backend-1: API principal, auth, regras de negocio, socket, event bus e workers.
• channel-2: integracoes de canais (Baileys/Meta), consumers/producers Rabbit e bus de eventos.
• frontend: app React com rotas, paginas, hooks, contextos e componentes.
• deploy: infraestrutura Docker (Traefik, Postgres, Redis, RabbitMQ, MinIO, backend, channel, frontend, transcricao).
• scripts: instaladores automatizados para deploy.

​

2) Fluxo completo da aplicacao

1. Usuario aciona tela no frontend.
2. Frontend chama endpoint HTTP no backend.
3. Backend executa regra de negocio (service/model) e pode publicar em Rabbit.
4. Channel consome eventos/fila e conversa com canal externo.
5. Channel devolve resposta/notificacao para backend.
6. Backend emite evento via Socket.IO.
7. Frontend atualiza interface em tempo real no ExclusiveDay.

​

3) Como navegar no backend (Backend-1)

Arquitetura principal:

• src/server.ts: bootstrap do servidor, fila, crons, socket init.
• src/app.ts: middlewares globais, CORS, erro global, registro de rotas.
• src/routes/index.ts: agregador de todos os modulos de rota.
• src/controllers: camada HTTP.
• src/services: regra de negocio.
• src/models: entidades Sequelize.
• src/middleware/isAuth.ts: validacao de token.
• src/libs/socket.ts: namespaces e eventos Socket.IO.

Padrao de implementacao de endpoint:

1. Criar service em src/services/<Dominio>Services.
2. Criar/ajustar controller em src/controllers.
3. Criar rota em src/routes/<dominio>Routes.ts.
4. Registrar no src/routes/index.ts.
5. Se precisar realtime, emitir via getIO() (socket).

​

4) Como navegar no channel (channel-2)

Arquitetura principal:

• src/server.ts: bootstrap do channel, start do bus e inicializacao dos consumers.
• src/bus-rabbitmq/bus-rabbitmq.ts: registro dos handlers de comandos/eventos.
• src/bus-rabbitmq/rabbitmq-transport.ts: retry, DLQ, bind exchange/queue.
• src/handlers: handlers de comandos (baileys/meta/schedule/campaign).
• src/consumers: consumers RPC diretos.
• src/producers: envio direto para filas.
• src/services/flow: logica de flow builder no channel.

Padrao para nova integracao:

1. Criar command/event + handler em src/handlers.
2. Registrar handler no bus-rabbitmq.ts.
3. Se for RPC direto, criar consumer em src/consumers e iniciar no server.ts.
4. Criar producer em src/producers para chamadas de outros servicos.

​

5) Como navegar no frontend (frontend)

Arquitetura principal:

• src/routes/index.js: rotas publicas e privadas.
• src/layout/MainListItems.js: menu lateral e visibilidade por permissao/plano.
• src/pages: telas por modulo.
• src/components: componentes reutilizaveis.
• src/hooks: acesso a API e estado de dominio.
• src/context: auth, tickets, whatsapp etc.
• src/services/api.js: cliente HTTP.
• src/services/socket.js: cliente Socket.IO.

Padrao para nova tela/modulo:

1. Criar pagina em src/pages/<NovaTela>/index.js.
2. Adicionar rota em src/routes/index.js.
3. Adicionar item no menu em src/layout/MainListItems.js.
4. Criar hook de dados em src/hooks.
5. Integrar endpoints via src/services/api.js.

​

6) Migrations e seeds (backend + channel)

Backend:

• Migrations: Backend-1/src/database/migrations
• Seeds: Backend-1/src/database/seeds
• Comandos: npm run db:migrate e npm run db:seed

Channel:

• Migrations: channel-2/src/database/migrations
• Seeds: channel-2/src/database/seeds
• Comandos: npm run db:migrate e npm run db:seed

Observacao importante:

• O channel-2/package.json chama copy:migrations antes do migrate. Validar esse passo no ambiente antes de pipeline.

​

7) Mensageria (RabbitMQ) para dev

Filas de RPC entre backend e channel:

• check-contact-number-queue
• get-profile-picture-queue
• create-or-update-contact-queue
• notification-queue

Filas de event bus (por servico):

• backend-event-bus-queue
• channel-event-bus-queue

Referencia detalhada:

• essentials/eventos-rabbitmq

​

8) Como adicionar um modulo novo (fim a fim)

Checklist rapido:

1. Definir dominio (ex.: smart-campaigns).
2. Backend: rota + controller + service + model (se necessario).
3. Channel: producer/consumer/handler (se houver integracao externa).
4. Frontend: pagina + rota + menu + hook + componentes.
5. Banco: migration e seed quando aplicavel.
6. Tempo real: evento socket se a UI precisar de atualizacao imediata.
7. Docs: atualizar modulos-crm e este guia.

​

9) Debug por camada

​

Backend

• verificar src/server.ts e src/app.ts
• confirmar token em isAuth.ts
• inspecionar erro de service/controller nos logs
• validar emissao socket em libs/socket.ts

​

Channel

• confirmar start do bus em channel-2/src/server.ts
• validar RABBITMQ_URI e RABBITMQ_QUEUE_NAME
• checar handlers registrados no bus-rabbitmq.ts
• acompanhar retries/DLQ no transport custom

​

Frontend

• confirmar REACT_APP_BACKEND_URL
• checar interceptors/login em hooks/useAuth.js
• validar rota e permissao em routes/index.js e MainListItems.js
• checar assinatura de socket no hook do modulo

​

10) Convencoes de codigo observadas

• Controllers em PascalCaseController.ts.
• Services em pastas por dominio com sufixo Service.
• Rotas em camelCaseRoutes.ts.
• Models em PascalCase.ts.
• Uso de isAuth para proteger endpoints privados.
• Uso de companyId como particionamento funcional em varios fluxos.

​

11) Roteiro de onboarding para dev novo (1 dia)

1. Subir stack (quickstart) ou ambiente local (development).
2. Rodar migrations e seeds.
3. Login admin e navegar modulos principais.
4. Ler arquitetura-backend-frontend.
5. Ler eventos-rabbitmq.
6. Implementar uma alteracao pequena em um modulo (backend + frontend).
7. Validar fluxo com socket/mensageria quando aplicavel.

Com isso, o dev ja consegue evoluir qualquer area do ExclusiveDay com autonomia.