Sinapse — Base Inteligente de Requisitos

PRO4TECH · Fatec São José dos Campos · Grupo Galáticos
Projeto de Aprendizagem Interdisciplinar (API) — 4º Semestre (2º Semestre/2026)

O Sinapse é a memória institucional da fábrica de software. A plataforma converte requisitos de software e decisões de engenharia em uma base de conhecimento inteligente e reutilizável, auxiliando Product Owners (POs) e equipes de desenvolvimento na especificação de features com menor retrabalho e maior conformidade com o padrão da fábrica.

📖 User Stories e rastreabilidade das tarefas

O Backlog de Produto v1.0 contém 63 User Stories (PBIs), organizadas em seis épicos. A descrição completa de cada história — COMO UM, EU QUERO, PARA QUE, cenários DADO/QUANDO/ENTÃO e prioridade — está nos documentos abaixo:

Cada tarefa técnica abaixo está ligada diretamente a pelo menos uma User Story. Os critérios de aceitação da tarefa nunca substituem os cenários da User Story.

Sprint 1 — 32 tarefas

Tarefa	User Stories relacionadas
PRE-01	PBI-01.1.1, PBI-01.1.2, PBI-01.1.3, PBI-01.1.4
PRE-02	PBI-01.1.1, PBI-01.1.5, PBI-01.5.1, PBI-02.2.4, PBI-03.2.2, PBI-04.2.1, PBI-05.1.1, PBI-06.1.1
PRE-03	PBI-02.1.1, PBI-02.1.4, PBI-02.2.1, PBI-03.2.1
PRE-04	PBI-01.3.1, PBI-02.3.1, PBI-04.1.3, PBI-06.1.1
PRE-05	PBI-01.1.1, PBI-01.1.2, PBI-01.1.3, PBI-01.1.4
PRE-06	PBI-02.3.1, PBI-03.1.4, PBI-05.2.1
PRE-07	PBI-02.3.1, PBI-04.1.1
PRE-08	PBI-06.1.1, PBI-06.1.2, PBI-06.1.3
PRE-09	PBI-02.2.1, PBI-03.1.1, PBI-04.1.1
S1-01	PBI-06.1.1, PBI-06.1.2, PBI-06.1.3
S1-02	PBI-06.1.1, PBI-06.1.2, PBI-06.1.3
S1-03, S1-04	PBI-01.1.1
S1-05	PBI-01.1.2
S1-06	PBI-01.1.3
S1-07	PBI-01.1.4
S1-08	PBI-01.1.5
S1-09	PBI-01.1.6
S1-10, S1-11	PBI-01.2.1, PBI-01.2.2, PBI-01.2.3
S1-12	PBI-01.2.4
S1-13	PBI-01.3.1, PBI-01.3.2, PBI-01.3.3, PBI-01.3.4
S1-14	PBI-01.3.5
S1-15	PBI-01.3.6
S1-16	PBI-01.4.1, PBI-01.4.2
S1-17	PBI-01.4.3
S1-18	PBI-01.5.1, PBI-01.5.2
S1-19	PBI-02.1.1
S1-20	PBI-02.1.2
S1-21	PBI-02.1.3
S1-22	PBI-02.1.4
S1-23	PBI-01.1.1, PBI-01.1.2, PBI-01.1.3, PBI-01.1.4, PBI-01.1.5, PBI-01.2.1, PBI-01.2.2, PBI-01.2.3, PBI-01.3.1, PBI-01.3.2, PBI-01.3.3, PBI-01.3.5, PBI-01.4.1, PBI-01.4.2, PBI-01.5.1, PBI-01.5.2, PBI-02.1.1, PBI-06.1.1, PBI-06.1.2, PBI-06.1.3

Sprint 2 — 18 tarefas

Tarefa	User Stories relacionadas
S2-01, S2-02	PBI-02.2.1
S2-03	PBI-02.2.2
S2-04	PBI-02.2.3
S2-05	PBI-02.2.4
S2-06	PBI-02.3.1
S2-07	PBI-02.3.2
S2-08	PBI-02.3.3
S2-09	PBI-03.3.1, PBI-03.3.2
S2-10	PBI-03.1.1, PBI-03.1.2
S2-11	PBI-03.1.3
S2-12	PBI-03.1.4
S2-13	PBI-03.2.1
S2-14	PBI-03.2.2, PBI-03.2.3
S2-15	PBI-01.5.3
S2-16	PBI-01.5.4
S2-17	PBI-02.3.1, PBI-02.3.2
S2-18	PBI-02.2.1, PBI-02.2.2, PBI-02.2.4, PBI-02.3.1, PBI-02.3.2, PBI-02.3.3, PBI-03.1.1, PBI-03.1.2, PBI-03.1.4, PBI-03.2.1, PBI-03.2.2, PBI-03.2.3, PBI-03.3.1, PBI-03.3.2

Sprint 3 — 17 tarefas

Tarefa	User Stories relacionadas
S3-01	PBI-04.1.1, PBI-04.1.2
S3-02	PBI-04.1.3
S3-03	PBI-04.1.4
S3-04	PBI-04.1.1, PBI-04.1.2, PBI-04.1.3, PBI-04.1.4
S3-05	PBI-04.2.1
S3-06	PBI-04.2.2
S3-07	PBI-04.2.3
S3-08	PBI-05.1.1, PBI-05.1.4
S3-09	PBI-05.1.2
S3-10	PBI-05.1.3, PBI-05.2.3
S3-11	PBI-05.2.1
S3-12	PBI-05.2.2
S3-13	PBI-06.2.1
S3-14	PBI-06.2.2
S3-15	PBI-01.5.5
S3-16	PBI-04.1.1, PBI-04.1.2, PBI-04.1.3, PBI-04.1.4, PBI-05.1.1, PBI-05.1.2, PBI-05.1.3, PBI-05.1.4, PBI-05.2.1
S3-17	PBI-04.1.1, PBI-04.1.2, PBI-05.2.1, PBI-06.2.1, PBI-06.2.2

O detalhamento operacional das 67 tarefas, dependências, tamanhos e critérios globais está no Plano de Tarefas de Desenvolvimento.

🏗️ Arquitetura e Componentes de Infraestrutura

A stack base deste repositório compreende:

Serviço / Componente	Descrição / Tecnologia	Função Principal
postgres	`pgvector/pgvector:pg16`	Banco de dados unificado: relacional e busca vetorial (HNSW)
n8n	`docker.n8n.io/n8nio/n8n:latest`	Orquestração do pipeline de ingestão e gatilhos de documentos
ollama	`ollama/ollama:latest`	Runtime local de IA: inferência de LLM e geração de embeddings
`n8n-local-sync`	CLI GitOps em Python (PyPI)	Versionamento, validação e sincronização bidirecional de workflows
Python RAG / IA (em desenv.)	Python 3.11+	Chunking, embeddings e integração com LLM local
Backend Aplicação (em desenv.)	Node.js	API REST, regras de negócio e controle de acesso
Frontend SPA (em desenv.)	React	Interface do Product Owner e consulta ao acervo

🚀 Como Iniciar o Ambiente de Desenvolvimento

1. Pré-requisitos

Docker (v24+) e Docker Compose (v2+)
Python 3.9 ou superior (para execução do n8n-local-sync)
Git

2. Clonar e Configurar Variáveis de Ambiente

Copie o modelo de variáveis de ambiente para criar o seu .env:

cp .env.example .env

⚠️ Importante sobre o N8N_ENCRYPTION_KEY:
A chave definida no .env.example (sinapse-shared-dev-encryption-key-2026) é compartilhada entre toda a equipe de desenvolvimento. Não altere esta chave localmente em desenvolvimento, pois ela garante que as credenciais e workflows exportados continuem válidos e interoperáveis entre as máquinas do time.

3. Subir os Containers

Inicie os containers do PostgreSQL (com pgvector), n8n e Ollama em segundo plano:

docker compose up -d

Verifique se os serviços estão saudáveis:

docker compose ps

PostgreSQL: localhost:5432 (Usuário: sinapse, Senha padrão: sinapse_dev_password, Banco: sinapse)
n8n Web UI: http://localhost:5678
Ollama API: http://localhost:11434

4. Baixar Modelos no Ollama

Os modelos são persistidos no volume Docker sinapse_ollama_data. Para baixar os modelos recomendados no PRD:

# Modelo de Embeddings multilíngue (recomendado)
docker compose exec ollama ollama pull bge-m3

# Modelo LLM para inferência (versão leve para desenvolvimento em CPU)
docker compose exec ollama ollama pull qwen2.5:1.5b

# Listar modelos instalados
docker compose exec ollama ollama list

🔄 Versionamento de Workflows com `n8n-local-sync`

Os workflows do n8n são versionados no Git através do utilitário GitOps n8n-local-sync.

1. Instalação da CLI

Instale a ferramenta via pip:

pip install n8n-local-sync

2. Configurar a API Key do n8n

Acesse o n8n no navegador: http://localhost:5678.
Na primeira inicialização, crie a conta de proprietário local.
Acesse Settings (ícone de engrenagem) → n8n API → Create an API key.
Copie a chave gerada e adicione-a ao seu arquivo local .env:
```
N8N_API_KEY=sua_chave_aqui
```

🔒 Atenção: A variável N8N_API_KEY nunca deve ser versionada no Git. O arquivo .env já está incluído no .gitignore.

3. Comandos do Dia a Dia

Operação	Comando	Descrição
Validar workflows	`n8n-sync validate`	Analisa a sintaxe JSON e varre possíveis segredos/senhas expostos
Visualizar status	`n8n-sync status`	Exibe o estado de sincronização entre o Git local e a instância do n8n
Ver diferenças (diff)	`n8n-sync diff`	Mostra alterações estruturais normalizadas (sem poluição de metadados)
Puxar do n8n para o Git	`n8n-sync sync`	Atualiza o repositório local com os workflows criados/editados no n8n
Subir do Git para o n8n	`n8n-sync push`	Envia os workflows versionados no repositório para o container do n8n

4. Fluxo de Trabalho Recomendado

Desenvolva ou altere o workflow na interface web do n8n (http://localhost:5678).
Traga as alterações para o repositório:
```
n8n-sync sync
```
Valide a integridade do JSON e ausência de credenciais:
```
n8n-sync validate
```
Revise as alterações com o git diff limpo:
```
git diff n8n/workflows/
```

Comite e envie as alterações em commits semânticos:

git add n8n/workflows/
git commit -m "feat(workflow): add document parser workflow"
git push origin <sua-branch>

🧪 Integração Contínua (CI)

A esteira automatizada no GitHub Actions (.github/workflows/ci.yml) é disparada a cada Push e Pull Request:

Valida a sintaxe e a configuração do Docker Compose (docker compose config).
Executa n8n-sync validate para assegurar que nenhum workflow com erro de estrutura ou credencial exposta chegue à branch principal.

📁 Estrutura de Pastas do Repositório

Consulte o Guia de Configuração e Desenvolvimento para instruções detalhadas de inicialização de cada microsserviço.

API-4/
├── .github/
│   └── workflows/
│       └── ci.yml                 # Pipeline de validação no GitHub Actions
├── ai-service/                    # Microsserviço Python/FastAPI (RAG, Chunking & Ollama)
├── backend/                       # API REST Node.js/TypeScript (CRUD, Auth & Postgres)
├── docs/                          # Documentação do projeto, PRD, backlog e guias
│   ├── Architecture/              # Diagramas de arquitetura, fluxo RAG e ERD
│   └── SETUP_GUIDE.md             # Guia completo de configuração das stacks
├── frontend/                      # SPA React/TypeScript/Vite (Interface do PO)
├── n8n/
│   ├── local-files/               # Diretório compartilhado montado em /files no n8n
│   └── workflows/                 # Workflows exportados e versionados no Git
├── .env.example                   # Modelo de configuração de variáveis de ambiente
├── .gitignore                     # Arquivos e diretórios desconsiderados pelo Git
├── .n8n-sync.yaml                 # Configuração do n8n-local-sync
├── docker-compose.yml             # Orquestração dos containers (Postgres, n8n & Ollama)
├── LICENSE                        # Licença do projeto
└── README.md                      # Este arquivo

Navigation Menu

Uh oh!

Repository files navigation

Sinapse — Base Inteligente de Requisitos

📖 User Stories e rastreabilidade das tarefas

🏗️ Arquitetura e Componentes de Infraestrutura

🚀 Como Iniciar o Ambiente de Desenvolvimento

1. Pré-requisitos

2. Clonar e Configurar Variáveis de Ambiente

3. Subir os Containers

4. Baixar Modelos no Ollama

🔄 Versionamento de Workflows com `n8n-local-sync`

1. Instalação da CLI

2. Configurar a API Key do n8n

3. Comandos do Dia a Dia

4. Fluxo de Trabalho Recomendado

🧪 Integração Contínua (CI)

📁 Estrutura de Pastas do Repositório

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
ai-service		ai-service
backend		backend
database		database
docs		docs
frontend		frontend
n8n		n8n
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.n8n-sync.yaml		.n8n-sync.yaml
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Sinapse — Base Inteligente de Requisitos

📖 User Stories e rastreabilidade das tarefas

🏗️ Arquitetura e Componentes de Infraestrutura

🚀 Como Iniciar o Ambiente de Desenvolvimento

1. Pré-requisitos

2. Clonar e Configurar Variáveis de Ambiente

3. Subir os Containers

4. Baixar Modelos no Ollama

🔄 Versionamento de Workflows com n8n-local-sync

1. Instalação da CLI

2. Configurar a API Key do n8n

3. Comandos do Dia a Dia

4. Fluxo de Trabalho Recomendado

🧪 Integração Contínua (CI)

📁 Estrutura de Pastas do Repositório

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🔄 Versionamento de Workflows com `n8n-local-sync`