ggbr12/papiro-mind repository overview

⁠PapiroMind

Site

http://papiromind.codelsoftware.com.br/⁠

⁠📘 Plataforma de Documentação Técnica Inteligente (Notion para Engenheiros)

⁠1. 🎯 O que é a ferramenta

Trata-se de uma plataforma de documentação técnica, inspirada no Notion, mas projetada exclusivamente para times de engenharia de software.

Ela funciona como:

• Base de verdade técnica

• Knowledge Hub para desenvolvedores

• Fonte contextual para agentes de IA via MCP

• Portal integrado ao ciclo de desenvolvimento

Não é um Notion genérico — é desenhado intencionalmente para engenharia, convivendo diretamente com o código.

⁠2. 🧑‍💻 Público-alvo

A ferramenta atende:

• Engenheiros de software

• Tech Leads

• Arquitetos

• Backend e Frontend

• SRE / DevOps

• QA técnico

• Equipes que usam IA para desenvolvimento

O foco é documentação técnica rápida, precisa e ligada ao código.

⁠3. 🔥 Por que essa ferramenta existe

As ferramentas atuais:

• Não são orientadas a engenharia

• Não sincronizam bem documentação ↔ código

• Não são preparadas para agentes de IA

• Não versionam tecnicamente da maneira correta

• Têm baixa integração com GitHub / Jira / CI/CD

Times modernos precisam de:

• Precisão

• Histórico e rastreabilidade

• Padronização

• Documentação que oriente humanos e IA

A plataforma resolve isso criando uma Single Source of Truth técnica, viva e integrada ao desenvolvimento.

⁠4. 🧱 Características principais

⁠4.1 Estrutura tipo Notion, mas especializada

• Workspaces

• Páginas hierárquicas

• Links internos [[Minha Página]]

• Editor TipTap (Markdown + HTML)

• Versionamento estruturado

⁠4.2 Base técnica centralizada

Inclui:

• Arquitetura

• Modelagem

• ADRs

• RFCs

• Endpoints

• Especificações

• Diagramas

• Guias operacionais

⁠4.3 Motor de relacionamentos

Permite relacionar:

• Página ↔ página

• Página ↔ módulo

• Página ↔ feature

• Página ↔ issue do Jira

Formando um grafo navegável de conhecimento.

⁠5. 🤖 Integração com agentes MCP

A plataforma é o backend de contexto para agentes como:

• Cursor

• Copilot

• VSCode Agents

• Agentes internos

Fluxo simplificado:

1. Dev aciona agente

2. Agente chama o MCP

3. MCP consulta a documentação

4. Retorna contexto técnico (diagramas, ADRs, modelos, fluxos)

5. Agente dá respostas alinhadas à arquitetura real

Sem documentação estruturada → respostas vagas
Com esta plataforma → respostas precisas e contextualizadas

⁠6. 🧩 Integração com Jira

Permite:

• Relacionar páginas ↔ histórias/épicos

• Criar páginas a partir de issues

• Sincronizar status

• Mostrar documentação no Jira

• Criar histórico técnico automático

O Jira descreve tarefas.
A plataforma descreve conhecimento.

⁠7. 🚀 Fluxo ideal do desenvolvedor

1. PM cria história

2. Tech Lead cria página técnica

3. Dev desenvolve consultando documentação

4. Ao finalizar, documenta ajustes

5. A documentação vira base do próximo dev/IA

⁠1️⃣ Fluxos Gerais do Sistema

⁠A. Criar Workspace e Página

1. Usuário acessa o sistema

2. Cria workspace

3. Cria página

4. TipTap abre editor

5. Usuário escreve Markdown

6. Livewire salva Markdown + HTML

⁠B. Criar Página em Workspace Existente

1. Acessa workspace

2. Clica “Nova Página”

3. Preenche título

4. TipTap abre editor

5. Livewire salva

⁠C. Editar Página Existente

1. Usuario acessa workspace

2. Lista páginas

3. Seleciona uma

4. TipTap carrega conteúdo

5. Edita

6. Livewire salva atualizações

⁠D. Adicionar Tags

1. Abre página

2. Adiciona tags

3. Sistema salva relação

4. Workspace permite filtros por tags

⁠E. Consulta via MCP (IA)

1. Dev aciona agente

2. Agente chama MCP

3. MCP consulta base

4. MCP retorna conteúdo técnico

5. Agente auxilia dev

⁠2️⃣ Diagrama de Sequência — Fluxo Completo

`sequenceDiagram autonumber

actor Usuario as Usuário
participant Browser as Navegador (UI)
participant TipTap as Editor TipTap
participant Livewire as Livewire
participant Laravel as Backend Laravel
participant DB as Banco de Dados
participant MCP as Servidor MCP
participant Agent as Agente de IA (Cursor)

%% --- Criar Workspace ---
Usuario->>Browser: Acessa o sistema
Browser->>Laravel: Solicita criação de Workspace
Laravel->>DB: Salva Workspace
DB-->>Laravel: OK
Laravel-->>Browser: Workspace criado

%% --- Criar Página ---
Usuario->>Browser: Criar nova página
Browser->>Laravel: Criar registro da página
Laravel->>DB: Salva nova página
DB-->>Laravel: OK
Laravel-->>Browser: Enviar página vazia

Browser->>TipTap: Inicializa editor
Usuario->>TipTap: Edita conteúdo
TipTap->>Livewire: onUpdate(html, markdown)

Livewire->>Laravel: updateContent
Laravel->>DB: Persistir conteúdo
DB-->>Laravel: OK
Laravel-->>Livewire: Confirmar

%% --- Editar Página Existente ---
Usuario->>Browser: Abrir página
Browser->>Laravel: Buscar conteúdo
Laravel->>DB: SELECT
DB-->>Laravel: Conteúdo
Laravel-->>Browser: Retorna
Browser->>TipTap: Carrega conteúdo

%% --- Tags ---
Usuario->>Browser: Adiciona tags
Browser->>Laravel: Atualiza tags
Laravel->>DB: Salva relação
DB-->>Laravel: OK

%% --- MCP Query ---
Agent->>MCP: Consulta termo/página/tag
MCP->>Laravel: Buscar documentação
Laravel->>DB: SELECT
DB-->>Laravel: Conteúdo técnico
Laravel-->>MCP: Resposta estruturada
MCP-->>Agent: Resultados` 

⁠3️⃣ Banco de Dados — Modelagem

`///////////////////////////////////////////////////////// // USERS /////////////////////////////////////////////////////////

Table users { id bigint [pk, increment] nome varchar email varchar [unique] senha_hash varchar criado_em datetime atualizado_em datetime }

///////////////////////////////////////////////////////// // WORKSPACES /////////////////////////////////////////////////////////

Table workspaces { id bigint [pk, increment] nome varchar slug varchar descricao text criado_por bigint criado_em datetime atualizado_em datetime }

///////////////////////////////////////////////////////// // WORKSPACE USERS /////////////////////////////////////////////////////////

Table workspace_users { id bigint [pk, increment] workspace_id bigint user_id bigint papel varchar // admin, editor, viewer criado_em datetime }

///////////////////////////////////////////////////////// // PAGES /////////////////////////////////////////////////////////

Table pages { id bigint [pk, increment] workspace_id bigint parent_page_id bigint [null] titulo varchar slug varchar conteudo_markdown longtext metadados json criado_por bigint atualizado_por bigint criado_em datetime atualizado_em datetime }

///////////////////////////////////////////////////////// // PAGE VERSIONS /////////////////////////////////////////////////////////

Table page_versions { id bigint [pk, increment] page_id bigint conteudo_markdown longtext metadados json criado_por bigint criado_em datetime }

///////////////////////////////////////////////////////// // PAGE LINKS /////////////////////////////////////////////////////////

Table page_links { id bigint [pk, increment] page_id bigint linked_page_id bigint tipo varchar // referencia, citacao, dependencia criado_em datetime }

///////////////////////////////////////////////////////// // PAGE PERMISSIONS /////////////////////////////////////////////////////////

Table page_permissions { id bigint [pk, increment] page_id bigint user_id bigint permissao varchar // owner, editor, viewer, denied criado_em datetime }

///////////////////////////////////////////////////////// // AI INDEX /////////////////////////////////////////////////////////

Table ai_index { id bigint [pk, increment] page_id bigint version_id bigint embedding json resumo text tokens int atualizado_em datetime }

///////////////////////////////////////////////////////// // REFS /////////////////////////////////////////////////////////

Ref: workspaces.criado_por > users.id Ref: workspace_users.workspace_id > workspaces.id Ref: workspace_users.user_id > users.id Ref: pages.workspace_id > workspaces.id Ref: pages.parent_page_id > pages.id Ref: pages.criado_por > users.id Ref: pages.atualizado_por > users.id Ref: page_versions.page_id > pages.id Ref: page_versions.criado_por > users.id Ref: page_links.page_id > pages.id Ref: page_links.linked_page_id > pages.id Ref: page_permissions.page_id > pages.id Ref: page_permissions.user_id > users.id Ref: ai_index.page_id > pages.id Ref: ai_index.version_id > page_versions.id`