codebase-overview

To document codebase architecture, you can generate a CODEBASE.md file that maps the project structure, tech stack, critical modules, and entry points. This living document guides teams by enforcing evidence-based descriptions drawn directly from actual code artifacts.

Mapping project structure involves analyzing top-level directories, key modules, dependencies, and coding conventions. The result is a comprehensive CODEBASE.md overview that helps new developers understand data flows and navigate the codebase effectively.

Evidence-based code analysis avoids incorrect architecture assumptions by citing actual code artifacts rather than guessing module behavior from directory or file names. This strict approach ensures the generated documentation accurately reflects the true tech stack and data flows.

Yes, you can generate a CODEBASE.md file automatically by running an analysis of your existing project. The tool scopes top-level directories, identifies patterns, and outputs the documentation directly to ./.gtd/CODEBASE.md without requiring manual writing.

You should update your codebase documentation after major refactors to ensure the living CODEBASE.md accurately reflects structural changes, new dependencies, and updated entry points. Rerunning the analysis keeps the architecture overview aligned with the actual codebase.

Generating a codebase overview works across various tech stacks because the analysis identifies the specific frameworks, dependencies, and patterns present in your project. It scopes top-level directories and modules to produce an accurate architecture map regardless of the stack.