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

Pacote	Tecnologia
packages/mcp-server	TypeScript, @modelcontextprotocol/sdk, zod
packages/api	Express, TypeScript, Prisma, PostgreSQL
packages/web	React, Vite, @xyflow/react, Tailwind CSS, dagre, html-to-image

---

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

Servico	URL
Web App	http://localhost:5173
API	http://localhost:3001
API Health	http://localhost:3001/health
DB Studio	pnpm --filter api db:studio

---

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

Tool	Quando e chamada
create_architecture	Design de um novo sistema
update_architecture	Evoluir uma arquitetura existente
get_architecture	Ler estado atual antes de modificar
list_architectures	Listar todas as arquiteturas salvas

---

Canvas — funcionalidades

Feature	Como usar
Editar servico	Click no node -> painel lateral com campos editaveis
Adicionar servico	Botao + Service na toolbar
Deletar servico	Click no node -> Delete Service no painel
Conectar nodes	Arrasta de um handle (bolinha) pra outro
Tipo de conexao	Dropdown na toolbar seleciona HTTP/Event/DB/gRPC
Deletar conexao	Seleciona a edge + tecla Delete
Mover zonas	Arrasta a zona -> todos os services dentro movem junto
Redimensionar	Seleciona node ou zona -> arrasta os handles nos cantos
Editar zona	Click na zona -> editar label no painel lateral
Re-layout	Botao Re-layout -> recalcula layout hierarquico
Salvar	Botao Save ou Cmd+S
Export PNG/SVG	Botoes na toolbar
Modo apresentacao	Botao Present ou Cmd+F, ESC pra sair
Copiar link	Botao Link na toolbar

Zonas automaticas

Os services sao agrupados automaticamente em zonas visuais:

Zona	Tipos de servico
Entry Points	api_gateway
Services & Workers	service
Data & Messaging	database, queue
External Systems	external

Cores das conexoes

Cor	Tipo
Azul	HTTP (sync)
Roxo (animado)	Event (async)
Amarelo	Database
Verde	gRPC

---

Tipos de servicos

Tipo	Usar para
api_gateway	Entry points, BFFs, reverse proxies
service	Logica de negocio, microservicos, workers
database	SQL, NoSQL, cache, object storage
queue	Kafka, SQS, RabbitMQ, mensageria async
external	APIs de terceiros (Stripe, Auth0, SendGrid...)

Tipos de conexoes

Tipo	Usar para
sync_http	REST, GraphQL
async_event	Eventos, pub/sub, filas
db_access	Servico -> banco de dados
grpc	Chamadas gRPC internas

---

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