Frontend — Chronicle

Visao Geral

SPA construida com Next.js 16 + React 18 + TypeScript + Tailwind CSS.

Stack: React Query (server state), Zustand (client state), @dnd-kit (drag & drop), WebSocket (tempo real).

---

Paginas

Auth

Rota	Descricao
/login	Login (email/senha + OTP + OAuth2)
/signup	Cadastro
/auth/callback	Callback OAuth2 (Google, GitHub)

Organizations

Rota	Descricao
/orgs	Lista de organizacoes
/orgs/new	Criar organizacao
/orgs/{orgId}/pipes	Pipes da organizacao
/orgs/{orgId}/members	Membros
/orgs/{orgId}/reports	Relatorios da org
/orgs/{orgId}/databases	Databases compartilhados

Pipes

Rota	Descricao
/orgs/{orgId}/pipes/new	Criar pipe
/orgs/{orgId}/pipes/{pipeId}/board	Quadro Kanban
/orgs/{orgId}/pipes/{pipeId}/editor	Configurar pipe
/orgs/{orgId}/pipes/{pipeId}/automations	Automacoes
/orgs/{orgId}/pipes/{pipeId}/forms	Formularios publicos
/orgs/{orgId}/pipes/{pipeId}/reports	Relatorios do pipe

Publico

Rota	Descricao
/forms/{slug}	Formulario publico (sem auth)
/invite/{token}	Aceitar convite

---

Board (Kanban)

Interface principal do Chronicle. Funcionalidades:

• Drag & drop de cards entre estagios (@dnd-kit)
• Busca e filtros por titulo, labels, status, atrasados
• Quick add — Criacao inline de cards
• Card drawer — Detalhe com campos, comentarios, arquivos, historico
• WIP limit — Indicador visual quando estagio atinge o limite
• WebSocket — Atualizacoes em tempo real

Interacao

1. Drag card → closestCorners collision
2. Drop → API cardsApi.move(cardId, stageId)
3. boardStore atualiza localmente (otimista)
4. WebSocket confirma para outros usuarios

---

State Management

Zustand Stores

authStore (persistido em localStorage):

{
  token: string | null
  user: User | null
  isAuthenticated: boolean
}

boardStore (sessao):

{
  pipeId, pipeName, pipeColor
  stages: Stage[]
  selectedCard: Card | null
  isDrawerOpen: boolean
}

orgStore (persistido em localStorage):

{
  currentOrg: Organization | null
}

---

API Client (lib/api.ts)

Base URL: NEXT_PUBLIC_API_URL (default: http://localhost:5040)

Interceptors:

• Request: Authorization: Bearer {token} + X-Organization-Id: {orgId}
• Response: 401 → limpa token + redireciona para /login

Modulos

Modulo	Endpoints
authApi	login, signup, OTP, OAuth2, me
organizationsApi	CRUD orgs + membros
pipesApi	CRUD pipes + archive/restore
stagesApi	CRUD stages + reorder
cardsApi	CRUD cards + move + search + dependencies
commentsApi	CRUD comentarios
filesApi	Upload/delete arquivos
fieldsApi	CRUD campos + reorder
automationsApi	CRUD automacoes + toggle
formsApi	CRUD formularios
publicFormsApi	Schema + submit (sem auth)
labelsApi	CRUD labels + add/remove de cards
reportsApi	Stats org + pipe + timeline
databasesApi	CRUD databases + fields + records
invitesApi	Convites + aceitar

---

Componentes Chave

Board

Componente	Funcao
BoardSearchBar	Busca de cards
BoardFilters	Filtros por estagio, labels, atrasados
StageHeader	Info do estagio + WIP limit
QuickAddCard	Criacao inline
PipeSettingsDrawer	Config do pipe

Cards

Componente	Funcao
CardDrawer	Detalhe do card com edicao
CardFiles	Gestao de arquivos
CardComments	Comentarios com threading
CardHistory	Timeline de mudancas

Editor

Componente	Funcao
StageEditor	Criar/editar estagios
FieldEditor	Configurar campos customizados
FieldConditionBuilder	Condicoes de visibilidade
PipeSettings	Metadata do pipe

Automations

Componente	Funcao
AutomationBuilder	Designer de automacoes
TriggerSelector	Selecao de trigger
ActionConfigurator	Config de acao

---

WebSocket

Hook: useBoardWebSocket(pipeId)

// Configuracao
URL: ws(s)://host/ws/board/{pipeId}
Reconnect: backoff [1s, 2s, 5s, 10s, 30s]
Ping: 30s interval, 10s timeout

Eventos atualizam automaticamente o boardStore.

---

Testes

Tipo	Ferramenta	Localizacao
E2E	Playwright	tests/
Lint	ESLint	eslint.config.mjs
Commit	CommitLint + Husky	.husky/