# AI-DLC Brownfield Documentation Artifacts: 9 Reverse-Engineering Files Explained

> Explore 9 AI-DLC brownfield documentation artifacts generated for reverse-engineering existing codebases. Understand architecture, APIs, structure, and quality metrics with this awslabs tool.

- Repository: [Amazon Web Services - Labs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows)
- Tags: tutorial
- Published: 2026-05-09

---

**AI-DLC generates nine conditional documentation artifacts under `aidlc-docs/inception/reverse-engineering/` when it detects an existing codebase, covering architecture, API documentation, code structure, and quality metrics.**

When you run the `awslabs/aidlc-workflows` engine against a repository containing existing application code, it triggers a **Reverse Engineering** stage that produces machine-readable documentation artifacts. These **brownfield artifacts** capture the current state of your codebase and serve as the foundation for all subsequent AI-driven development phases, including Requirements Analysis and Application Design.

## How AI-DLC Detects Brownfield Projects

AI-DLC performs **Workspace Detection** at startup to determine if your repository contains existing code. When existing source files are detected, the workflow automatically triggers the **Reverse Engineering** stage defined in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) (lines 12-14). This conditional block executes only when the `brownfield` flag evaluates to true, ensuring documentation generation occurs exclusively for existing codebases.

## The 9 Conditional Reverse-Engineering Artifacts

All brownfield-specific artifacts reside in `aidlc-docs/inception/reverse-engineering/`. These files are created only when analyzing existing projects, as specified in [`docs/GENERATED_DOCS_REFERENCE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/docs/GENERATED_DOCS_REFERENCE.md).

**business-overview.md** – Captures high-level business domain descriptions, key transactions, and domain terminology used throughout the application.

**architecture.md** – Contains system-level architecture diagrams, component boundaries, and data-flow narratives describing how services interact.

**code-structure.md** – Inventories the build system, main packages or modules, design patterns employed, and overall file layout of the repository.

**api-documentation.md** – Catalogs public and internal APIs including request/response schemas, data models, and endpoint specifications.

**component-inventory.md** – Lists all software components (application, infrastructure, shared libraries, and test suites) with their brief responsibilities.

**technology-stack.md** – Documents languages, frameworks, CI/CD tools, cloud services, and testing utilities currently in use.

**dependencies.md** – Maps internal and external library dependencies, version ranges, and relationship graphs between components.

**code-quality-assessment.md** – Records metrics including test coverage percentages, static analysis warnings, technical debt indicators, and coding style adherence.

**reverse-engineering-timestamp.md** – Stores metadata including who ran the analysis, when it occurred, and how it was performed for auditability purposes.

## Global Artifacts Created for All Projects

In addition to the conditional reverse-engineering files, AI-DLC always creates these artifacts regardless of project type:

- [`aidlc-docs/aidlc-state.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/aidlc-state.md) – Tracks workflow progress and stage completion status
- [`aidlc-docs/audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/audit.md) – Immutable, timestamped log of every user input and AI response

## Example Artifact Content

Below is a representative excerpt showing the format and depth of generated documentation:

```markdown

# Architecture Overview

## System Context

- The system processes incoming **Order** events from an external SaaS platform.
- Core services:
  - `order-service` (Java Spring Boot) – business logic
  - `payment-service` (Node.js) – payment gateway integration
  - `notification-service` (Python) – email/SMS alerts

## Component Diagram

```mermaid
graph LR
    Client --> OrderService
    OrderService --> PaymentService
    OrderService --> NotificationService
    PaymentService --> BankAPI

```

# API Documentation

## `POST /orders`

```json
{
  "orderId": "string",
  "customerId": "string",
  "items": [{ "sku": "string", "qty": 1 }]
}

```

*Response*: `201 Created` with location header.

# Technology Stack

- **Language**: Java 17, Node 20, Python 3.11
- **Frameworks**: Spring Boot, Express, FastAPI
- **CI**: GitHub Actions, Maven, npm, Poetry

```

## Summary

- AI-DLC generates **nine conditional artifacts** under `aidlc-docs/inception/reverse-engineering/` specifically for brownfield codebases
- These files cover business context, architecture, APIs, components, technology stack, dependencies, code quality, and audit metadata
- The **Reverse Engineering** stage triggers automatically when **Workspace Detection** finds existing code, implemented in [`core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/core-workflow.md)
- **Global artifacts** ([`aidlc-state.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-state.md) and [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md)) are created for both greenfield and brownfield projects
- All artifacts serve as the machine-readable foundation for subsequent AI-DLC phases

## Frequently Asked Questions

### Where does AI-DLC store brownfield documentation artifacts?

AI-DLC stores brownfield-specific documentation in the `aidlc-docs/inception/reverse-engineering/` directory. This path is created automatically when the **Workspace Detection** step identifies an existing codebase and triggers the **Reverse Engineering** stage.

### What triggers the generation of reverse-engineering artifacts?

The **Workspace Detection** step triggers artifact generation when it discovers existing application code in your repository. This conditional logic is defined in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) at lines 12-14, which checks if the `brownfield` flag is true before executing the Reverse Engineering stage.

### Are these artifacts generated for greenfield projects?

No. The nine reverse-engineering artifacts are **conditional** and appear only for brownfield projects. However, global files including [`aidlc-state.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-state.md) and [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) are generated for both greenfield and brownfield repositories.

### How can I verify what artifacts were generated for my project?

Check the `aidlc-docs/inception/` directory. If you see a `reverse-engineering/` subdirectory containing files like [`architecture.md`](https://github.com/awslabs/aidlc-workflows/blob/main/architecture.md) and [`code-quality-assessment.md`](https://github.com/awslabs/aidlc-workflows/blob/main/code-quality-assessment.md), your project was processed as a brownfield codebase. The complete artifact specification is documented in [`docs/GENERATED_DOCS_REFERENCE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/docs/GENERATED_DOCS_REFERENCE.md).