Generate Architecture Documentation Automatically from Your Codebase
You know the problem: your app’s architecture documentation is either non-existent, wildly out of date, or buried in scattered wiki pages that nobody reads. By the time you onboard a new developer, they’re confused about module boundaries, data flow, and how components talk to each other. Modern LLMs can solve this. With the right prompts, you can generate accurate, up-to-date architecture documentation directly from your code in minutes. Here’s how.
Why LLMs Excel at Architecture Documentation
Traditional documentation requires humans to write and maintain it manually. It falls behind as your codebase evolves. LLMs, however, can read your actual code and extract the truth about how your system works. They understand dependency relationships, data flows, and module responsibilities by analyzing the code itself. This means your documentation stays in sync with reality, not someone’s outdated memory of how things used to work.
The key is teaching the LLM what format and level of detail you want. Tell it to generate Mermaid diagrams, markdown files with clear sections, or even a visual dependency matrix. LLMs can adapt to your preferred documentation style.
Step 1: Extracting Module Dependencies
Start by asking an LLM to analyze your module structure and create a dependency graph. Provide your project’s settings.gradle or settings.gradle.kts file, along with a brief explanation of your module organization.
“I have an Android multi-module project. Here’s my settings.gradle.kts [paste file]. I want you to create a dependency graph showing: (1) which modules depend on which others, (2) what each module’s primary responsibility is, (3) any circular dependencies or violations of our layering rules. Format the output as a Mermaid graph diagram and a markdown table.”
The LLM will parse your module structure and generate a visual dependency graph. This immediately reveals architectural problems — circular dependencies, modules with too many responsibilities, or layers that shouldn’t depend on each other. You can then use this output as the foundation for your architecture documentation.
Step 2: Data Flow and API Contracts
Next, extract how data flows through your app. Ask the LLM to read key files in your data and domain layers, then generate documentation about data contracts and flows.
“Here are the key data models and repositories in my domain layer [paste UserRepository, OrderRepository, PaymentRepository source files]. Create a markdown document that explains: (1) what each model represents, (2) which API endpoints and database tables back each repository, (3) the overall data flow from API to UI. Include a Mermaid flowchart showing how data moves from API → Repository → UseCase → ViewModel → UI.”
This generates documentation that new developers can actually use. They’ll understand at a glance what data structures your app maintains, where data comes from, and how it flows to the presentation layer. This is especially valuable for teams using clean architecture or domain-driven design, where understanding the domain layer is critical.
Step 3: Generating a Multi-Module ARCHITECTURE.md
Once you have module dependencies and data flows, ask the LLM to synthesize everything into a unified ARCHITECTURE.md file. Provide your module structure, key files from each layer, and your app’s high-level purpose.
“I’m building an e-commerce Android app with a feature-based multi-module architecture. Here’s my module structure [paste settings.gradle.kts], and here are representative files from each layer [paste UserAuthRepository, LoginViewModel, LoginScreen]. Create a comprehensive ARCHITECTURE.md that includes: (1) a module dependency diagram, (2) descriptions of each module’s responsibility, (3) the data flow from API to UI, (4) dependency injection setup (we use Hilt), (5) async patterns (we use coroutines), (6) testing strategy. Format it so it’s readable for developers joining the team.”
The LLM synthesizes all this information into a cohesive document. It will have clear sections, examples, and visual diagrams. New developers can read this in 20 minutes and understand your architecture far better than months of random exploration.
Step 4: Keeping Docs in Sync with Code
Generated documentation only stays accurate if you regenerate it when your architecture changes. Set up a periodic review — say, once per quarter, or whenever you make major architectural changes.
Create a checklist:
- Module changes? If you added, removed, or renamed modules, regenerate the dependency graph
- New layers or patterns? If you introduced new architectural patterns (e.g., a new UseCase layer, a caching strategy), update the data flow diagrams
- API contracts changed? If your API evolved, regenerate the repository and model documentation
- Team practices shifted? If your team adopted new testing patterns or dependency injection approaches, document those changes
You can even ask the LLM: “Here’s my old ARCHITECTURE.md and here are the code changes I’ve made since then. What sections of the documentation should I update?” This keeps your docs maintainable without requiring a human to manually rewrite everything.
Real Example: E-Commerce App Architecture Documentation
Let’s say you have a multi-module e-commerce app. Your modules are:
:core:network # Retrofit, OkHttp setup :core:database # Room database :core:di # Hilt configuration :feature:auth # Login, signup :feature:products # Product listing, search :feature:cart # Shopping cart :feature:orders # Order history, checkout :shared:models # Domain models :shared:navigation # Navigation graph :app # Main application
You give the LLM your settings.gradle.kts, key source files from each module, and ask:
“Generate a comprehensive ARCHITECTURE.md for this e-commerce app. Include module descriptions, a dependency diagram, how authentication flows through the app, how the cart persists data, and how orders are submitted. I’ll commit this to our repository.”
The LLM produces documentation that explains exactly how your app works. This becomes invaluable for new team members and serves as a reference when you’re planning new features.
Advanced: API Contract and Integration Documentation
You can also use LLMs to document API contracts. Provide your Retrofit interfaces and ask the LLM to generate OpenAPI/Swagger-style documentation, or just a readable markdown table of endpoints, parameters, and responses.
“Here are my Retrofit API interfaces [paste UserApi, ProductApi, OrderApi]. Generate a markdown document listing every endpoint, its parameters, response structure, and error codes. Format it like API documentation a frontend team would read.”
This helps teams collaborating across platforms (iOS, backend, web) understand your Android app’s contract with the API server. If you’re working on app architecture documentation in depth, consider reading our comprehensive guide on Claude Code for Android Development Setup.
Integrating Documentation Into Your Workflow
Once you have architecture documentation, make it part of your project:
- Check it into git — store ARCHITECTURE.md or CLAUDE.md in your repo root
- Link it in your README — new developers read the README first, so link to architecture docs there
- Reference it in code reviews — if a PR violates documented architecture, reference the docs in your feedback
- Update it with your code — when you make architectural changes, regenerate the docs as part of the same commit
For a deeper dive into code review practices enhanced by AI, check out our post on Code Review with Claude Code.
Real-World Example Workflow
Here’s how to generate architecture docs from scratch:
- Gather files: Collect your settings.gradle.kts, key repositories, ViewModels, and screens
- Write a prompt: Describe your app’s purpose, architecture style, and what documentation you want
- Review the output: Read the LLM’s generated docs. Does it accurately describe your architecture?
- Iterate: Ask follow-up questions: “Can you add a section on testing strategy?” or “Can you clarify how the cart data persists across app sessions?”
- Commit to repo: Save the final ARCHITECTURE.md in your project
- Schedule quarterly updates: Every few months, regenerate the docs to catch any drift from reality
External Resources
For reference on Android architecture patterns, consult the official Android Architecture Guide. If you use Hilt, the Hilt documentation is the authoritative source for DI patterns.
Conclusion
LLMs can generate accurate, maintainable architecture documentation directly from your code. By asking the right questions and providing the right code samples, you can create documentation that stays in sync with your codebase, helps new developers onboard faster, and serves as a reference for your entire team. Start with module dependencies, move to data flows, and synthesize everything into a cohesive ARCHITECTURE.md. Update it quarterly, and you’ll have documentation that actually reflects how your app works.
This post was written by a human with the help of Claude, an AI assistant by Anthropic.