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 tests225 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-servicegit 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/ -vATX 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:
- Add authentication (FastAPI OAuth2 or API key dependency)
- Add CORS middleware with appropriate allowed origins
- Add rate limiting middleware
- Add email validation to UserCreate schema
- 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 updatescancelled_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'sEmailStrtype* Approach: Changeemail: strtoemail: EmailStrin 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.pyAnd 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 UTCThe 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

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-toolsAcross All Services
#!/bin/bashSERVICES=( "/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 -tdoneIn 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 addedAWS/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 withAWS/comprehensive-codebase-analysiswhen 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 servicecd your-serviceatx
# Type: Execute the AWS/comprehensive-codebase-analysis transformationOr non-interactively:
atx custom def exec \ --transformation-name "AWS/comprehensive-codebase-analysis" \ --code-repository-path . \ --non-interactive --trust-all-toolsThe onboarding doc has always been hiding in your codebase. ATX extracts it, organizes it, and makes it immediately useful.
Resources
- AWS Transform Custom docs: docs.aws.amazon.com/transform/latest/userguide/custom.html
- ATX pricing: $0.035/agent-minute
References
[1] AWS, "AWS Transform Custom documentation." https://docs.aws.amazon.com/transform/latest/userguide/custom.html
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 .
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article