How to audit a codebase
What to check before you take responsibility for someone else's code.
When to audit a codebase
You should audit a codebase before:
- Taking over maintenance from another developer or team - Acquiring a company (technical due diligence) - Hiring a vendor and reviewing their deliverables - Onboarding to a legacy project at a new job - Deciding whether to rewrite or refactor
The goal is not to find every bug. It is to understand the system well enough to estimate the cost and risk of maintaining it.
Architecture review
Start with the big picture. How is the system structured?
Questions to answer:
- What are the major components (frontend, backend, database, external services)? - How do they communicate (REST, GraphQL, message queues, direct database access)? - Is there clear separation between layers (presentation, business logic, data access)? - Are there single points of failure? - How does the system scale? Is it a monolith, microservices, or serverless?
CodeDashboard generates architecture diagrams and data flow visualizations automatically. Run the repo through it for a quick structural overview before diving into the code.
Technology and dependency analysis
Check what the project depends on and whether those dependencies are current:
- List all frameworks and major libraries with versions. - Check for end-of-life or deprecated dependencies. - Look for known vulnerabilities (`npm audit`, `pip audit`, Snyk, or Dependabot). - Count the total number of dependencies. An unusually high number can indicate maintenance risk. - Check if dependencies are pinned to specific versions or use ranges.
CodeDashboard's tech stack section detects all technologies and versions from the codebase.
Code quality signals
You cannot read every line, but you can look for signals:
- Test coverage: Does the project have tests? Are they unit tests, integration tests, or both? Run the test suite and check for failures. - Linting configuration: Is there an ESLint, Prettier, or equivalent config? This indicates code style consistency. - Type safety: Is the project using TypeScript, type hints (Python), or a type system? Untyped code has higher maintenance risk. - Error handling: Search for try/catch blocks, error boundaries, and error logging. Sparse error handling means runtime failures will be harder to debug. - Code complexity: Look at the largest files. Functions over 100 lines and files over 500 lines are signals of accumulated complexity.
Security assessment
A full security audit is out of scope for most code audits, but check the basics:
- Authentication: How are users authenticated? Are passwords hashed (bcrypt, argon2)? Are tokens validated properly? - Authorization: Is there role-based access control? Are API endpoints protected? - Input validation: Is user input validated before processing? Look for SQL injection, XSS, and command injection vectors. - Secrets management: Are API keys, database credentials, and tokens stored in environment variables? Check git history for accidentally committed secrets. - HTTPS: Is all traffic encrypted? Are cookies set with Secure and HttpOnly flags?
Database and data assessment
Review the database schema and data practices:
- Is the schema well-normalized? Are there redundant or unused tables? - Are indexes defined for frequently queried columns? - Are migrations used for schema changes? - Is there a backup strategy? - Is sensitive data encrypted at rest? - Does the schema have clear relationships (foreign keys, constraints)?
Documentation and maintainability
Evaluate how easy it will be to maintain the code going forward:
- Does the README explain how to run the project? - Are there architecture docs or ADRs? - Is there a CONTRIBUTING guide? - How active is the commit history? (Last commit > 6 months ago is a warning sign for active projects.) - Are there open issues or PRs that reveal ongoing problems?
CodeDashboard's handover readiness score combines several of these signals into a single metric.
Write up your findings
Summarize the audit in a short document:
1. Overview: What the system does, major technologies, team size (if known). 2. Architecture: How the system is structured, key components, and data flow. 3. Risks: Security concerns, outdated dependencies, missing tests, technical debt. 4. Recommendation: Go/no-go decision with specific conditions or follow-up actions.
Keep the writeup to 1-2 pages. The goal is a decision-support document, not a textbook.
Key takeaways
- 1Audit codebases before acquisitions, vendor reviews, or inheriting maintenance responsibility.
- 2Start with architecture (structure) before looking at code quality (details).
- 3Check dependencies for vulnerabilities and end-of-life status.
- 4Look for test coverage, type safety, and error handling as quality signals.
- 5Use CodeDashboard to generate the architectural overview in under 2 minutes.
Related guides
How to understand a GitHub repo
A step-by-step process for making sense of any codebase you have never seen before.
How to do a code handover
The handover checklist that saves you from "just one more question" emails for the next 3 months.
What is codebase documentation?
The types of documentation every codebase needs, and how to create them without burning out.
Try CodeDashboard free for 7 days
Paste a GitHub URL and get a full visual dashboard in under 2 minutes. No credit card required for free accounts.