Inspect an unfamiliar codebase
Use IBM Bob to rapidly understand an unfamiliar application, such as its purpose, project structure, architecture, tech stack, key components, test coverage, and deployment model. You can do this without relying on outdated documentation or waiting for teammates.
Getting productive in an unfamiliar codebase typically means hours of reading code, looking for documentation, and asking teammates for context. In this tutorial, you use Bob in Ask mode to systematically interrogate the Galaxium Travels codebase and extract a complete picture of the application: its purpose and architecture, tech stack, key components, unit and integration test coverage, and deployment model. You then switch to Agent mode to save everything Bob discovered into a persistent Markdown reference that your whole team can use.
Galaxium Travels is an intentionally complex, real-world-style application that has a React frontend, a Python FastAPI backend, and a Java Spring Boot inventory hold service. This makes it a strong candidate for this workflow.
Bob's output varies depending on the current state of the codebase. Treat the examples in this tutorial as representative starting points, not exact transcripts. Use them to calibrate your own prompts and refine the results.
Key features you learn
- Ask mode: Explore and analyze code without Bob modifying any files.
- Agent mode: Let Bob write files autonomously to persist generated artifacts to your project.
- Context mentions: Reference
specific files and folders with
@to give Bob precise scope for analysis. /init: Initialize project context so Bob understands the codebase conventions before you start asking questions.
Prerequisites
To complete this tutorial, you need the following:
- Bob IDE installed.
- Git installed locally.
- Familiarity with the basics of using Bob. If you are new to Bob, complete the Quickstart tutorial first.
Set up your workspace
Clone the Galaxium Travels repository
In your terminal, clone the example repository:
git clone https://github.com/IBM/galaxium-travels.gitOpen the example project
In the Bob IDE, open the galaxium-travels folder you just cloned. If Bob asks
"Do you trust the authors of the files in the folder?", click Yes, I trust
the authors.
Open the Bob chat interface
If the chat interface is not already open, click the Bob icon in the navigation bar or use the shortcut Option + Command + B (Mac) or Ctrl + Alt + B (Windows).
Initialize project context
Bob defaults to Agent mode on startup. Before switching modes, run the /init
command so Bob reads the project and generates the AGENTS.md context files it
uses in subsequent interactions.
/initIf auto-approval is disabled, Bob asks permission to read files and write the
AGENTS.md files. Approve each request. Bob creates a root-level AGENTS.md
and a .bob/ folder with mode-specific configuration.
Review the generated AGENTS.md to confirm that Bob correctly identified the
multi-service structure of the repository.
Switch to Ask mode
Select Ask in the mode selector below the chat input field, or type /ask
to switch modes. Ask mode is strictly read-only. Bob analyzes files but cannot
create or modify anything, making it the right mode for all the exploration work
in this tutorial.
Understand the application purpose and project structure
Start with the broadest question: what does this application do, and how is the
codebase organized? Bob reads the project structure and key files, such as
README.md, package.json, requirements.txt, build files, and other
configuration files. Bob synthesizes a concise summary without you having to
manually trace through every directory.
In Ask mode, enter the following prompt:
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.Bob reads the file tree and key entry points, then produces output that includes the following:
- Application purpose
- Top-level directory responsibilities
- A synopsis of each top-level directory's contents
- High-level architecture diagram
Analyze the tech stack
With the high-level structure clear, drill into the exact technologies in use. This prompt is useful when you need to understand build tooling, evaluate dependency choices, or assess upgrade scope.
In Ask mode, enter the following prompt:
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.Bob inspects the dependency and configuration files for each service and produces output that includes:
- Detailed tech stack analysis for each service
- End-to-end testing framework identification
- Additional tooling from the CI/CD stack and deployment scripts
- A "Stack at a Glance" diagram that visually summarizes the tech stack across all services and layers
Map the key components
Understanding the tech stack tells you what a codebase uses; understanding the key components tells you how it works. This prompt asks Bob to trace the component boundaries and data flows across all three services, which is especially useful before making changes that cut across service boundaries.
In Ask mode, enter the following prompt with context mentions to point Bob at the most relevant files:
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.Bob traces the interaction chain and produces output that contains:
- Detailed frontend, backend API, database layer, and Java hold service component responsibilities
- A diagram breakdown of the two booking lifecycle flows with component interactions annotated
- A summary of the five cross-service contracts that you must know before making changes
- A component interaction map
Assess unit test coverage
Before adding features or refactoring, you need to know what the existing test suite covers and where the gaps are. This prompt asks Bob to read the test files and produce a coverage assessment without running the tests.
In Ask mode, enter the following prompt:
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.Bob reads the test files and produces a detailed test suite analysis that includes:
- Testing framework, classes under test, number of tests per class, and what is verified per class for each service
- Critical gaps in testing
- Missing test coverage for critical business logic
Assess integration and end-to-end test coverage
Unit tests tell you whether individual components work in isolation; integration and end-to-end tests tell you whether the services work correctly together. This is particularly important for Galaxium Travels because the booking confirmation flow spans all three services.
In Ask mode, enter the following prompt:
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.Bob reads the end-to-end test suite and generates detailed end-to-end test coverage analysis that includes:
- Test infrastructure and requirements to run the suite
- Smoke tests
- Key infrastructure decisions
- Cross-service flows both covered and not covered
- Test assertions at the boundary level
Review the deployment model
Understanding how an application is deployed (its target platforms, containerization strategy, and infrastructure automation) is essential before you onboard as a contributor or before you run the application anywhere beyond your laptop.
In Ask mode, enter the following prompt:
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.Bob reads the deployment artifacts and produces a deployment model analysis. The analysis includes:
- Supported deployment targets
- Containerization strategy for each service
- Infrastructure provisioning details
- CI/CD workflows
- Key deployment constraints and gaps
Save your findings to the repository
The analysis you produced in Ask mode lives only in the chat session. Switch to Agent mode to ask Bob to write a persistent onboarding reference document to the repository, so future contributors can benefit from this work.
Switch to Agent mode
Select Agent in the mode selector, or type /agent in the chat input field.
Create the onboarding reference
Ask Bob to consolidate everything it discovered into a single Markdown file. Bob has the full context of the conversation and synthesizes findings without re-reading all the files.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.Bob writes the file. If auto-approval is disabled, click Approve when Bob
requests permission to write docs/ONBOARDING.md.
Verify the output
Open docs/ONBOARDING.md in the editor to confirm the document contains all
the content you expect to see. You can also ask Bob to preview it:
Show me a preview of docs/ONBOARDING.mdBob renders the Markdown in the chat interface. Review the content for accuracy and completeness before committing.
Commit the file
Use your preferred Git workflow to commit docs/ONBOARDING.md to your
repository. The document is now available to every contributor and to Bob
itself in future sessions.
Troubleshooting
Bob's analysis is shallow or misses services
By default, Bob reads the project structure and a selection of key files. If the output is missing a service or is less detailed than expected, add explicit context mentions to narrow Bob's focus.
For example, if the Java hold service is not reflected in the tech stack
analysis, add @booking_system_inventory_hold_service/pom.xml to the prompt:
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.Bob cannot find test files
If Bob reports that it cannot find test files, use a context mention to point directly at the test directories:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.Bob's deployment analysis omits a target
The AWS, IBM Cloud, and local deployment artifacts are spread across multiple top-level directories. If Bob's deployment summary is incomplete, prompt it with the specific directories:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init generates an empty or incorrect AGENTS.md
In the workspace root, the /init command builds project context by reading
anchor files such as README.md, package.json, requirements.txt, pom.xml,
Makefile, and similar manifests. If none of those files exists at the root,
or if the workspace root is set to a subdirectory, Bob sees only a fragment of
the project and generates a sparse or incorrect AGENTS.md.
If the generated AGENTS.md does not reflect the multi-service structure,
check the following:
- Workspace root: Confirm that
galaxium-travels/, not a subdirectory such asbooking_system_backend/, is open as the workspace root. All three service directories must be visible at the top level. - Missing anchor files: If the root lacks a
README.mdor other manifest,/inithas little to read. Add a root-levelREADME.mdwith a brief project description, then rerun/init.
After correcting the root, rerun /init to regenerate the AGENTS.md
files.
Modernize a Node.js application
Learn to use IBM Bob for application modernization by upgrading a Node.js Express API from version 16 to 22. Try AI-assisted development with modes, approvals, and literate coding in this hands-on tutorial.
Generate architecture diagrams
Use IBM Bob to analyze the Galaxium Travels codebase and generate Mermaid UML class diagrams, sequence diagrams, and use case diagrams. Learn how to use context mentions in Ask mode to explore code and Agent mode to save the results to your repository.