The Research-Before-Architecture Principle: How One Message Launched a QA Cluster
In the sprawling transcript of an opencode coding session focused on the Filecoin Gateway (FGW) distributed storage system, one message stands out as a methodological turning point. It is message index 1905, a response from the assistant to the user's request: "Describe best practices for an easy QA/test environment. Aim for fairly small, e.g. 2x 1.25TiB nodes + 1x 200GiB S3+YB, ubuntu 24. Mainnet with cidg (supplied wallet/token). Include network reqs. Delegate agents to research anything you aren't 100% sure about."
This message is not a deployment command. It is not a configuration file. It is not a debugging session. It is something rarer and more instructive: a deliberate pause for research before committing to an architecture. The assistant does not guess, does not assume, and does not rush to produce a plan from memory. Instead, it delegates three parallel research tasks, waits for the results, and then compiles comprehensive summaries of the FGW deployment requirements, YugabyteDB minimum specifications, and Filecoin mainnet network needs. This article examines that single message in depth: why it was written, how it structured its research, what assumptions it carried, what knowledge it required and produced, and what it reveals about the thinking process of a methodical technical assistant.
The Full Text of the Subject Message
[assistant] I'll research the requirements for a minimal QA/test environment for FGW on Filecoin mainnet. Let me delegate some research tasks to gather accurate information.
>
[task] {"description":"Research FGW deployment requirements","prompt":"Research the FGW (Filecoin Gateway) codebase to understand deployment requirements:\n\n1. Look at ansible roles and playbooks to understand what services need to be deployed\n2. Check configuration files for required dependencies (Yugab...
>
Now I have all the information needed. Let me compile a comprehensive summary of the FGW deployment requirements.
>
---
>
## FGW (Filecoin Gateway) Deployment Requirements - Comprehensive Summary
>
Based on the analysis of the ansible roles, playbooks, configuration files, and documentation, here is a comprehensive deployment guide:
>
---
>
### 1. REQUIRED SERVICES AND THEIR RELATIONSHIPS
>
#### Core Services (deployed by Ansible)
>
| Service | Node Type | Purpose | Dependencies | |---------|----------...
>
[task] {"description":"Research YugabyteDB minimal deployment","prompt":"Research YugabyteDB minimum requirements for a small test/QA deployment:\n\n1. What are the minimum hardware requirements for a single-node YugabyteDB?\n2. What ports does YugabyteDB need?\n3. Can it run on a node with only 200GiB sto...
>
Based on my research of the official YugabyteDB documentation, here is a comprehensive summary of the minimum requirements for a small test/QA deployment:
>
---
>
## YugabyteDB Minimum Requirements for Small Test/QA Deployment
>
### 1. Minimum Hardware Requirements for Single-Node YugabyteDB
>
For Development/Testing (Quick Start): - CPU: 2 cores minimum (4 cores recommended) - RAM: 2 GB minimum (4 GB recommended for better performance) - Disk: SSD recommended; minimum varies by data...
>
[task] {"description":"Research Filecoin mainnet requirements","prompt":"Research Filecoin mainnet requirements for a storage client/gateway application:\n\n1. What network connectivity is needed for Filecoin mainnet?\n2. What ports are typically used for Filecoin network communication?\n3. Are there any b...
>
Based on my comprehensive research of the FGW codebase, here is a detailed summary of the Filecoin mainnet network requirements:
>
## Filecoin Mainnet Network Requirements for FGW
>
### 1. Network Connectivity Needed for Filecoin Mainnet
>
FGW uses external Lotus Gateway RPC - NOT a full Lotus node:
>
- External RPC Endpoint: FGW connects to Filecoin via the Lotus Gateway RPC API (JSON-RPC over HTTP/HTTPS) - Default Endpoint: https://api.chain.love/rpc/v1 (public Filecoin gateway) - ...
Why This Message Was Written: The Motivation and Context
To understand why message 1905 exists, we must look at what preceded it. The session had just completed an extensive period of implementation and testing. The assistant had built and committed three major milestones: a multi-tier retrieval cache system (Milestone 03), a passive garbage collection system (Milestone 04), and enterprise-grade observability with Grafana dashboards, operational runbooks, and an AI support system (Milestone 02). The code was tested, benchmarks were run, and everything was committed. The project was, in a sense, "done" in development.
But software that runs only in unit tests and Docker Compose environments is not yet a real system. The user's question at message 1904 shifted the focus from development to deployment: "Describe best practices for an easy QA/test environment." This was a call to bridge the gap between tested code and operational reality. The user specified concrete parameters: two nodes with 1.25 TiB of storage each, one node with 200 GiB for S3 and YugabyteDB, Ubuntu 24.04, mainnet connectivity with a supplied wallet and CIDgravity token. They explicitly asked for network requirements. And crucially, they instructed the assistant to "Delegate agents to research anything you aren't 100% sure about."
This last instruction is the key to understanding the message. The user was not asking for a quick opinion or a best-guess architecture. They were asking for a researched recommendation. The assistant, recognizing that it needed accurate information about three distinct domains—the FGW codebase's own deployment structure, YugabyteDB's hardware requirements, and Filecoin mainnet's network topology—responded by doing exactly what was asked: it delegated research tasks.
The message is thus a research manifesto. It declares the assistant's intent to gather information before acting, a principle that stands in contrast to the trial-and-error debugging that characterized earlier segments of the conversation. This is not a message that deploys anything. It is a message that prepares to deploy, and that preparation is treated as a first-class activity worthy of its own dedicated research tasks.## How Decisions Were Made (and Not Made)
A striking feature of this message is that it makes almost no decisions. It does not choose a deployment topology. It does not select specific software versions. It does not commit to a port allocation scheme. Instead, it produces research summaries that will inform future decisions. The assistant's approach is to gather facts first: what services the FGW codebase actually deploys, what YugabyteDB needs to run, and what network connectivity Filecoin mainnet requires.
The only decision visible in the message is the decision to research. The assistant could have attempted to answer the user's question from memory or general knowledge. Filecoin is a well-known protocol; YugabyteDB is a documented database; the assistant had already worked extensively with the FGW ansible roles in previous segments. But the user's explicit instruction to delegate research for anything uncertain created a forcing function. The assistant responded by launching three parallel research tasks, each with a detailed prompt specifying what to look for.
This is a significant architectural choice in the assistant's own methodology. Rather than producing a single stream of reasoning, the assistant parallelizes the knowledge-gathering process. Each research task is independent: one examines the FGW codebase's ansible roles and playbooks, another examines YugabyteDB's official documentation, and a third examines Filecoin mainnet's network requirements. The results are then compiled into three separate summaries within the same message.
The message also makes a subtle but important structural decision about how to present information. The three research summaries are presented sequentially, each preceded by a task declaration and followed by a detailed report. This creates a clear audit trail: the reader (and the user) can see exactly what was researched, what sources were consulted, and what conclusions were drawn. The assistant does not merge the three summaries into a single narrative, which would have obscured the provenance of each fact. Instead, it keeps them separate, allowing the user to evaluate each research thread independently.
Assumptions Embedded in the Message
Every research effort rests on assumptions, and this message is no exception. The most fundamental assumption is that the FGW codebase's ansible roles and playbooks are the correct source of truth for deployment requirements. The assistant assumes that the code as written reflects the intended architecture—that the roles for kuri, s3-frontend, yugabyte, and prepare accurately describe what services need to run and how they relate to each other. This is a reasonable assumption, but it is not neutral. The ansible roles may contain bugs, may be incomplete, or may reflect an idealized architecture that has not been tested on physical hardware. The assistant does not flag this uncertainty.
A second assumption concerns the user's infrastructure. The user specified "2x 1.25TiB nodes + 1x 200GiB S3+YB, ubuntu 24." The assistant assumes these are physical or virtual machines with dedicated storage, that they are network-connected with private IPs, and that the user has SSH access and root privileges. It assumes Ubuntu 24.04 LTS, which is a specific version that may have its own quirks with YugabyteDB or the Go runtime that FGW requires. The assistant does not question whether the user has actually provisioned these machines or whether they are available.
A third assumption is that the CIDgravity token and wallet files will be supplied by the user and that these credentials are valid for mainnet. The assistant's research tasks focus on technical requirements—CPU, RAM, storage, ports—but do not investigate whether the supplied credentials have any special configuration requirements. For example, does the CIDgravity token need to be registered with specific node identifiers? Does the wallet need to be funded with FIL for deal collateral? The research summaries do not address these questions.
Perhaps the most significant assumption is that the QA environment should mirror the production architecture as closely as possible. The assistant's research is oriented toward understanding the "real" deployment requirements of FGW, not toward finding the simplest possible test setup. This is a defensible choice—the user asked for "best practices for an easy QA/test environment," which implies a trade-off between simplicity and fidelity. But the assistant does not explicitly discuss this trade-off. It does not ask, for example, whether a single-node deployment would be sufficient for basic testing, or whether the S3 frontend could be omitted in early QA phases.
Input Knowledge Required to Understand This Message
To fully grasp what this message is doing, a reader needs significant contextual knowledge. They need to understand that FGW (Filecoin Gateway) is a horizontally scalable S3-compatible storage system that uses YugabyteDB as its metadata store and connects to the Filecoin blockchain for deal-making. They need to know that the project uses Ansible for deployment, with roles organized by service type (kuri, s3-frontend, yugabyte, prepare). They need to understand the concept of "LocalWeb" as a built-in HTTP server for serving CAR files to storage providers. They need to know what CIDgravity is—a service that helps storage providers choose the best deal partners—and that it requires an API token.
The reader also needs to understand the research delegation mechanism itself. The message uses a [task] directive that appears to be a structured prompt for an automated research agent. The assistant invokes these tasks, waits for results, and then incorporates them into the message. A reader unfamiliar with this pattern might be confused by the apparent non-sequitur: the assistant says "Let me delegate some research tasks," and then the message contains what appear to be completed research summaries. The intermediate step—the actual execution of the research—is not shown.
Network knowledge is also required. The message discusses ports (5433 for YSQL, 9042 for YCQL, 8078 for S3 API, 8443 for LocalWeb, 9010 for Web UI, 2112 for Prometheus metrics) and assumes the reader understands the role of each. It distinguishes between internal traffic (between kuri nodes and YugabyteDB) and external traffic (from storage providers and clients). It mentions Lotus Gateway RPC and assumes the reader knows that this is a public JSON-RPC endpoint for Filecoin blockchain interaction.
Output Knowledge Created by This Message
The message creates substantial output knowledge across three domains. First, it produces a structured understanding of FGW's service architecture: which services exist, what they depend on, and how they are deployed via Ansible. This is knowledge extracted from the codebase itself, organized into a readable summary. Second, it produces a concrete specification for YugabyteDB in a test context: minimum 2 CPU cores, 2 GB RAM, SSD storage, with specific port requirements and the recommendation to use yugabyted for single-node simplicity. Third, it produces a clarification about Filecoin mainnet connectivity: FGW does not need a full Lotus node; it uses an external RPC endpoint (api.chain.love), which dramatically simplifies the network requirements.
The message also creates implicit knowledge about what not to worry about. By stating that FGW uses an external Lotus Gateway RPC rather than a full node, the assistant eliminates an entire category of complexity. The reader learns that they do not need to run a Filecoin daemon, do not need to sync the blockchain, and do not need to manage Filecoin P2P networking. This is perhaps the most valuable output of the Filecoin research task: it identifies a simplifying assumption that might otherwise have been missed.
The research summaries also serve as a form of documentation. They capture the state of the FGW codebase at a particular moment, including the ansible roles and their relationships. This is knowledge that could become stale as the codebase evolves, but at the time of writing, it represents an accurate map of the deployment architecture.
The Thinking Process: A Methodical Approach to Uncertainty
The thinking process visible in this message is one of deliberate, structured inquiry. The assistant begins by acknowledging the need for research: "I'll research the requirements for a minimal QA/test environment for FGW on Filecoin mainnet." It then decomposes the problem into three independent research streams, each with a clear scope and set of questions.
The FGW deployment research task asks specific questions about ansible roles, configuration files, and dependencies. The YugabyteDB research task asks about minimum hardware, ports, and the feasibility of running on a 200 GiB node. The Filecoin mainnet research task asks about network connectivity, ports, and whether a full Lotus node is required. Each task is scoped to a single domain, and each produces a self-contained summary.
This decomposition is itself a thinking strategy. Rather than attempting to answer the user's question in a single pass—which would require holding all three domains in working memory simultaneously—the assistant offloads each domain to a separate research process. This is analogous to how a human engineer might open three browser tabs and research each topic independently before synthesizing the results.
The synthesis happens at the level of the message structure. The three summaries are presented in sequence, but they are not integrated into a single deployment plan. That integration happens in the next message (index 1907), where the assistant presents a complete architecture diagram with node specifications, port allocations, and configuration recommendations. Message 1905 is thus the research phase; message 1907 is the design phase. The separation is intentional and visible.
One notable aspect of the thinking process is what is not done. The assistant does not question its own research methodology. It does not ask whether the ansible roles are the right source of truth, or whether the YugabyteDB documentation might be outdated, or whether the Filecoin network requirements might have changed. It accepts the sources at face value and presents the results without qualification. This is appropriate for a research task of this scope—the assistant is not writing a peer-reviewed paper, it is gathering information to inform a practical deployment—but it is worth noting as a limitation of the approach.
Mistakes and Incorrect Assumptions
Were there any mistakes in this message? The research summaries themselves appear accurate based on the codebase and documentation. However, there is a subtle error in the framing. The user asked for "S3+YB" on the 200 GiB node, implying that both an S3-compatible storage backend (like MinIO) and YugabyteDB should run on the same machine. The assistant's research includes MinIO requirements in a subsequent message (index 1906), but in message 1905, it focuses exclusively on YugabyteDB. This could be seen as a misalignment with the user's request—the user wanted both services researched, but the assistant only researched one in this message.
More significantly, the assistant assumes that the QA environment should use the same architecture as production: separate kuri storage nodes with S3 frontends, a shared YugabyteDB, and external monitoring. The user's question was specifically about an "easy" QA environment, which might have justified simplifications like running everything on a single node or using SQLite instead of YugabyteDB. The assistant does not explore these alternatives. It defaults to the full production architecture scaled down, rather than asking whether a simpler architecture might suffice for QA purposes.
The message also contains an implicit assumption about the user's technical sophistication. The research summaries are detailed but assume the reader understands concepts like "YSQL vs YCQL," "Prometheus metrics scraping," and "LocalWeb CAR serving." A less technical user might have needed more explanation of these concepts. The assistant does not provide glossaries or introductory context.
Conclusion: The Value of Structured Research
Message 1905 is a testament to the value of structured research before architectural commitment. In a coding session dominated by debugging, testing, and iterative refinement, this message stands out as a deliberate pause—a moment when the assistant stepped back from the code and asked, "What do I actually need to know before I proceed?"
The answer was three research tasks, three summaries, and a foundation of verified knowledge that would inform every subsequent decision about the QA cluster. The message did not deploy anything, but it made the deployment that followed possible. It is a reminder that in complex systems engineering, the most important output is sometimes not code or configuration, but understanding.