airgraph-studio

Um studio front-end para visualizar e brincar com DAGs de pipelines (estilo Airflow), com foco em aprender e praticar algoritmos de grafos + visualização.

• Layout: elkjs (ELK / layered)
• Render/Interações: d3 (SVG, zoom/pan, hover, highlight)
• UI: React + Vite + TypeScript
• State: Zustand (4 slices: graph, layout, ui, viewport)
• Styling: Tailwind + shadcn/ui

Objetivos (MVP)

1. Renderizar um DAG (nodes + edges) a partir de um arquivo (ex: YAML/JSON).
2. Rodar layout com ELK (left-to-right) e desenhar no SVG com D3.
3. Interações essenciais: zoom/pan, selecionar nó/aresta, highlight upstream/downstream.
4. Validar DAG (detectar ciclos) e sinalizar problemas no UI.

Requisitos

• Node.js >= 20
• pnpm (recomendado)
• Git

Instalação

git clone <SEU_REPO.git>
cd airgraph-studio

pnpm install
pnpm dev

Acesse o endereço que o Vite mostrar no terminal.

Scripts

Script	Descrição
dev	Roda localmente com HMR
build	Build de produção
preview	Preview do build
test	Testes unitários
lint	Lint
format	Formatação

Observação: se algum script ainda não existir no repo, trate como "contrato" do projeto — a gente cria conforme implementa.

Estrutura de diretórios

airgraph-studio/
  apps/
    studio/                     # app web (Vite + React)
      src/
        features/               # vertical slices
          canvas/               # SVG + D3 rendering
          inspector/            # side panel
          importer/             # YAML/JSON import
        store/                  # Zustand store + slices
        shared/                 # app-level utils
        main.tsx
        App.tsx
      index.html
      vite.config.ts

  packages/
    graph-core/                 # tipos + algoritmos (validateDag, topoSort, traversals)
    layout-elk/                 # adapter ELK (Graph → PositionedGraph)
    render-d3/                  # renderer D3/SVG (paths, zoom, hit testing)

  docs/
    overview.md
    getting_started.md
    instructions.md

  prompts/                      # prompts modulares para dev agent
    system/                     # convenções globais
    features/                   # prompts por feature
    recipes/                    # combinações de prompts
    snippets/                   # blocos reutilizáveis

  .editorconfig
  .gitignore
  package.json
  pnpm-workspace.yaml
  tsconfig.base.json

Diretrizes de contribuição

Branch / Commits

• Branch: feat/..., fix/..., chore/...
• Commits: preferir Conventional Commits (feat:, fix:, docs:)

Qualidade

• Todo algoritmo de grafo em packages/graph-core deve ter teste unitário.
• Componentes e hooks críticos (zoom/pan, selection, highlight) devem ter pelo menos testes de lógica (e2e depois).

PR checklist (padrão)

• Passa test
• Passa lint
• Sem warnings relevantes no console
• README/docs atualizados quando mudar contratos

Roadmap (curto)

• Import/export YAML (schema de pipeline)
• Ciclos: detectar e destacar arestas do ciclo
• Highlight upstream/downstream
• Cluster/Group por stage (RAW/CUR/BI)
• Mini-map + search
• Undo/redo
• Persistência de preferências (tema/layout)