# How the Ouroboros Brownfield Explorer Scans 15 Config File Types Across 12+ Ecosystems

> Discover how Ouroboros Brownfield Explorer scans 15 config file types across 12+ ecosystems to detect projects and aggregate tech stack data for AI interviews.

- Repository: [Q00/ouroboros](https://github.com/Q00/ouroboros)
- Tags: how-to-guide
- Published: 2026-03-14

---

**The Ouroboros Brownfield Explorer detects existing projects by scanning for 15+ configuration file types across 12+ language ecosystems using a curated catalog in `_CONFIG_FILES`, then aggregates tech stack data and key type definitions into a Markdown prompt for AI-assisted interviews.**

The **Brownfield Explorer** is a core component of the Q00/ouroboros repository designed to automatically discover context from existing codebases. Unlike greenfield project generators, this engine identifies "brownfield" projects—those with existing source files and build artifacts—by recognizing ecosystem-specific configuration patterns and extracting architectural context for downstream AI interviews.

## The Config File Catalogue (`_CONFIG_FILES`)

At the heart of the scanning process lies a comprehensive dictionary that maps well-known build and dependency files to their corresponding technology stacks.

### Mapping 15+ File Types to Tech Stacks

In [`src/ouroboros/bigbang/explore.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/explore.py), the `_CONFIG_FILES` dictionary (lines 28-45) serves as the single source of truth for ecosystem detection. This curated list covers **15+ file types** spanning Go (`go.mod`), Rust ([`Cargo.toml`](https://github.com/Q00/ouroboros/blob/main/Cargo.toml)), JavaScript/TypeScript ([`package.json`](https://github.com/Q00/ouroboros/blob/main/package.json)), Python ([`requirements.txt`](https://github.com/Q00/ouroboros/blob/main/requirements.txt), [`pyproject.toml`](https://github.com/Q00/ouroboros/blob/main/pyproject.toml)), Java/Kotlin ([`pom.xml`](https://github.com/Q00/ouroboros/blob/main/pom.xml), `build.gradle`), Ruby (`Gemfile`), Elixir ([`mix.exs`](https://github.com/Q00/ouroboros/blob/main/mix.exs)), PHP ([`composer.json`](https://github.com/Q00/ouroboros/blob/main/composer.json)), and C/C++ ([`CMakeLists.txt`](https://github.com/Q00/ouroboros/blob/main/CMakeLists.txt), `Makefile`) ecosystems.

Each entry pairs a filename with a human-readable technology label, enabling the explorer to immediately identify the primary language when it encounters a recognized manifest in the project root.

## Brownfield Detection and Tech Stack Inference

Once the catalog is loaded, the explorer executes a two-phase detection process to confirm brownfield status and extract detailed context.

### Detecting Existing Projects with `detect_brownfield`

The `detect_brownfield` function (lines 80-94 in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py)) iterates over the keys of `_CONFIG_FILES` and checks for file existence within the supplied directory using `Path.exists()`. The presence of **at least one** recognized configuration file signals a brownfield project, triggering the full exploration pipeline rather than treating the directory as a blank slate.

### Inferring Technology Stacks

After confirming brownfield status, `scan_directory` performs a secondary pass through `_CONFIG_FILES` to build a comprehensive tech stack profile. For each matching file found, the function records the associated language label (e.g., `go.mod` maps to "Go", [`package.json`](https://github.com/Q00/ouroboros/blob/main/package.json) maps to "JavaScript/TypeScript"). This yields a concise "Tech Stack" string that appears in the final interview prompt, informing the AI about the project's architectural foundation.

## Deep Code Analysis with Type Patterns

Beyond manifest detection, the explorer performs content analysis to identify key architectural components within the source code.

### Source File Discovery (`_TYPE_PATTERNS`)

Following tech stack identification, the explorer loads **glob patterns** specific to each language (lines 47-62 in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py)). The `_TYPE_PATTERNS` dictionary maps ecosystem labels to file extensions—such as `*.go` for Go, `*.py` for Python, and `*.rs` for Rust—enabling the system to locate relevant source files without parsing directory trees blindly.

### Extracting Key Type Definitions (`_TYPE_DEF_PATTERNS`)

For architectural context, the explorer utilizes `_TYPE_DEF_PATTERNS` (lines 64-107 in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py)), which contains regular-expression patterns tailored to each language's syntax. These patterns capture **struct**, **class**, **interface**, **enum**, and **constant** definitions. The system runs a fast content search via `Read`, `Glob`, and `Grep` operations on discovered files, collecting "key types" that represent the project's core data models and abstractions.

## Aggregating Results for AI Context

All collected data converges in `format_explore_results` (lines 998-1021 in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py)). This function aggregates the tech stack, discovered dependencies, and extracted key types into a structured Markdown block. The resulting snippet is injected into the system prompt during the interview phase ([`src/ouroboros/bigbang/interview.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/interview.py), lines 214-225), enabling the AI to ask informed questions about existing architecture rather than proposing redundant scaffolding.

## Implementation Example

The following example demonstrates how to invoke the Brownfield Explorer on an existing project:

```python
from pathlib import Path
from ouroboros.bigbang.explore import detect_brownfield, scan_directory, format_explore_results

project_root = Path("/my/existing/app")

# 1️⃣ Detect brownfield status

if detect_brownfield(project_root):
    # 2️⃣ Run full exploration

    results = scan_directory(project_root)          # returns List[CodebaseExploreResult]

    prompt_section = format_explore_results(results)
    print(prompt_section)                          # inject into interview prompt

else:
    print("No known config files – treating as greenfield.")

```

Running the above on a directory containing [`package.json`](https://github.com/Q00/ouroboros/blob/main/package.json) and a `src/*.ts` folder produces a prompt snippet such as:

```

### [PRIMARY] /my/existing/app

Tech: JavaScript/TypeScript
Deps: react, lodash, axios
Key Types:
- class App
- interface Config

```

## Summary

- The **Brownfield Explorer** uses a curated `_CONFIG_FILES` dictionary in [`src/ouroboros/bigbang/explore.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/explore.py) to recognize **15+ configuration file types** across **12+ ecosystems** including Go, Rust, Python, and Java.
- **`detect_brownfield`** (lines 80-94) confirms existing projects by checking for the presence of known manifest files.
- **`scan_directory`** infers technology stacks by mapping discovered config files to language labels, while **`_TYPE_PATTERNS`** and **`_TYPE_DEF_PATTERNS`** (lines 47-107) enable deep source code analysis.
- **`format_explore_results`** (lines 998-1021) aggregates findings into Markdown blocks injected into AI interview prompts via the orchestrator adapter.

## Frequently Asked Questions

### How does the Brownfield Explorer handle polyglot repositories containing multiple config files?

The explorer treats the presence of any recognized config file as a brownfield signal, and `scan_directory` aggregates **all** detected technologies into a combined tech stack string. A project containing both `go.mod` and [`package.json`](https://github.com/Q00/ouroboros/blob/main/package.json) would report "Go, JavaScript/TypeScript" in the final prompt, allowing the AI to understand cross-language dependencies.

### What specific file types does the `_CONFIG_FILES` dictionary recognize?

According to the source code in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py) (lines 28-45), the dictionary recognizes ecosystem manifests including `go.mod`, [`Cargo.toml`](https://github.com/Q00/ouroboros/blob/main/Cargo.toml), [`package.json`](https://github.com/Q00/ouroboros/blob/main/package.json), [`requirements.txt`](https://github.com/Q00/ouroboros/blob/main/requirements.txt), [`pyproject.toml`](https://github.com/Q00/ouroboros/blob/main/pyproject.toml), [`pom.xml`](https://github.com/Q00/ouroboros/blob/main/pom.xml), `build.gradle`, `Gemfile`, [`mix.exs`](https://github.com/Q00/ouroboros/blob/main/mix.exs), [`composer.json`](https://github.com/Q00/ouroboros/blob/main/composer.json), [`CMakeLists.txt`](https://github.com/Q00/ouroboros/blob/main/CMakeLists.txt), and `Makefile`, covering the majority of modern language ecosystems.

### How does the explorer extract type definitions without full parsing?

Rather than implementing language-specific parsers, the explorer uses **`_TYPE_DEF_PATTERNS`**—a collection of regular expressions (lines 64-107 in [`explore.py`](https://github.com/Q00/ouroboros/blob/main/explore.py))—to perform fast text searches for struct, class, interface, and enum declarations. This lightweight approach avoids heavy AST parsing while still capturing key architectural signatures.

### Where does the brownfield context appear in the AI interview process?

The formatted results from `format_explore_results` are injected into system prompts by the orchestrator adapter ([`src/ouroboros/orchestrator/adapter.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/orchestrator/adapter.py), lines 98-112). This occurs when `state.is_brownfield` evaluates to true in [`interview.py`](https://github.com/Q00/ouroboros/blob/main/interview.py) (lines 214-225), ensuring the AI receives codebase context before generating interview questions.