AWS Builder Center

Document a 109K-Line Framework in One Command

One AWS Transform command turns a 109K-line Python framework into 32 docs covering architecture, security, tech debt, and migration planning.

FastAPI: 109,000 lines of Python. 85,000 GitHub stars. A dependency injection system, OpenAPI generation, Pydantic integration, security schemes, WebSocket support, and a 170-file test suite. One ATX command. 32 documentation files generated. 2,122 lines covering architecture, patterns, security, technical debt, and migration planning. Total cost: $4.84.



The Scale Problem

Post  ATX Comprehensive Codebase Analysis  in this series demonstrated  AWS/comprehensive-codebase-analysis  on a 225-line FastAPI service. The generated documentation was impressive: 32 files, 1,700 lines, architecture diagrams, security analysis, tech debt assessment. But a skeptic could argue that a 225-line service is trivial. Any tool can document simple code.
The real question is: what happens when you point the same transformation at a codebase with genuine complexity? A framework with 109,000 lines, hundreds of modules, multiple architectural layers, and design decisions accumulated over five years of development by dozens of contributors?
FastAPI is that test. It's the most popular Python web framework by growth rate. It has a sophisticated dependency injection system, automatic OpenAPI 3.1.0 schema generation, security scheme implementations (OAuth2, HTTP Bearer, API keys, OpenID Connect), WebSocket support, middleware composition, and a unique pattern where type annotations simultaneously drive runtime validation and API documentation generation.
If ATX can produce accurate, useful documentation for FastAPI, it can handle your production codebase.

The Input: A Shallow Clone

git clone --depth 1 https://github.com/fastapi/fastapi.git
cd fastapi
No setup. No configuration. No "tell ATX about your project." Just a git repo with Python source files.

Running the Transformation

aws configure # configure AWS credentials (or use env vars / a profile)

atx custom def exec \
--transformation-name "AWS/comprehensive-codebase-analysis" \
--code-repository-path ./fastapi \
--build-command "python -m pytest tests/ -x -q --timeout=10 2>/dev/null || true" \
--non-interactive --trust-all-tools
ATX spent 138 agent minutes analyzing FastAPI. For context, a human developer writing equivalent documentation for a framework of this size would spend 40-80 hours: reading every module, tracing dependency chains, mapping the architecture, identifying patterns, documenting APIs, assessing security posture, and cataloging technical debt.
ATX Comprehensive Codebase Analysis


What ATX Produced: 32 Files, 2,122 Lines

32 files changed, 2122 insertions(+)

ATXDocumentation/
├── README.md ← Index and navigation
├── project-overview.md ← Identity, stack, capabilities
├── technical-debt-report.md ← Top-level debt assessment
├── architecture/
│ ├── system-overview.md ← Layered architecture, deployment model
│ ├── components.md ← Module breakdown, responsibilities
│ ├── dependencies.md ← External and internal dependency graph
│ └── patterns.md ← Design patterns, anti-patterns
├── behavior/
│ ├── business-logic.md ← Core framework logic
│ ├── workflows.md ← Request processing pipelines
│ ├── decision-logic.md ← Conditional logic paths
│ └── error-handling.md ← Exception types, handler chain
├── reference/
│ ├── program-structure.md ← File-by-file inventory
│ ├── interfaces.md ← Public API surface
│ ├── data-models.md ← Pydantic model hierarchy
│ ├── api-reference.md ← Endpoint documentation
│ └── modules.md ← Module dependency map
├── analysis/
│ ├── code-metrics.md ← LOC, file counts, quality indicators
│ ├── complexity-analysis.md ← Cyclomatic complexity hotspots
│ ├── dependency-analysis.md ← Supply chain assessment
│ ├── security-patterns.md ← Security posture evaluation
│ └── tech-debt.md ← Debt categorization
├── diagrams/
│ ├── architecture/system-context.md ← Deployment and integration diagrams
│ ├── behavioral/sequence-diagrams.md ← Request flow sequences
│ └── structural/component-diagrams.md ← Component relationship maps
├── technical-debt/
│ ├── summary.md ← Prioritized debt overview
│ ├── outdated-components.md ← Version constraint issues
│ ├── maintenance-burden.md ← Complexity hotspots
│ └── remediation-plan.md ← Prioritized fix plan
├── migration/
│ ├── component-order.md ← Dependency-based refactoring order
│ ├── test-specifications.md ← Test strategy for changes
│ └── validation-criteria.md ← Success criteria
└── specialized/
└── api-documentation.md ← Framework-specific API docs
This is not a template filled with placeholders. Every file contains content derived from reading FastAPI's actual source code.

Deep Dive: The Project Overview

ATX correctly identified FastAPI's identity, technology stack, and project structure:
# Project Overview - FastAPI

## Project Identity
- Name: FastAPI
- Version: 0.137.1
- Description: High-performance Python web framework for building APIs
with type hints
- Repository: https://github.com/fastapi/fastapi
- Documentation: https://fastapi.tiangolo.com/
- License: MIT
- Author: Sebastián Ramírez (tiangolo@gmail.com)

## Technology Stack
| Layer | Technology | Version |
|-------|-----------|---------|
| Language | Python | >=3.10 (supports 3.10-3.14) |
| ASGI Framework | Starlette | >=0.46.0 |
| Data Validation | Pydantic | >=2.9.0 |
| Build System | PDM (pdm-backend) | - |
| Type System | typing-extensions | >=4.8.0 |
| CLI | fastapi-cli | >=0.8 (optional) |
| Server | Uvicorn | >=0.12.0 (optional) |
This was extracted from  pyproject.toml  and the actual source. The version numbers match reality. The technology identification is accurate: FastAPI does use PDM as its build backend, it does require Python 3.10+, and Starlette/Pydantic are its two foundational dependencies.
ATX also mapped the 109K-LOC codebase into a digestible project structure:
fastapi/ # Main source package (~109K LOC total)
├── fastapi/ # Core framework code
│ ├── applications.py # FastAPI main class
│ ├── routing.py # APIRouter, APIRoute
│ ├── params.py # Parameter types (Path, Query, etc.)
│ ├── param_functions.py # Public param factory functions
│ ├── dependencies/ # Dependency injection system
│ ├── security/ # Security schemes (OAuth2, HTTP, API Key)
│ ├── openapi/ # OpenAPI schema generation
│ ├── middleware/ # Middleware re-exports
│ ├── _compat/ # Compatibility utilities
│ └── ...
├── tests/ # Test suite (~170+ test files)
├── docs/ # Documentation (multi-language)
├── docs_src/ # Documentation source code examples
├── scripts/ # Build/development scripts
└── pyproject.toml
This is accurate. A developer landing on this project for the first time immediately knows where to look for routing code ( routing.py ), parameter handling ( params.py ), security ( security/ ), and the dependency injection system ( dependencies/ ).

Deep Dive: Architecture and Design Patterns

The architecture documentation is where ATX proves it can handle complexity. From  architecture/system-overview.md :
## Architecture Summary

FastAPI is a layered framework built on two foundational libraries:
1. Starlette - Provides the ASGI server interface, routing infrastructure,
request/response objects, middleware, and WebSocket support
2. Pydantic - Provides data validation, serialization, and JSON Schema
generation

FastAPI adds:
- Automatic OpenAPI schema generation
- Dependency injection system
- Parameter extraction and validation (path, query, header, cookie, body)
- Security scheme integration
- Auto-documentation UIs (Swagger, ReDoc)

## Key Architectural Decisions
1. Built on Starlette, not from scratch - Leverages a battle-tested ASGI
framework for HTTP/WebSocket handling
2. Pydantic for validation - Uses Pydantic's type system for both request
validation and OpenAPI schema generation
3. Annotation-driven API - Type hints and Annotated types define the entire
request interface
4. Decorator-based routing - HTTP method decorators for route registration
5. Composable routers - APIRouter enables modular application structure
6. Function-based dependency injection - Dependencies are regular Python
functions/classes resolved via Depends()
ATX identified six architectural decisions. These aren't generic observations. "Annotation-driven API" refers to FastAPI's unique pattern where Python type annotations simultaneously drive runtime behavior and documentation generation. "Function-based dependency injection" distinguishes FastAPI's DI from class-based DI systems like Spring's. These are insights a developer would only reach after spending hours reading the code.

The Technology Stack Diagram

ATX generated an ASCII-art layer diagram:
┌─────────────────────────────────────────────┐
│ FastAPI Application │
├─────────────────────────────────────────────┤
│ OpenAPI Generation │ Auto-Docs │ DI System │
├─────────────────────────────────────────────┤
│ FastAPI Core (routing, params) │
├─────────────────────────────────────────────┤
│ Starlette (ASGI) │
│ (Routing, Request/Response, Middleware) │
├─────────────────────────────────────────────┤
│ Pydantic (Validation) │
│ (Models, FieldInfo, JSON Schema) │
├─────────────────────────────────────────────┤
│ Python (>=3.10, typing) │
└─────────────────────────────────────────────┘
This correctly shows the layer ordering: Python at the bottom, Pydantic and Starlette as peers in the middle, FastAPI core on top of both, and the value-add features (OpenAPI, Auto-Docs, DI) at the application level.

Design Patterns Identified

From  architecture/patterns.md , ATX identified six primary patterns:
  1. Layered Architecture with four named layers (Application, Routing, Dependency, Foundation)
  1. Decorator Pattern for route registration
  1. Dependency Injection (Service Locator variant) with a detailed explanation of how  Depends()  builds a resolution tree
  1. Strategy Pattern for response classes and security schemes
  1. Composite Pattern for  APIRouter.include_router()  composition
  1. Template Method Pattern for  APIRoute.get_route_handler() 
And two anti-patterns:
God Object Tendency: FastAPI.init accepts ~35 parameters, handling many concernsRe-export Pattern: middleware/ module re-exports Starlette classes rather than extending them (pragmatic but increases coupling surface)
These are fair criticisms. The FastAPI constructor does accept dozens of parameters (title, description, version, servers, dependencies, middleware, exception_handlers, docs_url, redoc_url, etc.), and the middleware module is indeed a re-export layer. ATX identified real architectural characteristics, not generic boilerplate.

Deep Dive: Error Handling Documentation

The behavior section documents how FastAPI handles errors at runtime. From  behavior/error-handling.md :
## Exception Types
| Exception | Module | HTTP Status | Purpose |
|-----------|--------|-------------|---------|
| HTTPException | exceptions.py | Configurable | Standard HTTP error responses |
| WebSocketException | exceptions.py | - | WebSocket close with code |
| RequestValidationError | exceptions.py | 422 | Request parameter validation failure |
| ResponseValidationError | exceptions.py | 500 | Response model validation failure |

## Error Flow
Request Processing:
├── Parameter Extraction Fails → RequestValidationError → 422
├── Dependency Raises HTTPException → HTTP error response
├── Endpoint Raises HTTPException → HTTP error response
├── Response Serialization Fails → ResponseValidationError → 500
└── Unhandled Exception → Starlette's 500 handler

Dependency Cleanup:
├── Generator dependency yield succeeds → response sent
├── Generator dependency raises after yield → logged, response already sent
└── Generator dependency raises before yield → HTTPException propagates
The "Dependency Cleanup" section is particularly valuable. FastAPI's generator-based dependencies (using  yield ) have non-obvious error handling semantics: if a generator raises after yielding, the response has already been sent to the client. This is a subtlety that trips up developers and isn't well-documented in the official docs. ATX discovered it by reading the source code.
ATX also produced the validation error response format:
{
"detail": [
{
"type": "missing",
"loc": ["query", "name"],
"msg": "Field required",
"input": null
}
]
}
This is accurate. FastAPI returns a list of validation errors with location arrays, message strings, and type identifiers. A developer writing error handling logic benefits from seeing this format documented rather than discovering it through trial and error.

Deep Dive: Technical Debt Assessment

ATX assessed FastAPI's technical health. From  technical-debt/summary.md :
## Overview
FastAPI v0.137.1 demonstrates low technical debt overall. The project
maintains modern Python standards, uses current dependency versions,
and has comprehensive test coverage.

## Debt Categories
| Category | Severity | Count |
|----------|----------|-------|
| Outdated Runtime/Framework | None | 0 |
| Outdated Dependencies | Medium | 1 |
| Deprecated APIs retained | Low | 3 |
| Architectural concerns | Low | 3 |

## Prioritized Action Items
1. (Medium) Update httpx version constraint to allow 1.x
2. (Low) Plan deprecation timeline for on_event, routes, openapi_prefix
3. (Low) Consider refactoring FastAPI constructor to reduce parameter count
This is a measured, accurate assessment. FastAPI is actively maintained, so finding "low technical debt" is the correct conclusion. The  httpx  constraint issue is real (FastAPI pins httpx below 1.0 in its optional dependencies). The deprecated APIs ( on_event ,  routes ,  openapi_prefix ) are indeed marked with deprecation warnings in the source. ATX didn't invent problems where none exist, and it identified the real ones.

Deep Dive: The Deployment and Security Diagrams

ATX generated ASCII architecture diagrams showing how FastAPI fits into a deployment:
┌─────────────────────────────────────────────────────────────────┐
│ Deployment Context │
│ │
│ ┌──────────┐ HTTP ┌──────────┐ ASGI ┌──────────┐ │
│ │ Client │───────────▶│ Reverse │──────────▶│ Uvicorn │ │
│ │ (Browser/ │ │ Proxy │ │ (ASGI │ │
│ │ Mobile) │ │ (nginx) │ │ Server) │ │
│ └──────────┘ └──────────┘ └─────┬────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ FastAPI │ │
│ │Application │ │
│ └─────┬────┘ │
│ │ │
│ ┌──────────┼───┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌────┐ ┌────┐ │
│ │Database │ │Cache│ │APIs│ │
│ └─────────┘ └────┘ └────┘ │
└─────────────────────────────────────────────────────────────────┘
And a security boundary diagram:
┌─────────────────────────────────────────────────┐
│ Public Internet │
└──────────────────────┬──────────────────────────┘
│
┌───────▼────────┐
│ TLS Termination │ ← HTTPS only
│ (Reverse Proxy) │
└───────┬────────┘
│
┌───────▼────────┐
│ CORS Middleware │ ← Origin validation
└───────┬────────┘
│
┌───────▼────────┐
│ Auth Middleware │ ← Token/credential check
│ (Security deps)│
└───────┬────────┘
│
┌───────▼────────┐
│Input Validation │ ← Pydantic validation
│ (Param/Body) │
└───────┬────────┘
│
┌───────▼────────┐
│ Application │ ← Business logic
│(Route Handler) │
└────────────────┘
These diagrams are useful for security reviews, architecture discussions, and onboarding. They show where security boundaries exist in a FastAPI deployment and in what order requests pass through validation layers.

Deep Dive: Code Metrics

From  analysis/code-metrics.md :
## Overall Statistics
| Metric | Value |
|--------|-------|
| Total Lines of Code (Python) | ~109,727 |
| Source Package (fastapi/) | ~30 files |
| Test Files | ~170+ |
| Documentation Examples (docs_src/) | ~500+ files |
| Python Version | >=3.10 |

## Quality Indicators
| Indicator | Status |
|-----------|--------|
| Type Annotations | Complete (mypy strict mode) |
| py.typed marker | Present |
| Linting | ruff (E, W, F, I, B, C4, UP rules) |
| Test Coverage | Comprehensive (170+ test files) |
| CI/CD | GitHub Actions |
| Documentation | Extensive (multi-language) |
| Deprecation Warnings | Used for removed APIs |
ATX correctly identified that FastAPI runs mypy in strict mode, uses Ruff for linting with specific rule sets (E, W, F, I, B, C4, UP), includes a  py.typed  marker for PEP 561 compliance, and maintains multi-language documentation. These are details you only find by reading  pyproject.toml  and CI configuration files.

Accuracy Assessment: What ATX Got Right

Let me verify ATX's claims against FastAPI's actual repository:
Claim
Verification
Accurate?
Python >=3.10 required
 pyproject.toml :  requires-python = ">=3.10" 
Yes
Starlette >=0.46.0
 pyproject.toml  dependencies
Yes
Pydantic >=2.9.0
 pyproject.toml  dependencies
Yes
PDM backend
 [build-system]  uses  pdm-backend 
Yes
170+ test files
 tests/  directory has 170+  .py  files
Yes
mypy strict mode
 pyproject.toml   [tool.mypy]  strict = true
Yes
Ruff rules E,W,F,I,B,C4,UP
 pyproject.toml   [tool.ruff.lint]  select
Yes
MIT license
 pyproject.toml  license field
Yes
Decorator-based routing
Core pattern in  routing.py 
Yes
Depends() for DI
Core pattern in  dependencies/ 
Yes
httpx pinned below 1.0
Optional deps constraint
Yes
 on_event  deprecated
Source has deprecation warnings
Yes
 _compat/  for Pydantic v1/v2
Directory exists with compatibility code
Yes
Every factual claim I checked against the repository is accurate. ATX read the source files, extracted real information, and documented it correctly.

What ATX Can't Do (and Doesn't Pretend To)

The generated documentation has clear boundaries:
No historical context. ATX doesn't know why Sebastián Ramírez chose Starlette over other ASGI frameworks, or why the DI system uses function-based injection rather than class-based. It documents what exists, not the reasoning behind it.
No usage recommendations. The documentation describes how FastAPI works internally, but doesn't tell you "use this pattern for microservices" or "avoid this pattern for high-throughput scenarios." That requires domain expertise beyond static analysis.
No runtime profiling. The complexity analysis identifies structurally complex code (high cyclomatic complexity) but doesn't profile actual performance. Hot paths in production might differ from what static analysis predicts.
No comparison to alternatives. ATX won't tell you "FastAPI is faster than Flask for X" or "consider Django for Y." It documents one codebase, not the ecosystem.
These limitations are appropriate. The documentation serves as a factual reference, not an opinionated guide. Human maintainers can add the "why" and "when" on top of the "what" that ATX provides.

How This Differs from README or Official Docs

FastAPI has excellent official documentation at fastapi.tiangolo.com. So why generate more documentation?
Official docs teach users. They explain how to use FastAPI: create routes, add parameters, validate data. They're written for consumers of the framework.
ATX documentation maps internals. It explains how FastAPI works inside: the routing resolution order, the dependency injection tree construction, the OpenAPI schema generation pipeline, the exception handler chain. It's written for contributors and maintainers.
These serve different audiences:
  • Framework user reads official docs to learn  @app.get("/items/{item_id}") 
  • Framework contributor reads ATX docs to understand how that decorator registers a route in the internal routing table, how path parameters are extracted, and how the response model gets validated
For internal proprietary codebases (where no official docs exist), ATX's output serves both purposes. But even for well-documented OSS projects like FastAPI, the internal architecture documentation fills a gap that official docs intentionally leave empty.

Scaling: Document Your Entire Service Fleet

The real value emerges at organizational scale. Most companies have dozens or hundreds of internal services, each with minimal documentation. The  AWS/comprehensive-codebase-analysis  TD works on any codebase, any language:
Related transformation: AWS has since added  AWS/business-rules-extraction  (Early Access), which goes a step further than documentation — it decomposes a monolith into bounded domains and produces language-neutral, rewrite-ready specifications and a machine-readable manifest. Use  AWS/comprehensive-codebase-analysis  to understand and document a system; reach for  AWS/business-rules-extraction  when you plan to re-architect or rewrite it.
#!/bin/bash
for service in /path/to/services/*/; do
if [ -d "$service/.git" ]; then
echo "Analyzing: $(basename $service)"
atx custom def exec \
--transformation-name "AWS/comprehensive-codebase-analysis" \
--code-repository-path "$service" \
--build-command "true" \
--non-interactive --trust-all-tools
fi
done

Cost at Scale

Codebase Size
Estimated Agent Minutes
Cost
Small (< 1K LOC)
~5 min
$0.18
Medium (1K-10K LOC)
~15-30 min
$0.53-$1.05
Large (10K-50K LOC)
~60-90 min
$2.10-$3.15
Very Large (50K-109K LOC)
~138 min
$4.84
FastAPI at 109K LOC is a large codebase and cost $4.84. Most internal services are 1K-10K lines and would cost $0.50-$1.00 each. Documenting 50 services costs roughly $25-$50 total.
Compare that to the human alternative: even if each service takes only 4 hours to document manually (an optimistic estimate for a 10K-LOC service), that's 200 engineering hours for 50 services. At typical loaded engineering cost, that's $30,000-$50,000 worth of time.

Using the Output with AI Coding Tools

The  ATXDocumentation/  directory serves as context for AI tools. You can:
Feed it to Kiro by adding key sections to  .kiro/steering/ :
cp ATXDocumentation/architecture/patterns.md .kiro/steering/architecture.md
cp ATXDocumentation/behavior/error-handling.md .kiro/steering/error-patterns.md
Feed it to Claude Code/Q Developer by creating an AGENTS.md that references or summarizes the ATX output.
Use it for onboarding by committing the entire  ATXDocumentation/  directory to your repo. New developers read it before touching code.
Use it for architecture reviews by sharing the security analysis and tech debt assessment with reviewers who need to evaluate the system without reading every file.

Continual Learning

Each execution of  AWS/comprehensive-codebase-analysis  contributes lessons. The TD learns from every codebase it analyzes. Running it on FastAPI teaches it about Python framework patterns. Running it on an Express app teaches it about JavaScript middleware architecture. Running it on a Spring Boot service teaches it about annotation-driven Java patterns.
# Review and manage accumulated lessons (interactive TUI)
atx custom def learnings \
--transformation-name "AWS/comprehensive-codebase-analysis"
The TD improves with every execution. Early executions contribute patterns. Later executions benefit from those patterns and contribute new ones. This is the flywheel that makes ATX more accurate over time.

Getting Started

# Install ATX (requires Node.js 22+)
curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

# Authenticate (configure AWS credentials)
aws configure # or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION

# Run on any repository
atx custom def exec \
--transformation-name "AWS/comprehensive-codebase-analysis" \
--code-repository-path /path/to/your/repo \
--build-command "your-test-command" \
--non-interactive --trust-all-tools
The transformation takes 5-138 minutes depending on codebase size. The output is a git branch with the  ATXDocumentation/  directory committed. Review it, merge it, and your codebase has comprehensive documentation that stays accurate because you can re-run the transformation whenever the code changes significantly.
One command. Any codebase. Complete architectural documentation.



Resources

References

[1] AWS, "AWS Transform Custom documentation."  https://docs.aws.amazon.com/transform/latest/userguide/custom.html 
[2] AWS, "AWS Transform pricing."  https://aws.amazon.com/transform/pricing/ 
[3] FastAPI, "FastAPI framework, high performance, easy to learn."  https://github.com/fastapi/fastapi 


Disclaimer: Opinions expressed are personal and do not represent the official position of any organization. All claims about ATX capabilities are verified against the  official documentation .
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article