🧭 notion-workspace-app

📋 Índice

• 📖 Sobre o Projeto
• 📁 Estrutura do Projeto
• 🚀 Componentes
• ✨ Funcionalidades
• 🎯 Como Usar
• 🔐 Configuração e Segurança
• ✅ Qualidade
• 📄 Licença
• 👤 Autor
• 🤝 Contribuições

📖 Sobre o Projeto

O notion-workspace-app reúne quatro interfaces sobre o mesmo núcleo de dados: uma API REST Django, uma SPA React, um servidor MCP para clientes de IA e um launcher TUI que prepara e inicia o ambiente. A aplicação permite gerenciar tarefas em kanban, grade ou lista, explorar o workspace e sincronizar repositórios do GitHub com databases do Notion.

A regra de negócio compartilhada vem da biblioteca notion-starter. Este repositório mantém as bordas Django, React e MCP, além da configuração específica do produto. A porta de entrada recomendada é python start_app.py.

O projeto integra o ecossistema Automações do Notion.

📁 Estrutura do Projeto

notion-workspace-app/
│
├── 📁 server/                   # Backend Django e servidor MCP
│   ├── 📁 api/                  # Views, serializers e rotas REST
│   ├── 📁 config/               # Configuração do projeto Django
│   ├── 📁 integrations/         # Notion local e shims de adaptadores
│   ├── 📁 operations/           # Estado operacional em SQLite
│   ├── 📁 services/             # Shims dos casos de uso compartilhados
│   └── mcp_server.py            # Ferramentas notion.*
│
├── 📁 front/                    # SPA React com Vite
│   ├── 📁 src/components/       # Interface, tarefas e exploração
│   ├── 📁 src/hooks/            # Estado e acesso à API
│   └── package-lock.json        # Resolução reproduzível do frontend
│
├── 📁 tests/                    # Suíte Python automatizada
├── .github/workflows/ci.yml     # Gates Python e frontend
├── start_app.py                 # Menu interativo de entrada
├── requirements.txt             # Dependências Python
├── QUALIDADE.md                 # Contrato de qualidade do módulo
├── README.md                    # Este arquivo
└── LICENSE                      # Licença MIT

Na distribuição 0.3.0, front/ é usado apenas no desenvolvimento: o workflow de release compila a SPA para server/static/frontend/ e o wheel leva esse bundle. Assim, a instalação de usuário não precisa de Node/npm.

🚀 Componentes

✨ Funcionalidades

• visualizar tarefas em kanban, grade e lista;
• buscar e filtrar tarefas por status, duração e área;
• criar e editar tarefas pela interface;
• explorar páginas e databases compartilhados;
• sincronizar repositórios GitHub com databases do Notion;
• expor operações para clientes de IA via MCP;
• iniciar Django e Vite em conjunto pelo launcher interativo.

Exemplo de fluxo: ação na SPA → API Django → serviço compartilhado → API do Notion.

🎯 Como Usar

Instalação distribuída

Para usar o ecossistema completo, instale a fachada única:

pipx install "notion-automacoes[app]"
# ou: uv tool install "notion-automacoes[app]"
notion-automacoes doctor
notion-automacoes app start
notion-automacoes mcp start

O pacote notion-workspace-app==0.3.0 está publicado no PyPI. Para o produto completo, a instalação recomendada é a fachada notion-automacoes[app], que instala este app e a CLI em conjunto. Consulte o guia de distribuição do hub para a matriz de smoke e os limites do release.

Início rápido

O fluxo abaixo é o de desenvolvimento pelo checkout:

# Clone o repositório
git clone https://github.com/Felipe-Alcantara/notion-workspace-app.git
cd notion-workspace-app

# Instale as dependências Python de desenvolvimento
python -m pip install -e ".[dev]"

# Crie a configuração local e preencha os valores necessários
cp .env.example .env

# Abra o menu que instala, configura e inicia o produto
python start_app.py

No checkout, o launcher aplica as migrações, sobe Django e Vite e abre o navegador. Pelo menu também é possível instalar dependências, configurar o ambiente e conferir o status dos componentes.

Quando executado a partir do wheel, o mesmo launcher sobe apenas o Django e serve a SPA empacotada; Node/npm não são consultados. Os entry points diretos também estão disponíveis:

notion-automacoes-app --help
notion-automacoes-mcp --help

🔐 Configuração e Segurança

Use .env.example como modelo e mantenha o .env apenas na máquina local. Para operar o workspace, configure NOTION_TOKEN e, quando aplicável, NOTION_DATABASE_ID.

Nunca versione tokens, IDs reais ou bancos SQLite. Os testes usam mocks e não dependem de credenciais reais.

✅ Qualidade

Gate Python, executado na raiz:

python -m ruff check .
python -m pytest

Gate da SPA:

cd front
npm run lint
npm run build

A CI executa Python 3.10–3.13 e um job Node 22 com npm ci. Consulte QUALIDADE.md para o critério de pronto e a política de dependências.

📄 Licença

Este projeto está sob a licença MIT — veja LICENSE.

👤 Autor

Felipe Alcantara

• GitHub: @Felipe-Alcantara
• Repositório: notion-workspace-app

🤝 Contribuições

Contribuições são bem-vindas. Algumas ideias para quem quiser colaborar:

• ampliar a escrita genérica na aba Explorar;
• criar novas visualizações e interações no kanban;
• melhorar o empacotamento do launcher;
• expandir acessibilidade, testes e documentação.

Leia CONTRIBUTING.md antes de enviar uma mudança.

⭐ Se o app foi útil, considere dar uma estrela no GitHub.