Visão Geral da Aplicação: Arch Studio

O Arch Studio é uma ferramenta de diagramação visual avançada e interativa, construída com foco na bidirecionalidade entre código e interface gráfica. A aplicação utiliza Mermaid.js para a definição semântica dos diagramas e ReactFlow como motor de renderização e interação no canvas. O principal diferencial da ferramenta é tratar os nós do diagrama como componentes nativos do ReactFlow (e não como imagens estáticas), permitindo edição completa diretamente no canvas visual.

Pilares Arquiteturais

1. Sistema de Renderização Nativo (Mermaid → ReactFlow)

A aplicação atua como um tradutor bidirecional. Em vez de renderizar o output SVG tradicional do Mermaid, ela converte a Árvore de Sintaxe Abstrata (AST) do Mermaid em tipos customizados de nós no ReactFlow:

• A[Texto]: Nó Retângulo (diagram-node).
• A(Texto): Nó Arredondado (diagram-node-rounded).
• A{Decisão}: Nó Losango (diagram-decision).
• A((Círculo)): Nó Circular (diagram-circle).
• subgraph: Grupo de nós colapsável (diagram-group).
• Edges (-->): Conexões nativas customizáveis.
• Comportamento de todos os elementos: Arrastáveis, editáveis (inline) e redimensionáveis.

2. Sistema de Anotações (Annotations)

As anotações funcionam como "sticky notes" flexíveis na arquitetura, operando em dois modos distintos:

• Modo Vinculado (Target): A anotação possui uma referência a um nó alvo. Ela é renderizada com um conector visual (linha tracejada) que acompanha dinamicamente a posição do nó alvo.
• Modo Livre (Position): A anotação é inserida em coordenadas fixas (X, Y) do canvas, comportando-se como um nó independente flutuante.

3. Sincronização Bidirecional e Source of Truth

• Em Tempo de Execução (Runtime): O Source of Truth (fonte da verdade) é o estado nativo do ReactFlow (os nós e arestas na tela). O texto Mermaid visível para o usuário é, na verdade, uma view derivada gerada a partir do estado atual do canvas visual.
• Fluxo de Edição:
• Edição Visual: Alterar o canvas recompila e atualiza o código Mermaid instantaneamente.
• Edição de Código: O usuário edita o texto Mermaid, o serializer processa as mudanças e o canvas é redesenhado com as novas regras.

Arch Studio (arch.studio) — Product Manifesto & Specifications

1. Visão Geral do Produto

O Arch Studio (arch.studio) é um ambiente de design e documentação arquitetural hiper-focado na produtividade de Arquitetos de Software e Engenheiros Principais.

Tradicionalmente, a arquitetura de um sistema sofre de fragmentação extrema: diagramas vivem em ferramentas visuais (Miro, Lucidchart), regras de negócio residem no Confluence, exemplos de código ficam perdidos no repositório e anotações técnicas morrem em cadernos físicos ou canais do Slack. Essa fragmentação gera obsolescência imediata da documentação e desaliamento técnico.

O Arch Studio resolve este problema através do conceito de Single File Architecture Source (SFAS). Toda a inteligência de design da aplicação — incluindo diagramas interativos, anotações de engenharia, snippets de código estruturantes e definições de regras de negócios — é consolidada e sincronizada em um único arquivo baseado em XML enriquecido.

Além de servir como a "fonte única da verdade" visual e textual para humanos, este formato estruturado foi projetado nativamente para ser o input perfeito para ferramentas de Inteligência Artificial, funcionando como um mapa contextual ultra-preciso para a geração automática de código, testes e infraestrutura.

2. Princípios de Design do Produto

Seguindo a filosofia minimalista, técnica e de alta performance estabelecida pelo turing-autopilot, o Arch Studio é guiado por quatro pilares fundamentais:

I. Consolidação Absoluta (A Regra do Arquivo Único)

Chega de alternar entre 5 ferramentas para entender um microsserviço. Se faz parte do design do sistema, pertence ao arquivo .arch (XML). O arquivo encapsula a semântica (Mermaid), a geometria visual (ReactFlow) e o contexto técnico (Markdown, regras e código).

II. Bidirecionalidade Sem Perdas (Visual-as-Code)

O código não é um subproduto do diagrama, e o diagrama não é apenas uma renderização do código. Ambos são representações isomórficas do mesmo estado técnico. Alterar o código atualiza o canvas instantaneamente; arrastar ou redimensionar um nó no canvas regenera o código sem destruir os metadados.

III. Manipulação Nativa de Objetos

Diagramas gerados a partir de código não devem ser estáticos. Cada nó derivado do texto Mermaid é transformado em um objeto ReactFlow totalmente interativo (arrastável, redimensionável e editável inline). O layout automático existe para dar o pontapé inicial, mas o controle estético e organizacional final pertence inteiramente ao arquiteto.

IV. IA-Readiness (Pronto para a Era dos LLMs)

Arquivos de imagem tradicionais (.png, .svg) e diagramas puramente visuais são "caixas pretas" para modelos de linguagem. Ao estruturar toda a arquitetura em um XML semântico bem definido, o Arch Studio transforma diagramas complexos em contextos altamente digeríveis para IAs (como Claude e Gemini) agirem como agentes autônomos de desenvolvimento.

3. Arquitetura do Arquivo: O Formato .arch (XML)

Para atingir esses objetivos, a aplicação utiliza um formato de persistência proprietário baseado em XML. Este arquivo armazena três camadas cruciais da aplicação:

1. Camada Semântica: O código Mermaid puro que dita os relacionamentos lógicos.
2. Camada de Enriquecimento Visual (Enrichments): Coordenadas (X, Y), dimensões, cores e estados (como subgráficos colapsados) controlados via ReactFlow.
3. Camada de Contexto Técnico: Anotações livres ou vinculadas, regras de negócio em Markdown e exemplos de implementação associados a nós específicos.

Exemplo Conceitual da Estrutura XML:

<?xml version="1.0" encoding="UTF-8"?>
<diagram id="diag-001" version="1.0">
  <metadata>
    <name>Fluxo de Checkout</name>
    <description>...</description>
    <author>Rafael</author>
    <created>2026-06-08T10:00:00Z</created>
    <tags><tag>checkout</tag><tag>payment</tag></tags>
  </metadata>

  <!-- Código mermaid original preservado -->
  <source syntax="mermaid"><![CDATA[
    graph TD
      A[Início] --> B{Pagamento?}
      B -->|Cartão| C[Gateway]
      B -->|Pix| D[QRCode]
  ]]></source>

  <!-- Enriquecimentos por nó/aresta -->
  <annotations>
    <annotation target="B" type="business-rule">
      <title>Regra de Roteamento</title>
      <content><![CDATA[
        Se valor > R$500, exigir 2FA antes do pagamento.
        Ref: REQ-042
      ]]></content>
      <priority>high</priority>
    </annotation>

    <annotation target="C" type="code-snippet">
      <title>Implementação Gateway</title>
      <language>typescript</language>
      <content><![CDATA[
        await gateway.charge({ amount, token, idempotencyKey });
      ]]></content>
    </annotation>

    <annotation target="B->C" type="note">
      <content>Timeout de 30s configurável via env</content>
      <links>
        <link href="docs/payment-gateway.md" label="Doc Gateway"/>
        <link href="https://stripe.com/docs" label="Stripe API"/>
      </links>
    </annotation>
  </annotations>

  <!-- Customizações visuais (não existem no mermaid) -->
  <styles>
    <node-style target="C" backgroundColor="#e8f5e9" borderColor="#4caf50" icon="credit-card"/>
    <node-style target="D" backgroundColor="#fff3e0" borderColor="#ff9800" icon="qr-code"/>
    <edge-style target="B->C" color="#4caf50" strokeWidth="2" animated="true"/>
  </styles>

  <!-- Layout manual (posições do ReactFlow) -->
  <layout engine="dagre" direction="TD">
    <position nodeId="A" x="200" y="50"/>
    <position nodeId="B" x="200" y="150"/>
    <position nodeId="C" x="100" y="300"/>
    <position nodeId="D" x="300" y="300"/>
  </layout>
</diagram>

4. Funcionalidades Principais (Core Features)

4.1. O Canvas Vivo (ReactFlow Engine)

• Elementos customizados: Diferente de renderizadores estáticos, cada nó se transforma em um componente React com ciclo de vida próprio (diagram-node, diagram-decision, diagram-group).
• Edição Contextual Inline: Dando duplo clique em qualquer nó ou aresta, o arquiteto pode redefinir seu texto diretamente na tela, o que atualiza a árvore sintática e o painel de código lateral em tempo real.
• Subgrupos Inteligentes: Subgraphs do Mermaid viram nós herdeiros (parent nodes) no ReactFlow. Eles podem ser expandidos ou colapsados para esconder a complexidade de subsistemas sem perder as conexões externas.

4.2. Sistema de Anotações Dual-Mode

As anotações funcionam como cartões de informação contextualizados:

1. Modo Vinculado (Targeted): A anotação fica "presa" magneticamente a um nó de arquitetura através de uma linha tracejada (connector edge). Quando o nó se move, a anotação o acompanha, mantendo o contexto visual intacto.
2. Modo Livre (Floating): Funciona como um sticky note independente no espaço tridimensional do canvas, ideal para notas globais do sistema ou checklists de débito técnico.

4.3. Hub de Regras de Negócio e Snippets

Cada cartão de documentação ou nó do sistema suporta Markdown rico completo. Isso permite acoplar blocos de código arquiteturais estruturantes (ex: formato exato de um payload JSON, contrato de uma API gRPC, configuração de infraestrutura como código) exatamente onde eles fazem sentido: ao lado do componente que os executa.

5. O Pipeline de Desenvolvimento Orientado a IA (AI-Driven Pipeline)

O grande divisor de águas do Arch Studio é preparar o trabalho do arquiteto para o consumo automatizado de ferramentas de inteligência artificial.

+------------------+     Sincroniza      +-----------------------+
|  Painel Visual   | <-----------------> | Código Fonte (.arch)  |
| (Canvas de Nós)  |                     | (XML Semântico Rico)  |
+------------------+                     +-----------------------+
                                                     |
                                                     | É enviado como Input / Semente
                                                     v
                                         +-----------------------+
                                         |   Agente de IA / LLM  |
                                         +-----------------------+
                                                     |
                                                     v
                                         +-----------------------+
                                         | Código Pronto Gerado  |
                                         | (Infra, Apps, Testes) |
                                         +-----------------------+

Como a IA consome o arquivo .arch:

1. Contexto Topológico Perfeito: Ao invés de ler um texto corrido e confuso, a IA entende exatamente as dependências do sistema através do bloco <source-code type="mermaid">.
2. Intencionalidade de Negócio: Através das tags <annotation>, a IA recebe os requisitos não-funcionais (performance, segurança) e regras de negócio atrelados diretamente aos nós corretos.
3. Casos de Uso Imediatos:

• Geração de Boilerplates/Scaffolding: Passar o arquivo .arch para um agente de IA permite que ele crie toda a árvore de diretórios do repositório, configurando gateways, serviços e schemas de banco exatamente como desenhado.
• Validação de Código Automatizada: Em pipelines de CI/CD, a IA pode ler o arquivo de arquitetura e validar se o código real escrito pelos desenvolvedores não quebrou nenhuma regra de dependência ou restrição descrita no arquivo único.

6. Roadmap Técnico Inicial (Scaffolding)

Para a implementação no diretório local /Users/rbarbosa/Documents/Repos/arch-studio, o projeto seguirá a seguinte fundação:

1. Setup da Tech Stack: Next.js (App Router), TypeScript, Tailwind CSS (Design System escuro/técnico similar ao turing-autopilot).
2. Core Component Engine: Instalação e customização do reactflow com desativação de controles rígidos e ativação de nós customizados.
3. Parser Bidirecional: Criação do módulo src/lib/serializer encarregado de ler o XML, extrair o Mermaid, mapear os estados do ReactFlow e remontar o XML em cada alteração de estado.
4. UI Workspace: Painel dividido (Split Screen) com o Editor de Código / Documentação à esquerda e o Canvas Interativo à direita.