🌐 English version · Português (padrão)
Base de conhecimento operacional orientada a incidentes. Um "Notion para operações": registre incidentes durante a emergência, transforme-os em KBs revisadas e encontre soluções rapidamente na próxima ocorrência.
Status: projeto em desenvolvimento ativo. A API pode sofrer mudanças incompatíveis entre versões.
|
Captura Rápida — texto, voz, logs e imagens; a IA gera o artigo
|
Incidentes — lifecycle completo: aberto → reconhecido → resolvido
|
|
Knowledge Base — biblioteca de artigos com workflow de revisão
|
Artigo de KB — gerado a partir de um incidente, pronto para revisão
|
|
Busca Inteligente — combina texto, busca semântica (IA) e análise de problema
|
Post-Mortem — templates Google SRE, Netflix e AWS Well-Architected
|
- Screenshots
- Principais recursos
- Stack
- Começando
- Configuração
- Integrações opcionais
- Scripts disponíveis
- Estrutura do projeto
- Como contribuir
- Versionamento
- Contribuidores
- Autor
- Licença
- Registro rápido de incidentes — captura durante a emergência, estruturação depois.
- Busca textual e semântica — índice full-text do MongoDB, com busca por similaridade quando a IA está habilitada.
- Workflow de revisão — quem cria não aprova; rascunho → revisão → publicado.
- Multi-tenant — isolamento de dados por organização em todas as consultas.
- Controle de acesso — papéis, departamentos, grupos e permissões por base.
- Post-mortem e RCA — templates estruturados, timeline e 5 Whys.
- Ingestão de eventos — endpoint para Zabbix, Grafana e afins via token de API.
- Versionamento e auditoria — histórico de alterações e trilha de auditoria.
- Upload de arquivos — disco local por padrão, ou Cloudflare R2 quando configurado.
| Camada | Tecnologias |
|---|---|
| Backend | Node.js 18+, Fastify 4, MongoDB 7, JWT |
| Frontend | React 18, Vite 5, Bootstrap 5, React Router 6 |
| Infra local | Docker Compose (MongoDB) |
| Opcionais | OpenAI, Cloudflare R2, SMTP |
git clone https://github.com/janeiaraujo/knowledgebase.git
cd knowledgebase
docker compose up -d
docker compose --profile demo run --rm seed # dados de demonstraçãoAbra http://localhost:8080 e entre com demo@incidentkb.com / demo123.
Sobe MongoDB, API e interface — a interface serve por nginx, que faz o proxy de
/api e do WebSocket, então só a porta 8080 precisa existir.
Este compose é para avaliação e uso local. Antes de expor a qualquer rede, troque
JWT_SECRETeJWT_REFRESH_SECRET— veja SECURITY.md.
Para desenvolver (com hot reload), siga o passo a passo abaixo.
- Node.js 22+ (nodejs.org) — o backend roda em 18+, mas o Vite 8 do frontend exige
^20.19.0ou>=22.12.0 - Docker (docs.docker.com) — para o MongoDB local
- Git
Prefere não usar Docker? Veja Usando MongoDB Atlas.
# 1. Clone o repositório
git clone https://github.com/janeiaraujo/knowledgebase.git
cd knowledgebase
# 2. Suba o MongoDB
docker compose up -d
# 3. Configure e prepare o backend
cd backend
cp .env.example .env
npm install
npm run migrate # cria os índices do banco
npm run seed # popula dados de demonstração
npm start
# 4. Em outro terminal, o frontend
cd frontend
cp .env.example .env
npm install
npm run devAcesse http://localhost:5173.
O npm run seed cria uma organização de exemplo com 3 KBs:
E-mail: demo@incidentkb.com
Senha: demo123
⚠️ São credenciais de desenvolvimento. Nunca use este seed em produção.
curl http://localhost:3000/healthToda a configuração fica em backend/.env (veja backend/.env.example). Apenas quatro variáveis são obrigatórias:
| Variável | Descrição |
|---|---|
MONGODB_URI |
Conexão com o MongoDB. Padrão: mongodb://localhost:27017/incident_intelligence |
JWT_SECRET |
Segredo de assinatura do access token |
JWT_REFRESH_SECRET |
Segredo de assinatura do refresh token |
FRONTEND_URL |
Origem do frontend, usada no CORS |
Gere segredos seguros com:
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"🔒 O arquivo
.envestá no.gitignore. Nunca faça commit de credenciais reais — inclusive em arquivos de documentação.
Crie um cluster gratuito, libere seu IP em Network Access e ajuste:
MONGODB_URI=mongodb+srv://usuario:senha@cluster.mongodb.net/incident_intelligence?retryWrites=true&w=majorityO sistema sobe e funciona sem nenhuma delas. Cada uma habilita um recurso específico:
| Integração | Sem configurar | Variáveis |
|---|---|---|
| OpenAI | Rotas de IA respondem 503; o restante funciona |
OPENAI_API_KEY |
| Cloudflare R2 | Uploads vão para backend/uploads/ |
R2_* |
| SMTP | Magic link indisponível; login por senha funciona | SMTP_* |
| Asaas | Recursos de billing desabilitados | ASAAS_* |
| Comando | Descrição |
|---|---|
npm start |
Inicia a API em http://localhost:3000 |
npm run dev |
Inicia com hot reload (node --watch) |
npm run migrate |
Cria/atualiza os índices do MongoDB (idempotente) |
npm run seed |
Popula dados de demonstração |
node scripts/seed-sample-data.js |
Popula KBs, incidentes e eventos de exemplo extras (idempotente por tipo de dado) |
npm test |
Smoke test: sobe a API real e valida boot, /health, login e uma rota protegida |
⚠️ Oseedé aditivo: executá-lo novamente duplica os dados de exemplo. Rode-o apenas em bancos vazios. Jáscripts/seed-sample-data.jsverifica antes de inserir (pula KBs/incidentes se já existirem para o tenant), então pode rodar quantas vezes quiser.
| Comando | Descrição |
|---|---|
npm run dev |
Servidor de desenvolvimento em http://localhost:5173 |
npm run build |
Build de produção em dist/ |
npm run preview |
Serve o build localmente |
| Comando | Descrição |
|---|---|
docker compose up -d |
Sobe o MongoDB |
docker compose --profile tools up -d |
Sobe também o Mongo Express (http://localhost:8081) |
docker compose down |
Para os containers (preserva os dados) |
docker compose down -v |
Para e apaga os dados do banco |
.
├── backend/
│ └── src/
│ ├── db/indexes.js # Definição dos índices (usada no boot e no migrate)
│ ├── middlewares/ # Autenticação, tenant, RBAC
│ ├── modules/ # Um diretório por domínio (auth, records, kb, ai, ...)
│ ├── seeds/ # Scripts de migrate e seed
│ ├── utils/ # Helpers compartilhados
│ └── server.js # Bootstrap do Fastify
├── frontend/
│ └── src/
│ ├── components/ # Componentes reutilizáveis
│ ├── contexts/ # Estado global (Context API)
│ ├── pages/ # Telas da aplicação
│ └── services/ # Cliente HTTP
└── docker-compose.yml
Cada módulo do backend segue o padrão <dominio>.routes.js e, quando há regra de negócio relevante, <dominio>.service.js.
Contribuições são bem-vindas. Veja o CONTRIBUTING.md para o fluxo de trabalho, padrões de código e como reportar bugs.
Se este projeto te ajudou, considere deixar uma ⭐ — é o que aumenta o alcance dele.
Segue SemVer. A versão vive em dois lugares que precisam estar sempre iguais: backend/package.json e frontend/package.json — o CI falha o build se eles divergirem.
Tag e release são automáticas: ao mergear um PR que muda a versão, o workflow .github/workflows/release.yml cria a tag vX.Y.Z e publica a release usando a seção correspondente do CHANGELOG.md como corpo — não precisa criar nada manualmente. Se o CHANGELOG ainda não tiver a seção da versão, o workflow avisa e cai para as notas geradas a partir dos commits. O badge de "versão" no topo deste README lê backend/package.json em tempo real; o de "release" lê a última tag publicada.
Duas guardas evitam que a release fique para trás: o CI avisa (sem bloquear) quando um PR muda código de produto sem bumpar a versão, e o workflow release-drift.yml mantém uma issue aberta enquanto a main estiver à frente da última tag — fechando-a sozinho quando a release sair.
Para lançar uma nova versão: bump os dois package.json no mesmo PR, seguindo o tipo de mudança (patch para correção, minor para funcionalidade nova compatível, major para quebra de compatibilidade), e mergeie — o resto é automático.
Não é possível dar push direto na main. Toda mudança passa por pull request com: 1 aprovação, os 3 checks do CI verdes, branch atualizado com a main e conversas resolvidas. Force push e exclusão da branch estão bloqueados.
O alerta GHSA-qwww-vcr4-c8h2 (CSRF em RSC mode) aparece para o react-router 7.x e só tem correção na 8.3.0. Não se aplica a este projeto: a advisory afirma que afeta apenas quem usa as APIs instáveis de RSC, e este app é uma SPA client-side que não usa nenhuma delas.
Aplicá-lo não é atualizar uma dependência — react-router@8 exige React >= 19.2.7, e o projeto está no React 18. Seria uma migração de framework completa. Reavaliar quando migrarmos para o React 19; até lá o alerta está dispensado no Dependabot como "código vulnerável não é usado".
Obrigado a todas as pessoas que já contribuíram com este projeto:
Janei Araujo — @janeiaraujo
Distribuído sob a licença GNU AGPL-3.0-or-later. Veja LICENSE.
Encontrou uma falha de segurança? Não abra issue pública — veja SECURITY.md. Este projeto adota o Código de Conduta do Contributor Covenant.
Em resumo: você pode usar, modificar e redistribuir o projeto, inclusive comercialmente. Porém, se você o executar como serviço acessível pela rede, precisa disponibilizar o código-fonte da sua versão modificada aos usuários desse serviço.