AWS Builder Center

The 10-Minute Onboarding Doc Your Codebase Has Been Hiding

225 lines of Python, one AWS Transform command, 32 docs: architecture, security, tech debt, and API reference for fast developer onboarding.

225 lines of Python. One ATX command. 32 documentation files totaling 1,700 lines: architecture diagrams, security analysis, tech debt assessment, migration planning, and API reference. Everything a new developer needs to understand the system without reading a single line of source code.



The Onboarding Tax

Every time a developer touches an unfamiliar repo, they pay an onboarding tax. The README says "Order Service" and nothing else. The code is clean enough, but there's no map: no architecture overview, no explanation of which layer does what, no "here's how to add a new endpoint" guide.
So the developer opens files one by one, traces imports, reads function signatures, runs the tests, and slowly builds a mental model. For a 225-line service this takes maybe 30 minutes. For a 10,000-line service? Half a day. For a microservices estate with 50 services? A new hire spends their first week just orienting.
The information exists in the code. It's just not extracted, organized, or presented in a form that's immediately useful to someone who hasn't spent hours with it already.
AWS Transform Custom has an AWS-managed transformation called  AWS/comprehensive-codebase-analysis  that does this extraction automatically. It reads your code and produces a complete, hierarchical documentation suite covering architecture, behavior, security, technical debt, and migration planning.

The Starting Point

A FastAPI order service. Clean architecture, but minimal documentation:
order-service/
├── pyproject.toml
├── README.md ← "Order management REST API." (literally one line)
├── src/
│ ├── main.py ← FastAPI app, router registration, health check
│ ├── api/ ← Route handlers (orders.py, users.py)
│ ├── schemas/ ← Pydantic models (orders.py, users.py)
│ └── services/ ← Business logic (order_service.py, user_service.py)
└── tests/
└── test_orders.py ← 4 integration tests
225 lines of Python. 4 passing tests. FastAPI + Pydantic + structlog. If you're new to this repo, the one-line README tells you nothing about how it's structured, what patterns it uses, or where to start.

Running the Analysis

cd order-service
git init && git add . && git commit -m "initial: FastAPI order service"

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

> Execute the AWS/comprehensive-codebase-analysis transformation on this
repository. Validation command: pytest tests/ -v
ATX reads every source file, traces the internal dependency graph, identifies architectural patterns, assesses security posture, evaluates technical debt, and generates a hierarchical documentation suite.

What ATX Produced: 32 Files, 1,700 Lines

The output is a complete  ATXDocumentation/  directory:
32 files changed, 1700 insertions(+)
Here's the structure, but more importantly, here's what's in those files.

The Architecture Documentation

ATX identified the layered architecture pattern and documented each layer's responsibility, key decisions, and the relationships between components.
From  architecture/system-overview.md :
The application follows a layered architecture with clear separation of concerns:1. API Layer ( src/api/ ): Route handlers, HTTP concerns, request/response mapping 2. Schema Layer ( src/schemas/ ): Data validation and serialization models (Pydantic) 3. Service Layer ( src/services/ ): Business logic and data access**Key Architectural Decisions:**1. In-memory storage: Data persists only for the lifetime of the process. 2. Synchronous handlers: Despite FastAPI's async capabilities, all handlers are synchronous, appropriate given no I/O-bound operations. 3. Service-per-resource pattern: Each resource (orders, users) has its own service class and router. 4. UUID-based identifiers: All entities use UUID4 string identifiers.

ATX didn't just list the directories. It explained why the architecture is the way it is.

The Component Diagram

ATX generated ASCII diagrams that render anywhere (terminals, markdown viewers, plain text):
┌─────────────────────────────────────────────────┐
│ FastAPI Application │
│ (src/main.py) │
├─────────────────────┬───────────────────────────┤
│ │ │
│ ┌──────────────┐ │ ┌──────────────┐ │
│ │ Orders Router│ │ │ Users Router │ │
│ │ (api/orders) │ │ │ (api/users) │ │
│ └──────┬───────┘ │ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────▼───────┐ │ ┌──────▼───────┐ │
│ │OrderService │ │ │UserService │ │
│ │(services/ │ │ │(services/ │ │
│ │order_service)│ │ │user_service) │ │
│ └──────┬───────┘ │ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────▼───────┐ │ ┌──────▼───────┐ │
│ │Order Schemas │ │ │User Schemas │ │
│ │(schemas/ │ │ │(schemas/ │ │
│ │orders) │ │ │users) │ │
│ └──────────────┘ │ └──────────────┘ │
└─────────────────────┴───────────────────────────┘
And the internal architecture view:
┌──────────────────────────────────────────┐
│ HTTP / ASGI Layer │
│ (Uvicorn) │
├──────────────────────────────────────────┤
│ Application Framework │
│ (FastAPI) │
├────────────────────┬─────────────────────┤
│ /api/orders/* │ /api/users/* │
│ Orders Router │ Users Router │
├────────────────────┼─────────────────────┤
│ OrderService │ UserService │
│ (business logic) │ (business logic) │
├────────────────────┼─────────────────────┤
│ dict[str, dict] │ dict[str, dict] │
│ (order store) │ (user store) │
└────────────────────┴─────────────────────┘
A new developer looking at this immediately understands the request flow: HTTP comes in through Uvicorn, FastAPI routes it to the correct router, the router calls the service, the service manages the in-memory store.

The Sequence Diagrams

ATX generated behavioral diagrams showing how key operations work:
Client FastAPI OrderRouter OrderService structlog
│ │ │ │ │
│ POST /api/orders/ │ │ │
│───────────────►│ │ │ │
│ │ validate body │ │ │
│ │───────────────►│ │ │
│ │ │ create(payload) │
│ │ │───────────────►│ │
│ │ │ │ uuid4() │
│ │ │ │ store order │
│ │ │ │ log event │
│ │ │ │───────────────►│
│ │ │ order dict │ │
│ │ │◄───────────────│ │
│ │ 201 + JSON │ │ │
│◄───────────────│ │ │ │
This shows exactly which components are involved in creating an order and in what sequence. No code reading required.

The Security Analysis

ATX performed a full security assessment without being asked:
From  analysis/security-patterns.md :
Area
Status
Finding
Authentication
Not implemented
All endpoints publicly accessible
Input validation
Pydantic
 quantity > 0 ,  total > 0  enforced via  Field(gt=0) 
CORS
Not configured
No CORS headers (default)
Rate limiting
Not implemented
No protection against abuse
Injection
N/A
No database, no shell commands
Logging security
Good
structlog prevents log injection, no PII in logs
Recommendations:
  1. Add authentication (FastAPI OAuth2 or API key dependency)
  1. Add CORS middleware with appropriate allowed origins
  1. Add rate limiting middleware
  1. Add email validation to UserCreate schema
  1. Add HTTPS enforcement for production
A security reviewer reading this has an immediate picture of the attack surface without auditing the code manually.

The Decision Logic

ATX extracted every decision point and documented it as pseudocode:
From  behavior/decision-logic.md :
Order Cancellation Decision (src/services/order_service.py:cancel):

IF order_id NOT in _orders
→ Return None (caller raises 404)
ELSE
→ Set status = "cancelled"
→ Set cancelled_at = current UTC time
→ Return updated order

Note: No guard against cancelling an already-cancelled order.
The cancellation is idempotent in terms of status but updates
cancelled_at on each call.
ATX noticed the missing guard and flagged it. That's the kind of insight that takes a human developer 10 minutes of code reading to discover.

The Tech Debt Assessment

From  technical-debt-report.md :
RECOMMENDED AWS TRANSFORMATIONS: None. This is a small, modern Python 3.11+ FastAPI application with current dependencies and no legacy patterns. No version upgrade, SDK migration, or architectural transformation from the available AWS-managed catalog applies.
Then the prioritized findings:
Severity
Item
Impact
Medium
No persistent storage
Data lost on restart. Not production-ready.
Medium
No authentication
All endpoints publicly accessible
Low
Incomplete test coverage
User endpoints untested
Low
No email validation
Email field accepts any string
Low
No pagination
List endpoints return all records
Low
Open version constraints
 >=  without upper bounds
Low
No API versioning
Breaking changes affect all clients
And the remediation plan with specific implementation guidance:
Priority 1: Add Persistent Storage* Action: Integrate PostgreSQL via SQLAlchemy* Approach: Extract repository interfaces from services, implement database-backed repositories* Complexity: Significant effortPriority 2: Add Email Validation* Action: Use Pydantic's  EmailStr  type* Approach: Change  email: str  to  email: EmailStr  in UserCreate* Complexity: Minimal effort


The Migration Planning

ATX generated a dependency-based migration order, useful if you need to add a database, change frameworks, or decompose the service:
Layer 1: Foundation (No internal dependencies)
1. src/schemas/orders.py
2. src/schemas/users.py

Layer 2: Business Logic (Depends on schemas)
3. src/services/order_service.py
4. src/services/user_service.py

Layer 3: API (Depends on schemas + services)
5. src/api/orders.py
6. src/api/users.py

Layer 4: Application Bootstrap (Depends on API)
7. src/main.py

Layer 5: Tests (Depends on everything)
8. tests/test_orders.py
And validation criteria (checklist format):
- [ ] Health endpoint returns {"status": "ok"} with 200
- [ ] Order creation returns 201 with valid OrderResponse
- [ ] Order cancellation updates status to "cancelled"
- [ ] OrderCreate rejects quantity <= 0 (422)
- [ ] All responses match declared response_model schemas
- [ ] Order IDs are valid UUID4 strings
- [ ] Timestamps are timezone-aware UTC

The Anti-Patterns It Found

ATX didn't just document what's there. It identified patterns that could become problems at scale:
From  architecture/patterns.md :
Anti-Pattern: Service-as-Repository Services combine business logic and data access in a single class. While acceptable for this scale, it would limit testability and flexibility at larger scale.Anti-Pattern: Module-Level State Service instances holding mutable state at module level couples application lifetime with data lifetime and prevents easy testing in isolation.
These are the insights that a senior developer would share during a code review. ATX surfaces them automatically.

The Transformation Flow

ATX Comprehensive Codebase Analysis


The 10-Minute Onboarding Claim

Can a developer actually understand this codebase in 10 minutes? Here's the reading path:
Step
Document
What you learn
Time
1
 project-overview.md 
Tech stack, features, deployment model
1 min
2
 architecture/system-overview.md 
Layers, key decisions, why things are the way they are
2 min
3
 diagrams/structural/components.md 
Visual component map, dependency graph, class diagram
2 min
4
 reference/api-reference.md 
Every endpoint with request/response schemas
2 min
5
 technical-debt-report.md 
What to watch for, what's missing
1 min
6
 migration/component-order.md 
Where to start if adding something
1 min
Total

Complete mental model, zero code reading
9 min
After 9 minutes, a new developer knows: the tech stack (FastAPI, Pydantic, structlog), the architecture (3-layer, service-per-resource), what each file does (components.md), every API endpoint (api-reference.md), what's missing (no persistence, no auth), and where to start adding things (schemas first, then services, then routes).
They haven't opened a single source file.

Scaling This Across Your Org

Non-Interactive Mode

atx custom def exec \
--transformation-name "AWS/comprehensive-codebase-analysis" \
--code-repository-path /path/to/service \
--non-interactive --trust-all-tools

Across All Services

#!/bin/bash
SERVICES=(
"/path/to/order-service"
"/path/to/user-service"
"/path/to/payment-service"
"/path/to/notification-service"
)

for service in "${SERVICES[@]}"; do
echo "=== Analyzing: $(basename $service) ==="
atx custom def exec \
-n "AWS/comprehensive-codebase-analysis" \
-p "$service" \
-x -t
done
In one afternoon, every service has a complete documentation suite. New hires read docs instead of spelunking through code. On-call engineers understand unfamiliar services in minutes instead of hours. AI tools (Kiro, Claude Code) get the context they need to generate correct code.
Cost: In one example run this analysis took a handful of agent minutes at $0.035/agent-minute, on the order of ~$0.18 for a small service. Agent-minutes are non-deterministic and scale with codebase size and analysis depth, so larger services cost more (a large codebase can run to dozens or hundreds of agent-minutes). Treat per-service and fleet totals as estimates and run a pilot to establish your own baseline.
Related transformation: If your goal is not just onboarding docs but a rewrite-ready spec, AWS added  AWS/business-rules-extraction  (Early Access). It statically decomposes a monolith into bounded domains and extracts per-domain business rules, workflows, and a machine-readable manifest — the "yardstick" you validate a rewrite against. Pair it with  AWS/comprehensive-codebase-analysis  when you're documenting a system you also intend to modernize.

What This Enables

Faster onboarding. New hires read the generated docs on day one instead of spending a week tracing code.
Better AI tool performance. Commit the output as documentation (or reshape key parts into an AGENTS.md) and AI coding tools immediately produce higher-quality code that follows the project's patterns.
Incident response. On-call engineers facing an unfamiliar service at 2am read the architecture overview and component map. They find the relevant code in seconds instead of minutes.
Architecture reviews. The security analysis and tech debt assessment give reviewers a starting point without manual code auditing.
Migration planning. The dependency-ordered component list and validation criteria tell you exactly how to decompose, migrate, or refactor the service safely.

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 against any service
cd your-service
atx

# Type: Execute the AWS/comprehensive-codebase-analysis transformation
Or non-interactively:
atx custom def exec \
--transformation-name "AWS/comprehensive-codebase-analysis" \
--code-repository-path . \
--non-interactive --trust-all-tools
The onboarding doc has always been hiding in your codebase. ATX extracts it, organizes it, and makes it immediately useful.



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/ 


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