Inspecting App Architecture With AI

Joining a new project used to mean weeks of code reading, architecture diagram hunting, and asking teammates "what does this service do?" The codebase is a black box, and understanding it requires manually tracing data flows, mapping dependencies, and building a mental model one file at a time.

AI inverts this process. Instead of reading code to understand architecture, you ask an AI assistant to analyze the codebase and report what it finds. The AI reads thousands of files, identifies patterns, traces dependencies, and produces architectural summaries in minutes.

This tutorial shows you how to use AI to inspect and understand any application's architecture, from small side projects to enterprise monorepos.

Key Takeaways

• AI can map a 200k-line codebase's architecture in under an hour by analyzing file structure, import graphs, and naming conventions
• Dependency cycle detection catches architectural problems that code reviews miss
• Data flow tracing reveals the complete path from user input to database write and back
• AI-generated architecture diagrams serve as living documentation that updates with the codebase
• The technique works on unfamiliar codebases -- you don't need prior knowledge to inspect architecture with AI

Step 1: File Structure Analysis

The first inspection pass looks at how files are organized. File structure reveals architectural intent even before reading a single line of code.

Directory Pattern Recognition

Ask your AI assistant to analyze the top-level directory structure:

Analyze this project's directory structure and identify:
1. The architectural pattern (MVC, hexagonal, feature-based, etc.)
2. Where business logic lives vs infrastructure
3. Any organizational inconsistencies

For a Next.js project like this marketplace, the AI would identify:

• App Router pattern: app/ directory with route-based organization
• Component separation: components/ui/ for primitives, components/ for business components
• Data access layer: lib/supabase/ for database operations
• Clear boundaries: API routes in app/api/, server actions in app/actions/

What File Structure Reveals

Healthy patterns:

• Consistent naming conventions across directories
• Clear separation between UI, data, and business logic
• Feature-based organization at higher levels, type-based at lower levels

Warning signs:

• Files named utils.ts or helpers.ts growing beyond 200 lines (dumping ground)
• Business logic scattered across API routes instead of centralized
• Circular directory dependencies (A imports from B, B imports from A)

Step 2: Import Graph Analysis

The import graph is the skeleton of your architecture. It reveals which modules depend on which, where the coupling is tight, and where boundaries exist.

Building the Import Graph

Use AI to trace imports across the entire codebase:

Trace all import statements in the project. For each file, list:
1. What it imports (dependencies)
2. What imports it (dependents)
3. Whether it imports from external packages or internal modules

Identify the 5 most-imported files (highest fan-in) and the 5 files
that import the most (highest fan-out).

High fan-in files are the foundation of your architecture. If lib/supabase/server.ts is imported by 40 files, it's a critical dependency. Changes to it affect everything.

High fan-out files are integration points. A file that imports 20 other modules is likely orchestrating a complex flow. These files are the hardest to modify and the most likely to contain bugs.

Detecting Dependency Cycles

Circular dependencies are architectural debt. AI can detect them automatically:

Find all circular import chains in the codebase.
A circular chain is A → B → C → A.

For each cycle found, suggest how to break it by:
1. Extracting shared types into a separate module
2. Using dependency injection
3. Introducing an interface boundary

In practice, most cycles involve shared types or configuration. The fix is almost always extracting the shared element into a module that both sides can import without creating a cycle.

Step 3: Data Flow Tracing

Understanding how data moves through an application is the most valuable architectural insight. AI can trace complete data flows from entry point to storage.

Request-to-Response Tracing

Pick a specific user action and trace it end to end:

Trace the complete data flow for "user installs a skill":
1. Where does the request enter the application?
2. What middleware or server actions process it?
3. What database operations occur?
4. What side effects are triggered (cache invalidation, notifications)?
5. What response is sent back to the user?

The AI produces a sequence like:

1. User clicks "Install" button in components/SkillCard.tsx
2. Client calls server action app/actions/trackInstall.ts
3. Server action validates the request
4. Supabase skills table is updated (increment install_count)
5. revalidatePath('/browse') invalidates the cached page
6. Updated count is returned to the client

This trace reveals architectural decisions: why is install tracking a server action instead of an API route? Because server actions provide automatic CSRF protection and don't require a separate API endpoint.

State Flow Analysis

For applications with complex state management, trace how state propagates:

Map the state management architecture:
1. Where is application state stored? (Context, stores, URL params, cookies)
2. How does state flow between components?
3. What triggers state updates?
4. Are there any state synchronization issues between server and client?

This analysis often reveals hidden complexity. A project might use React Context for theme, URL params for filters, server state for data, and local state for form inputs. Understanding which mechanism manages which state is essential for debugging and extending the application.

Step 4: API Surface Mapping

Listing All Entry Points

Every application has an API surface -- the set of entry points that external clients (browsers, other services, CLI tools) can call:

List every public endpoint in this application:
1. API routes (app/api/**/route.ts)
2. Server actions (app/actions/*.ts)
3. Page routes (app/**/page.tsx)
4. Webhook handlers

For each endpoint, note:
- HTTP method and path
- Authentication requirements
- Rate limiting
- Input validation

This produces a complete API catalog that's more accurate than hand-maintained documentation because it's derived from the actual code.

External Dependency Mapping

List all external services this application connects to:
1. APIs (Supabase, Anthropic, GitHub)
2. Third-party libraries that make network calls
3. CDN resources loaded in the browser

For each, note:
- What data flows to/from the service
- What happens if the service is unavailable
- Whether there's a fallback or circuit breaker

This mapping is critical for understanding failure modes. If Supabase goes down, which features degrade and which break completely? AI can answer this by tracing the dependency chains.

Step 5: Pattern Recognition

Identifying Architectural Patterns

AI excels at recognizing patterns across large codebases:

Identify recurring patterns in this codebase:
1. How are errors handled? (try/catch, Result types, error boundaries)
2. How is authentication checked? (middleware, per-route, HOCs)
3. How are database queries structured? (raw, ORM, query builders)
4. How are components composed? (inheritance, composition, render props)

Pattern consistency (or inconsistency) reveals the project's maturity. A project with three different error handling patterns suggests multiple authors or evolving standards. A project with one consistent pattern suggests strong architectural leadership.

Detecting Anti-Patterns

Ask AI to flag potential architectural issues:

Identify potential architectural anti-patterns:
1. God objects (files > 500 lines with many responsibilities)
2. Feature envy (modules that use more of another module's data than their own)
3. Shotgun surgery (changes that require modifying many files)
4. Leaky abstractions (implementation details exposed through interfaces)

These findings aren't always problems -- sometimes a large file is large because the domain is inherently complex. But they're starting points for architectural discussion and improvement.

Automating Architecture Inspection

Creating an Architecture Skill

Combine the techniques above into a reusable AI skill that inspects any project:

## Architecture Inspector Skill

When asked to inspect a project's architecture:

1. Analyze directory structure and identify the organizational pattern
2. Build an import graph and identify high fan-in/fan-out modules
3. Check for circular dependencies
4. Trace 3 representative data flows (read, write, real-time)
5. Map the API surface
6. List external dependencies and their failure modes
7. Identify recurring patterns and anti-patterns

Output a structured report with:
- Architecture summary (2-3 paragraphs)
- Key modules and their responsibilities
- Data flow diagrams (text-based)
- Risk areas and recommendations

This skill produces consistent, comprehensive architectural reports for any project. It's particularly valuable for code review workflows where reviewers need to understand the architectural context of a change.

FAQ

How accurate is AI-generated architecture analysis?

Very accurate for structural analysis (file organization, imports, API surface). Less accurate for intent-based analysis (why was this decision made, what problem does this pattern solve). AI reports what the code does, not necessarily what it should do.

Can this technique work on a codebase I've never seen before?

Yes, and that's its primary value. The technique works best on unfamiliar codebases because the AI has no preconceptions. It analyzes the code as-is, which sometimes reveals patterns that long-time team members have normalized.

How often should I run architecture inspection?

After major refactors, when new team members join, and before large feature additions. Some teams run automated architecture checks in CI to catch dependency cycles and anti-pattern accumulation.

Does this replace architectural documentation?

It complements it. AI-generated architecture reports describe what the code does now. Human-written documentation describes what the code should do and why. Both are valuable, and the AI-generated version can validate whether the human documentation is still accurate.

How do I handle proprietary or sensitive code during inspection?

AI-powered architecture inspection runs locally and doesn't send code to external services (when using tools like Claude Code in local mode). The analysis happens on your machine with your code.

Sources

• Clean Architecture by Robert C. Martin -- Foundational architecture patterns
• Next.js App Router Documentation -- Architecture of Next.js applications
• Anthropic Claude Code Documentation -- AI-assisted code analysis capabilities
• Martin Fowler's Architecture Guide -- Comprehensive software architecture reference

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.