The Art of Codebase Exploration: How a Simple Glob Search Revealed a WebUI's Architecture

The Subject Message

[assistant] [glob] **/*.tsx
No files found
[glob] **/web/**/*
/home/theuser/gw/integrations/web/ribsweb.go
/home/theuser/gw/integrations/web/ribswebapp/build/static/js/main.4ed3ff03.js.LICENSE.txt
/home/theuser/gw/integrations/web/ribswebapp/build/static/js/main.4ed3ff03.js
/home/theuser/gw/integrations/web/ribswebapp/build/static/js/main.4ed3ff03.js.map
/home/theuser/gw/integrations/web/ribswebapp/build/static/css/main.23f311b7.css.map
/home/theuser/gw/integrations/web/ribswebapp/build/static/css/main.23f311b7.css
/home/theuser/gw/integrations/web/ribsweb...

Introduction

At first glance, the message above appears to be nothing more than a pair of file search commands and their results—a mundane interaction between a developer and their tooling. But within this brief exchange lies a fascinating microcosm of the software engineering process: the moment of discovery, the challenge of navigating an unfamiliar codebase, and the quiet pivot when an initial assumption proves wrong. This message, drawn from a coding session for the Filecoin Gateway (FGW) project, captures the precise instant when an AI assistant began the critical work of understanding a system's architecture before implementing a new feature. It is a study in exploration strategy, assumption testing, and the humble art of looking before leaping.

The Context: A Feature Request Arrives

To understand why this message was written, we must first understand the context that produced it. The user had just directed the assistant to add a CIDGravity connection status indicator to the WebUI, with a specific constraint: "ideally one that checks token validity (no new endpoints use one we have already)." This was not a casual suggestion but a deliberate architectural directive. The user wanted to leverage existing infrastructure—the RPC layer already connecting the backend to the frontend—rather than proliferating new API endpoints. This constraint reveals a developer who values system simplicity and understands the cost of adding surface area to a service.

The assistant had already begun its investigation. In the immediately preceding message (index 2688), it had grepped the codebase for CIDGravity references, finding 64 matches across configuration files, test files, and presumably backend code. That search established what existed in the codebase related to CIDGravity. But the user's request was about the UI, not the backend. The assistant now needed to understand the frontend architecture: what UI framework was in use, where the components lived, and how data flowed from backend to browser.

The First Assumption: TypeScript Everywhere

The assistant's first glob search—**/*.tsx—is revealing. The .tsx extension is the standard file extension for React components written in TypeScript, a combination so ubiquitous in modern web development that it has become almost synonymous with "serious frontend application." By searching for .tsx files, the assistant was implicitly assuming that the FGW WebUI was built with React and TypeScript.

This assumption was not unreasonable. React has dominated frontend development for nearly a decade. TypeScript has become the default choice for new projects. Many Go-based projects with web interfaces adopt React for the frontend, serving it through a Go HTTP handler. The assistant's mental model was entirely plausible.

But the search returned "No files found." The codebase contained zero TypeScript React components.

The Pivot: Broadening the Search

The assistant did not dwell on this dead end. Without visible hesitation or commentary, it immediately issued a second, broader glob search: **/web/**/*. This pattern casts a much wider net, looking for any file within any directory named "web" at any depth in the project tree. Where the first search was a laser focused on a specific technology, the second was a floodlight illuminating an entire subsystem.

The results told a different story. The assistant found files under integrations/web/—specifically a Go file (ribsweb.go) and a pre-built React application under ribswebapp/build/. The presence of main.4ed3ff03.js and main.23f311b7.css indicates a production build of a React application (the hashed filenames are a hallmark of Webpack or similar bundlers). The .js.map files are source maps for debugging. The .LICENSE.txt file is a bundler artifact.

This discovery reveals the actual architecture: the WebUI is a React application (built from source that presumably lives elsewhere, perhaps in a src/ directory that wasn't matched by the glob), compiled into static JS/CSS bundles, and served by a Go HTTP handler (ribsweb.go). The frontend source code—the actual .tsx or .jsx files—may live in a different location not captured by the glob, or may have been excluded from the repository (a common practice where only the build output is committed).

Why This Message Matters: The Thinking Process Made Visible

This message is valuable precisely because it is so small and so ordinary. It captures the raw, unfiltered process of a developer (or AI assistant) navigating unknown territory. The sequence of actions reveals a clear thinking process:

1. Form a hypothesis: "The WebUI is probably built with React and TypeScript, so there should be .tsx files."
2. Test the hypothesis: Run a targeted glob search.
3. Evaluate the result: No files found. The hypothesis was wrong.
4. Form a broader hypothesis: "Let me find anything related to the web interface."
5. Test again: Run a broader glob search.
6. Interpret the results: Found a Go web handler and a built React app. The UI exists but the source is either elsewhere or not in .tsx format. This is the scientific method applied to codebase exploration. The assistant did not charge ahead blindly implementing against an incorrect mental model. It paused, searched, discovered, and adjusted. The absence of commentary—the assistant did not say "Hmm, no TSX files, let me try something else"—makes the thinking process more visible, not less. The actions speak for themselves.

Input Knowledge Required

To fully understand this message, a reader needs several pieces of contextual knowledge. First, familiarity with the glob pattern syntax is essential: **/*.tsx means "any .tsx file at any depth," while **/web/**/* means "any file inside any directory named web at any depth." Second, knowledge of web development conventions is required: .tsx signals TypeScript React, .js and .css files with hashed names signal a bundled production build, and .js.map files signal debugging support. Third, understanding the broader project context—that the assistant had just been asked to add a UI feature and was in the discovery phase—is necessary to grasp the purpose of these searches.

Output Knowledge Created

This message produced concrete, actionable knowledge. The assistant now knows that:

• The WebUI lives under integrations/web/
• The frontend is served through a Go file (ribsweb.go)
• The React build output is in ribswebapp/build/
• The UI uses standard JS/CSS bundles (not TypeScript source files in the current search path)
• The source code for the React components may need to be found through additional searching This knowledge directly informs the next steps. The assistant now knows to look at ribsweb.go to understand how the Go backend serves the React frontend, and to find the React source code to understand how to add a new status indicator component.

The Deeper Lesson: Assumptions in Software Engineering

The most instructive aspect of this message is what it reveals about assumptions. The assistant assumed .tsx files would exist. This was wrong, but it was a productive wrongness—it narrowed the search space and, when falsified, led to a more accurate understanding. The willingness to be wrong quickly and pivot without drama is a hallmark of effective engineering.

This pattern repeats constantly in software development. We assume a project uses PostgreSQL based on a config file, only to discover it uses SQLite. We assume a service is deployed on Kubernetes based on a Dockerfile, only to find it runs on bare metal. The ability to form hypotheses, test them cheaply (a glob search costs milliseconds), and update our mental model accordingly is what separates effective developers from those who build on sand.

Conclusion

A message that might appear trivial—two file searches and their results—is in fact a masterclass in codebase exploration methodology. It demonstrates hypothesis formation, rapid testing, graceful failure, and adaptive searching. It shows that understanding a system is not a single event but a process of successive approximation, each search narrowing the gap between assumption and reality. For the Filecoin Gateway project, this message marks the moment when the assistant transitioned from knowing about the CIDGravity feature to understanding where and how to implement it in the UI. The glob search was not the work itself, but it was the essential preparation that made the work possible.