Chronicle

Plataforma de gestao de projetos com quadros Kanban, listas de tarefas, etiquetas, membros e notificacoes em tempo real.

Visao Geral

O Chronicle e um sistema de gestao de projetos inspirado no Pipefy/Trello, com quadros Kanban customizaveis, automacoes, formularios publicos e bancos de dados compartilhados.

Funcionalidades Principais

Modulo	Descricao
Organizations	Equipes/empresas com membros e roles
Pipes	Quadros Kanban com estagios, campos e automacoes
Cards	Itens de trabalho com campos customizados, labels e dependencias
Automations	Automacoes de workflow com 7 triggers e 8 acoes
Public Forms	Formularios externos para captacao de cards
Databases	Bancos de dados compartilhados por organizacao
Reports	Estatisticas e analytics por pipe e organizacao
WebSocket	Atualizacoes em tempo real no board

Stack

Camada	Tecnologia
Backend	Quarkus 3.17 + Java 21 + PostgreSQL 16
Frontend	Next.js 16 + React 18 + TypeScript + Tailwind CSS
Auth	JWT via OATH + roles via Guild
Cache	Redis (TTL configuravel)
WebSocket	Quarkus WebSockets Next
Drag & Drop	@dnd-kit
State	Zustand + React Query

Hierarquia de Dados

graph TB
    ORG[Organization] --> PIPE[Pipe]
    ORG --> DB[Database]
    ORG --> MEMBER[Member]
    PIPE --> STAGE[Stage]
    PIPE --> FIELD[Field]
    PIPE --> AUTO[Automation]
    PIPE --> LABEL[Label]
    PIPE --> FORM[Public Form]
    STAGE --> CARD[Card]
    CARD --> DATA[Card Data]
    CARD --> COMMENT[Comment]
    CARD --> FILE[File]
    CARD --> EMAIL[Email]
    CARD --> DEP[Dependency]

Multi-Tenancy

O Chronicle usa organizacoes como unidade de multi-tenancy:

• Cada usuario pode pertencer a multiplas organizacoes
• Roles por organizacao: OWNER, ADMIN, MEMBER
• Header X-Organization-Id em todas as requisicoes
• Convites por email com token de 7 dias

Kanban Board

O quadro Kanban e a interface principal do Chronicle:

Stages (Colunas)

• Posicao: Ordenacao visual
• isInitial: Estagio padrao para novos cards
• isFinal: Estagio de conclusao
• wipLimit: Limite de Work In Progress
• slaHours: SLA em horas (tempo maximo no estagio)

Cards (Itens)

• Codigo sequencial por pipe (ex: PRJ-0001)
• Campos customizados (15+ tipos)
• Assignee (responsavel)
• Due date + SLA tracking
• Labels, dependencias, arquivos, comentarios

Campos Customizados

Tipo	Descricao
TEXT / TEXTAREA	Texto simples / multilinhas
NUMBER / CURRENCY	Numeros e valores monetarios
DATE / DATETIME	Datas e horarios
SELECT / MULTISELECT	Opcoes unica / multipla
CHECKBOX	Booleano
FILE	Upload de arquivos
EMAIL / PHONE / URL	Campos formatados
ASSIGNEE / LABEL	Vinculo com usuario / etiqueta
DATABASE_LINK	Vinculo com banco de dados compartilhado

Os campos suportam condicoes de visibilidade e condicoes de obrigatoriedade baseadas em valores de outros campos.

Automacoes

graph LR
    T[Trigger] --> C{Condicoes?}
    C -->|Sim| A[Acao]
    C -->|Nao| X[Ignora]

Triggers

Trigger	Descricao
CARD_CREATED	Quando um card e criado
CARD_MOVED	Quando um card muda de estagio
FIELD_CHANGED	Quando um campo e atualizado
STAGE_ENTERED	Quando um card entra em estagio especifico
STAGE_EXITED	Quando um card sai de estagio especifico
DUE_DATE_PASSED	Quando a data de vencimento passa
SCHEDULE	Execucao agendada (cron)

Acoes

Acao	Descricao
MOVE_CARD	Mover card para outro estagio
UPDATE_FIELD	Atualizar valor de campo
SEND_EMAIL	Enviar email via Herald
SEND_WEBHOOK	POST para URL externa
ASSIGN_USER	Atribuir card a usuario
ADD_LABEL	Adicionar etiqueta
CREATE_COMMENT	Adicionar comentario
CREATE_CARD_IN_PIPE	Criar card em outro pipe

Profundidade maxima de execucao: 5 niveis (previne loops infinitos).

Tempo Real (WebSocket)

ws://host/ws/board/{pipeId}

Eventos transmitidos:

• CARD_CREATED, CARD_UPDATED, CARD_MOVED
• CARD_ARCHIVED, CARD_UNARCHIVED, CARD_DELETED

O frontend usa @dnd-kit para drag & drop e Zustand para gerenciar o estado do board com atualizacoes otimistas.

API Publica

O Chronicle oferece uma API publica autenticada por API Keys:

Header: X-API-Key: {key}

Endpoint	Metodo	Descricao
/api/v1/pipes/{pipeId}/cards	POST	Criar card
/api/v1/cards/{id}	GET	Obter card
/api/v1/pipes/{pipeId}/cards/code/{code}	GET	Buscar por codigo
/api/v1/cards/{id}	PUT	Atualizar card
/api/v1/cards/{id}/move	POST	Mover card

Cada API Key tem scopes (cards:read, cards:write, cards:move) e pode ser restrita a pipes especificos.

Formularios Publicos

Permitem captacao externa de cards sem autenticacao:

• URL publica: /forms/{slug}
• Campos selecionaveis do pipe
• Mensagens de boas-vindas e sucesso customizaveis
• Notificacoes por email para administradores
• Limite de submissoes configuravel
• Card criado no estagio alvo