Primeiros Passos — Chronicle¶

Pre-requisitos¶

Docker e Docker Compose
Java 21 (para desenvolvimento local)
Node.js 18+ (para o frontend)
Redis (para cache)
Servicos Haus rodando (OATH, Guild, Herald, Vault, Scrolls)

Subindo o Ambiente¶

1. Clone o repositorio¶

git clone <repo-url>
cd chronicle-backend

2. Suba os servicos¶

docker compose up -d postgres redis

PostgreSQL na porta 5436, Redis na porta 6379.

3. Inicie o backend¶

./mvnw quarkus:dev

O backend inicia na porta 8080 (internamente) com Flyway executando as migrations.

4. Inicie o frontend¶

cd ../chronicle-frontend
npm install
npm run dev

O frontend inicia na porta 3040.

Primeiro Acesso¶

1. Criar conta¶

Acesse http://localhost:3040/signup. O cadastro suporta:

Email + senha
OTP (One-Time Password)
OAuth2 (Google, GitHub)

2. Criar organizacao¶

Apos o login, crie sua organizacao:

Nome da organizacao
Slug (URL amigavel)
Descricao (opcional)

3. Criar pipe (quadro)¶

Em Pipes > Novo:

Nome do pipe
Icone e cor
Descricao

O pipe ja vem com estagios padrao que podem ser customizados.

4. Configurar estagios¶

No Editor do pipe:

Reordenar estagios
Definir estagio inicial e final
Configurar WIP limits
Definir SLA (horas)

5. Criar campos customizados¶

No Editor > Fields:

Adicionar campos (texto, numero, select, etc.)
Definir obrigatoriedade
Configurar condicoes de visibilidade

6. Criar automacoes¶

Em Automations:

Escolher trigger (card criado, movido, etc.)
Definir condicoes (opcional)
Configurar acao (mover, email, webhook, etc.)

Variaveis de Ambiente¶

Backend¶

QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://localhost:5436/chronicledb
QUARKUS_DATASOURCE_USERNAME=chronicle
QUARKUS_DATASOURCE_PASSWORD=chronicle
QUARKUS_REDIS_HOSTS=redis://localhost:6379

Frontend¶

NEXT_PUBLIC_API_URL=http://localhost:5040

Estrutura de Pastas¶

chronicle-backend/
├── src/main/java/chronicle/
│   ├── api/                # BFF + Public API + WebSocket
│   ├── application/        # Services
│   ├── domain/            # Entities + Enums
│   └── infrastructure/    # Clients, Cache, Security
├── src/main/resources/
│   ├── application.properties
│   └── db/migrations/     # Flyway
└── pom.xml

chronicle-frontend/
├── src/
│   ├── app/               # Next.js App Router
│   ├── components/        # Board, Cards, Editor
│   ├── stores/            # Zustand (auth, board, org)
│   ├── hooks/             # WebSocket hook
│   ├── lib/               # API client
│   └── types/             # TypeScript types
└── package.json

Comandos Uteis¶

# Backend
./mvnw quarkus:dev                    # Dev mode
./mvnw clean package                  # Build

# Frontend
npm run dev                           # Dev server (port 3040)
npm run build                         # Production build
npm run test                          # Playwright E2E
npm run lint                          # ESLint

WebSocket (Desenvolvimento)¶

Para testar WebSocket localmente, o frontend auto-detecta:

http://localhost:3040 → ws://localhost:8080/ws/board/{pipeId}
https://chronicle.example.com → wss://chronicle.example.com/ws/board/{pipeId}

O board mostra um indicador de conexao no canto.