Tentra Builder

AI-Native Architecture Workspace — design systems no Cursor ou Claude Code e veja a arquitetura ganhar vida em tempo real num canvas visual interativo.

O que e isso

Voce escreve "design a payment system with fraud detection" no Cursor ou Claude Code. O AI chama seu MCP server. A arquitetura aparece aqui -> http://localhost:5173/arch/:id Voce edita servicos, arrasta zonas, conecta nodes, redimensiona tudo e salva.

Cursor / Claude Code
        |
        |  create_architecture({ services, connections })
        v
  MCP Server  ------>  REST API  ------>  PostgreSQL
                                              |
                                              v
                                      React Flow Canvas
                                   http://localhost:5173

Stack

Pre-requisitos

• Node.js 20+
• pnpm 9+ -> npm i -g pnpm
• Docker (para o PostgreSQL)

Instalacao

git clone <repo>
cd archflowbuilder

# Instalar dependencias
pnpm install

# Copiar variaveis de ambiente
cp .env.example .env

Rodando em desenvolvimento

# 1. Subir o PostgreSQL
docker compose up -d postgres

# 2. Criar as tabelas (primeira vez)
cd packages/api
DATABASE_URL=postgresql://archflow:archflow@localhost:5432/archflow npx prisma db push
cd ../..

# 3. Buildar o MCP server
pnpm --filter mcp-server build

# 4. Subir tudo em paralelo
pnpm dev

Conectar o MCP no Cursor

Settings -> Features -> MCP -> Add new server:

{
  "archflow": {
    "command": "node",
    "args": ["/caminho/absoluto/packages/mcp-server/dist/index.js"],
    "env": {
      "API_URL": "http://localhost:3001",
      "WEB_URL": "http://localhost:5173"
    }
  }
}

Substitua /caminho/absoluto pelo path real do projeto.

Conectar o MCP no Claude Code

Opcao 1: Arquivo .mcp.json no projeto (recomendado)

Crie um arquivo .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "archflow": {
      "command": "/caminho/absoluto/packages/mcp-server/run.sh",
      "args": []
    }
  }
}

O run.sh ja vem incluso no projeto e faz o cd e exec node automaticamente.

Opcao 2: Config global ~/.claude/.mcp.json

Adicione ao arquivo ~/.claude/.mcp.json:

{
  "mcpServers": {
    "archflow": {
      "command": "/caminho/absoluto/packages/mcp-server/run.sh",
      "args": []
    }
  }
}

Opcao 3: CLI

claude mcp add archflow -- /caminho/absoluto/packages/mcp-server/run.sh

Importante

• A API precisa estar rodando (pnpm dev ou pnpm --filter api dev) antes de iniciar o Claude Code, pois o MCP server se conecta a ela na inicializacao.
• Substitua /caminho/absoluto pelo path real, ex: /Users/seu-usuario/code/archflowbuilder
• Apos configurar, reinicie o Claude Code para que as tools mcp__archflow__* aparecam.

MCP Tools disponiveis

Canvas — funcionalidades

Zonas automaticas

Os services sao agrupados automaticamente em zonas visuais:

Cores das conexoes

Tipos de servicos

Tipos de conexoes

REST API

POST   /architectures              Criar
GET    /architectures              Listar todas
GET    /architectures/:id          Buscar por ID
PATCH  /architectures/:id          Atualizar (auto-incrementa versao)
PATCH  /architectures/:id/layout   Salvar posicoes dos nodes
DELETE /architectures/:id          Deletar
GET    /health                     Health check

Estrutura do projeto

archflowbuilder/
|-- packages/
|   |-- mcp-server/
|   |   |-- src/index.ts          <- 4 MCP tools
|   |   |-- dist/index.js         <- build output
|   |   +-- run.sh                <- wrapper script para Claude Code
|   |-- api/
|   |   |-- prisma/schema.prisma
|   |   +-- src/
|   |       |-- index.ts
|   |       |-- routes/architectures.ts
|   |       +-- middleware/validate.ts
|   +-- web/
|       +-- src/
|           |-- App.tsx
|           |-- types.ts
|           |-- pages/
|           |   |-- Home.tsx              <- lista de arquiteturas
|           |   +-- Workspace.tsx         <- canvas editor
|           +-- components/
|               |-- ArchNode.tsx          <- node de servico (resizable)
|               +-- ZoneNode.tsx          <- zona de agrupamento (draggable, resizable)
|-- .mcp.json                     <- config MCP para Claude Code
|-- CLAUDE.md                     <- instrucoes para Claude Code
|-- docker-compose.yml
|-- deploy.sh
+-- .env.example

Exemplo de uso

Com o MCP conectado, escreva no Cursor ou Claude Code:

Design a fintech onboarding system with KYC validation,
fraud scoring, and async notifications.

O AI vai:

1. Chamar create_architecture com os servicos e conexoes
2. Salvar no banco
3. Retornar o link: http://localhost:5173/arch/abc123
4. Voce abre e edita o diagrama interativo

Deploy completo com Docker

chmod +x deploy.sh
./deploy.sh

Roadmap

• MCP server com 4 tools
• REST API com versionamento automatico
• Canvas React Flow com drag & drop
• Layout hierarquico por zonas (dagre)
• Zonas draggaveis e redimensionaveis
• Edicao inline (servicos, zonas, conexoes)
• Adicionar/remover servicos e conexoes no canvas
• Display names humanizados vs IDs tecnicos
• Legenda de cores e tipos
• Export PNG/SVG
• Modo apresentacao (fullscreen)
• Persistencia de layout (posicoes e tamanhos)
• Edges coloridas por tipo (animadas para async)
• Validacao automatica (nos soltos, loops, SPOFs)
• Historico de versoes com diff
• Export para Markdown / docs
• Export para codigo (Apache Camel, Spring, etc.)
• Colaboracao em tempo real (WebSocket)

Licenca

MIT