Gerar diagramas de arquitetura
Use o IBM Bob para analisar a base de código do Galaxium Travels e gerar diagramas de classes UML Mermaid, diagramas de sequência e diagramas de casos de uso. Aprenda a usar menções de contexto no modo Ask para explorar código e o modo Agent para salvar os resultados no seu repositório.
Diagramas de arquitetura fornecem uma linguagem visual compartilhada para uma base de código antes de modificá-la. Neste tutorial, você usa o Bob para ler os arquivos fonte do Galaxium Travels e gerar três tipos de diagramas UML: um diagrama de classes UML, um diagrama de sequência e um diagrama de casos de uso. Você usa o modo Ask para explorar o código com segurança e gerar a marcação do diagrama, que usa Mermaid. Em seguida, você muda para o modo Agent para salvar os diagramas no projeto.
O GitHub fornece suporte nativo para diagramas Mermaid em arquivos Markdown, então você pode salvar os diagramas gerados como arquivos .md e visualizá-los
renderizados no GitHub.
Neste tutorial, a saída do Bob pode diferir dos exemplos dependendo do estado atual da base de código. Use a marcação gerada como ponto de partida e refine conforme necessário.
Recursos principais que você aprenderá
- Menções de contexto: Referencie
arquivos e pastas específicos em seus prompts usando o símbolo
@. As menções de contexto permitem que o Bob saiba exatamente quais arquivos analisar para gerar diagramas precisos. - Modo Ask: Leia e analise código sem que o Bob faça alterações em seus arquivos.
- Modo Agent: Deixe o Bob escrever arquivos autonomamente para persistir artefatos gerados em seu projeto.
Pré-requisitos
Para completar este tutorial, você precisa do seguinte:
- Bob IDE instalado.
- Git instalado localmente para que você possa clonar o repositório de exemplo Galaxium Travels.
- Familiaridade com os conceitos básicos do uso do Bob. Se você é novo no Bob, comece com o tutorial de início rápido.
Configure seu espaço de trabalho
Clone o repositório Galaxium Travels
No seu terminal, execute o seguinte comando para clonar o repositório de exemplo Galaxium Travels:
git clone https://github.com/ibm/galaxium-travels.gitInicie o IBM Bob
Inicie o IDE IBM Bob no seu computador.
Abra o projeto de exemplo
No IDE Bob, abra a pasta galaxium-travels que você clonou. Se o Bob perguntar "Você confia
nos autores dos arquivos na pasta?", clique em Sim, confio nos
autores.
Revise o arquivo README.md no diretório raiz para obter uma visão geral da aplicação e sua arquitetura. O aplicativo Galaxium Travels simula um sistema de reserva de voos com um frontend React, um backend Python FastAPI e um serviço de retenção de inventário Java. A base de código é intencionalmente complexa e representativa de aplicações do mundo real, tornando-a uma ótima candidata para gerar diagramas de arquitetura.
Abra a interface de chat do Bob
Se a interface de chat ainda não estiver aberta, clique no ícone Bob na barra de navegação ou use o atalho Option + Command + B (Mac) ou Ctrl + Alt + B (Windows).
Inicialize o contexto do projeto
O Bob inicia no modo Agent por padrão. Se você mudou de modo, certifique-se de mudar para o modo Agent antes de executar o comando de inicialização. O Bob precisa escrever arquivos para configurar o contexto do projeto.
Digite o comando /init no campo de entrada da interface de chat. Se você tiver
a aprovação automática desabilitada, o Bob pedirá permissão para ler arquivos e escrever os
arquivos AGENTS.md.
/initO Bob lê os arquivos relevantes no projeto. O Bob então gera o arquivo principal
AGENTS.md no diretório raiz. O Bob também cria uma
pasta .bob que contém um AGENTS.md para cada modo.
Revise os arquivos AGENTS.md gerados para entender como o Bob configurou o
contexto do projeto e quais capacidades o Bob tem em cada modo.
Mude para o modo Ask
Selecione Ask no seletor de modo abaixo do campo de entrada do chat. Você também pode
digitar /ask no campo de entrada do chat para mudar de modo.
Ao contrário do modo Agent, o modo Ask é somente leitura. O Bob pode ler e analisar arquivos, mas não pode criar ou modificar nada, tornando-o seguro para exploração de código.
Gere um diagrama de classes UML
Um diagrama de classes UML mapeia o modelo de dados de uma aplicação: as entidades (classes), seus atributos e os relacionamentos entre elas. Para o Galaxium Travels, isso cobre os modelos Python SQLAlchemy no backend e as classes de domínio Java no serviço de retenção de inventário.
Crie um prompt para analisar os modelos de dados em ambos os serviços e produzir um
classDiagram Mermaid. Use menções de contexto para especificar os arquivos relevantes para
o Bob analisar. Por padrão, o Bob gera o diagrama Mermaid como uma imagem renderizada.
Para revisar a marcação Mermaid bruta, adicione a instrução "Gere apenas o
bloco de código Mermaid. Não renderize o diagrama Mermaid." ao seu prompt.
No modo Ask, digite o seguinte prompt no campo de entrada do chat:
Analise os modelos de dados em @booking_system_backend/models.py e as
classes de domínio Java em @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain.
Gere um classDiagram Mermaid que mostre todas as classes, seus atributos,
seus métodos (se houver) e os relacionamentos entre elas.
Inclua o enum BookingStatus.
Gere a marcação Mermaid. Não renderize o diagrama Mermaid.O Bob lê ambos os arquivos e produz marcação de diagrama semelhante ao seguinte:
classDiagram
direction LR
%% ── Python / SQLAlchemy (booking_system_backend/models.py) ──────────
class User {
+int user_id PK
+str name
+str email
}
class Flight {
+int flight_id PK
+str origin
+str destination
+str departure_time
+str arrival_time
+int base_price
+int economy_seats_available
+int business_seats_available
+int galaxium_seats_available
}
class Booking {
+int booking_id PK
+int user_id FK
+int flight_id FK
+str status
+str booking_time
+str seat_class
+int price_paid
}
class BookingStatus {
<<enumeration>>
BOOKED = "booked"
CANCELLED = "cancelled"
CANCELED = "cancelled"
COMPLETED = "completed"
}
%% ── Java / JPA (holdservice/domain) ────────────────────────────────
class Quote {
+String quoteId PK
+Integer flightId
+String seatClass
+Integer quantity
+Integer travelerId
+String travelerName
+Long pricePerSeat
+Long totalPrice
+Instant expiresAt
+QuoteStatus status
+Instant createdAt
#onCreate() void
}
class QuoteStatus {
<<enumeration>>
CREATED
}
class Hold {
+String holdId PK
+String quoteId FK
+HoldStatus status
+Instant reservedUntil
+String externalBookingReference
+String errorMessage
+Instant createdAt
+Instant updatedAt
#onCreate() void
#onUpdate() void
}
class HoldStatus {
<<enumeration>>
HELD
EXPIRED
CONFIRMED
RELEASED
CONFIRMATION_FAILED
}
class AuditEvent {
+String eventId PK
+String entityType
+String entityId
+String eventType
+String details
+Instant createdAt
#onCreate() void
}
%% ── Relationships ───────────────────────────────────────────────────
User "1" --> "0..*" Booking : places
Flight "1" --> "0..*" Booking : booked on
Booking ..> BookingStatus : status
Quote "1" --> "0..*" Hold : generates
Quote ..> QuoteStatus : status
Hold ..> HoldStatus : status
AuditEvent ..> Quote : references entityId
AuditEvent ..> Hold : references entityIdGere um diagrama de sequência
Um diagrama de sequência mostra como os componentes interagem em tempo de execução em um fluxo específico, ordenado por tempo. O fluxo de reserva do Galaxium Travels abrange o frontend React, o backend Python FastAPI e o serviço de retenção de inventário Java.
Crie um prompt para rastrear o fluxo completo de reserva e produzir um
sequenceDiagram Mermaid. Use menções de contexto para especificar os arquivos relevantes para o Bob
analisar. Quanto mais específico você for em seu prompt sobre quais arquivos analisar
e qual fluxo você deseja diagramar, mais precisa será a saída.
No modo Ask, digite o seguinte prompt no campo de entrada do chat:
Analise o fluxo de reserva em @booking_system_frontend/src/services,
@booking_system_backend/server.py, @booking_system_backend/services/booking.py,
e @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/api.
Gere um sequenceDiagram Mermaid mostrando o fluxo completo para um
usuário reservando um voo, incluindo as etapas de cotação e retenção com o serviço Java.
Gere a marcação Mermaid. Não renderize o diagrama Mermaid.O Bob rastreia a cadeia de interação e produz marcação de diagrama semelhante ao seguinte:
sequenceDiagram
autonumber
participant U as User (Browser)
participant FE as Frontend<br/>(api.ts)
participant PY as Python Backend<br/>(server.py)
participant BS as BookingService<br/>(booking.py)
participant QC as QuoteController<br/>(Java)
participant QS as QuoteService<br/>(Java)
participant HC as HoldController<br/>(Java)
participant HS as HoldService<br/>(Java)
participant DB as Python SQLite
participant JDB as Java SQLite
Note over U,JDB: ── Phase 1: Create Quote ──────────────────────────────────
U->>FE: createQuote({ flightId, seatClass,<br/>quantity, travelerId, travelerName })
FE->>PY: POST /quotes
PY->>QC: POST /api/v1/quotes
QC->>QS: createQuote(request)
QS->>QS: generateQuoteId() → "Q-2025-000001"
QS->>QS: pricingService.calculatePrice(flightId, seatClass)
QS->>JDB: save Quote (status=CREATED, expiresAt=+24h)
QS->>JDB: save AuditEvent (QUOTE / CREATED)
QC-->>PY: 201 Quote
Note right of PY: Returns {"error":"..."} HTTP 200<br/>if Java service unreachable
PY-->>FE: Quote JSON
FE->>FE: assertNotProxyError(response.data)
FE-->>U: quoteId
Note over U,JDB: ── Phase 2: Create Hold ───────────────────────────────────
U->>FE: createHold(quoteId)
FE->>PY: POST /quotes/{quoteId}/holds
PY->>HC: POST /api/v1/quotes/{quoteId}/holds
HC->>HS: createHold(quoteId)
HS->>JDB: findById(quoteId)
JDB-->>HS: Quote
HS->>HS: check quote not expired
HS->>HS: generateHoldId() → "H-2025-000001"
HS->>JDB: save Hold (status=HELD,<br/>reservedUntil=+15min)
HS->>JDB: save AuditEvent (HOLD / CREATED)
HC-->>PY: 201 Hold
PY-->>FE: Hold JSON
FE->>FE: assertNotProxyError(response.data)
FE-->>U: holdId
Note over U,JDB: ── Phase 3: Confirm Hold → Create Booking ─────────────────
U->>FE: confirmHold(holdId)
FE->>PY: POST /holds/{holdId}/confirm
PY->>HC: POST /api/v1/holds/{holdId}/confirm
HC->>HS: confirmHold(holdId)
HS->>JDB: findById(holdId)
JDB-->>HS: Hold
HS->>HS: check status == HELD
HS->>HS: check reservedUntil not passed
HS->>JDB: findById(hold.quoteId)
JDB-->>HS: Quote
HS->>PY: POST /internal/bookings/from-hold<br/>{ travelerId, travelerName, flightId, seatClass }
PY->>BS: book_flight(db, user_id, name,<br/>flight_id, seat_class)
BS->>DB: query Flight (check seats available)
BS->>DB: query User (validate user_id + name match)
BS->>DB: decrement {seat_class}_seats_available
BS->>DB: insert Booking (status="booked")
DB-->>BS: Booking row
BS-->>PY: BookingOut
alt booking succeeded
PY-->>HS: 200 { booking_id, ... }
HS->>JDB: update Hold (status=CONFIRMED,<br/>externalBookingReference=booking_id)
HS->>JDB: save AuditEvent (HOLD / CONFIRMED)
HC-->>PY: 200 Hold (CONFIRMED)
PY-->>FE: Hold JSON
FE->>FE: assertNotProxyError(response.data)
FE-->>U: Booking confirmed ✓
else booking failed (name mismatch / no seats / user not found)
PY-->>HS: 400 { error, error_code, details }
HS->>JDB: update Hold (status=CONFIRMATION_FAILED,<br/>errorMessage=...)
HS->>JDB: save AuditEvent (HOLD / CONFIRMATION_FAILED)
HC-->>PY: 400 Bad Request
PY-->>FE: error response
FE-->>U: Error shown to user ✗
endGere um diagrama de casos de uso
Um diagrama de casos de uso identifica os atores em um sistema e as capacidades que cada
ator pode exercer. O Mermaid não tem um tipo de diagrama de casos de uso nativo, então você
representa isso com um flowchart LR que agrupa casos de uso por ator.
Crie um prompt para identificar todos os atores e seus casos de uso em toda a aplicação. Os atores incluem tipos de usuários e sistemas externos. Use menções de contexto para especificar os arquivos relevantes para o Bob analisar, incluindo as páginas frontend, endpoints REST backend e ferramentas MCP. Quanto mais específico você for em seu prompt sobre quais arquivos analisar, mais precisa será a saída. Além disso, instrua o Bob a escapar chaves na marcação Mermaid para que o renderizador Mermaid não tente interpretar as chaves como sintaxe de template.
No modo Ask, digite o seguinte prompt no campo de entrada do chat:
Analise a aplicação completa Galaxium Travels.
Identifique todos os atores (tipos de usuários ou sistemas externos) e os casos de uso que cada
ator pode executar, com base nas páginas frontend, endpoints REST backend
e ferramentas MCP.
Gere um flowchart LR Mermaid que represente isso como um diagrama de casos de uso,
agrupando casos de uso sob seus respectivos atores usando subgrafos.
Escape chaves na marcação Mermaid para que o renderizador Mermaid não
tente interpretar as chaves como sintaxe de template.
Gere a marcação Mermaid. Não renderize o diagrama Mermaid.O Bob analisa a aplicação e produz marcação de diagrama semelhante ao seguinte:
flowchart LR
subgraph Traveller["👤 Traveller (Browser)"]
T1[Browse available flights]
T2[Search flights by origin / destination]
T3[Filter flights by date, price, seat class,\nduration, route category, time period]
T4[Register account]
T5[Sign in with name and email]
T6[Select seat class\neconomy / business / galaxium]
T7[Get price quote]
T8[Place seat hold - 15-minute timer]
T9[Confirm hold and create booking]
T10[Release hold]
T11[View active bookings]
T12[View past bookings]
T13[Cancel booking]
T14[View pending holds with countdown]
T15[Dismiss expired hold]
end
subgraph AIAgent["🤖 AI Agent (MCP Client)"]
A1[list_flights]
A2[register_user]
A3[get_user_id]
A4[book_flight]
A5[get_bookings]
A6[cancel_booking]
end
subgraph JavaService["☕ Java Hold Service\n(Internal System)"]
J1[Confirm hold via POST /internal/bookings/from-hold]
J2[Auto-expire holds after timeout]
end
subgraph RestAPI["🐍 Python REST API\n(External Consumers / Swagger)"]
R1[GET /flights — list and filter flights]
R2[POST /register — register user]
R3[GET /user — look up user by name and email]
R4[POST /book — book a flight]
R5[GET /bookings/{user_id} — get user bookings]
R6[POST /cancel/{booking_id} — cancel booking]
R7[POST /quotes — create quote proxy]
R8[GET /quotes/{id} — get quote proxy]
R9[POST /quotes/{id}/holds — create hold proxy]
R10[GET /holds/{id} — get hold proxy]
R11[POST /holds/{id}/confirm — confirm hold proxy]
R12[POST /holds/{id}/release — release hold proxy]
R13[GET / — health check]
end
Traveller -->|uses frontend which calls| RestAPI
AIAgent -->|MCP over HTTP at /mcp| RestAPI
JavaService -->|calls back via internal endpoint| RestAPISalve os diagramas no repositório
Mude o Bob para o modo Agent e peça para ele salvar os diagramas que você gerou no
repositório. Cada diagrama é salvo como um arquivo Markdown em uma nova
pasta docs/architecture/.
Mude para o modo Agent
Selecione Agent no seletor de modo, ou digite /agent no campo de entrada do chat.
Salve todos os três diagramas
Peça ao Bob para criar os arquivos de documentação de arquitetura.
Crie uma pasta docs/architecture/ na raiz do repositório.
Salve cada um dos três diagramas que geramos como arquivos Markdown individuais:
- class-diagram.md — o diagrama de classes UML
- sequence-diagram.md — o diagrama de sequência do fluxo de reserva
- use-case-diagram.md — o diagrama de fluxo de casos de uso
Cada arquivo deve ter um título curto, o bloco de código Mermaid que
geramos e uma breve descrição do diagrama.O Bob cria os três arquivos. Clique em Approve e Save para cada arquivo que o Bob escreve.
Verifique a saída
Abra cada arquivo no explorador de arquivos do Bob para confirmar que os blocos de código Mermaid delimitados estão presentes. Você tem estas opções para verificar os diagramas:
-
Peça ao Bob para mostrar uma prévia do arquivo Markdown.
No campo de entrada do chat, digite o seguinte prompt:
Mostre-me uma prévia de docs/architecture/class-diagram.mdO Bob renderiza o arquivo Markdown, incluindo o diagrama Mermaid, na interface de chat. Clique no diagrama renderizado para abri-lo em uma visualização maior.
Você pode fazer isso para cada um dos três arquivos para ver todos os diagramas renderizados.
-
Cole a marcação do diagrama no Mermaid Live Editor para visualizar o diagrama renderizado.
-
Faça commit e push das alterações para um repositório GitHub. Em seguida, visualize os arquivos no GitHub para ver os diagramas renderizados.
Solução de problemas
O Bob gera marcação Mermaid que não compila
O parser do Mermaid é rigoroso. Mesmo um único caractere inválido, uma palavra-chave não suportada ou uma quebra de linha ausente pode fazer com que um diagrama falhe silenciosamente ou gere um erro de análise. Use a seguinte abordagem para diagnosticar e corrigir o problema.
Identifique a linha com falha
Quando o Bob produz um erro de análise, a saída inclui o número da linha e um trecho do código problemático.
Se o Bob não gerar um erro de parser, cole a marcação no Mermaid Live Editor. O editor destaca a linha problemática e mostra o erro de parser, o que pode ajudá-lo a identificar o problema.
Você também pode inspecionar visualmente a marcação em busca de problemas comuns, como caracteres especiais sem escape em rótulos, subgrafos não fechados ou erros de sintaxe em setas.
| Sintoma | Causa provável | Solução |
|---|---|---|
Erro de análise perto de { ou } | Chaves sem escape em rótulos de nós flowchart ou classDiagram | Substitua { por { e } por }, ou reformule o rótulo |
Erro de análise perto de ( ou ) | Parênteses em um ID de nó | Envolva o rótulo entre aspas: A["label (note)"] |
Erro end ou subgraph inesperado | Subgrafo não fechado | Certifique-se de que cada bloco subgraph tenha um end correspondente |
| Tipo de seta não reconhecido | Sintaxe de seta errada para o tipo de diagrama | --> é para flowchart; classDiagram usa -->, ..>, --|> etc.; sequenceDiagram usa ->>, -->> |
| Nó definido mas não conectado | Nó órfão não causa erro, mas pode confundir alguns renderizadores | Conecte o nó ou remova-o |
| Diagrama renderiza parcialmente e depois para | Rótulo contém um caractere " sem escape | Escape aspas dentro de rótulos: A["it\'s a label"] |
Peça ao Bob para corrigir o problema
Dê ao Bob o erro de parser e a linha com falha. Em seguida, peça ao Bob para corrigir linhas específicas.
Por exemplo:
O classDiagram Mermaid falha ao analisar com este erro:
Parse error on line 42: ...unexpected token 'NEWLINE'
Aqui está o bloco relevante:
Booking ..> BookingStatus : status (active)
Corrija a sintaxe para que compile sem alterar a estrutura do diagrama.O Bob pode fazer uma correção direcionada sem regenerar conteúdo que você já revisou.
Peça ao Bob para validar antes de gerar
Se você estiver regenerando um diagrama do zero, adicione uma instrução de validação explícita ao prompt:
Antes de gerar o bloco Mermaid, analise-o mentalmente e confirme que cada ID de nó
é válido, cada subgrafo está fechado e todos os caracteres especiais em rótulos estão escapados.Reduza o escopo quando o diagrama for grande
Se um diagrama com muitos nós continuar produzindo marcação inválida, peça ao Bob para gerá-lo em seções, como os modelos Python primeiro e depois os modelos Java. Depois, peça ao Bob para montar os blocos. Gerações menores são mais fáceis para o Bob validar e mais fáceis para você comparar.
Próximos passos
Neste tutorial, você usou menções de contexto e o modo Ask para explorar a base de código do Galaxium Travels e gerar três tipos de diagramas de arquitetura com o Bob, depois usou o modo Agent para salvá-los no repositório. Continue com os seguintes recursos:
- Explore os tutoriais de introdução do Bob para aprender mais sobre as capacidades do Bob com o aplicativo Galaxium Travels.
- Siga o tutorial Planejar e implementar recursos complexos para usar o fluxo de trabalho Plan → Agent para adicionar novas funcionalidades.
- Leia as melhores práticas do Bob para aprender estratégias eficazes de prompting para usar o Bob.
Explorar uma base de código desconhecida
Use o IBM Bob para entender rapidamente uma aplicação desconhecida — seu propósito, estrutura do projeto, arquitetura, stack tecnológica, componentes principais, cobertura de testes e modelo de implantação. Tudo isso sem depender de documentação desatualizada ou esperar por colegas.
Gera relatórios de auditoria e documentação de conformidade
Usa o IBM Bob para analisar a base de código do Galaxium Travels e produzir relatórios de auditoria estruturados cobrindo qualidade de código, saúde de dependências, dívida técnica e postura de conformidade. Aprende a montar documentação pronta para stakeholders a partir de análise assistida por IA.