Codebase Pattern Analyzer

Systematically analyze a reference codebase and extract reusable architectural patterns into structured descriptions. These descriptions become the raw material for new skills (via the

skill-template-generator

When to Use

• You need to understand how a large codebase is structured before replicating it
• You want to extract a specific pattern (component architecture, service layer, API proxy, etc.) from a reference project
• You are bootstrapping a new project that should follow the conventions of an existing one

Step 1: Map the Directory Structure

Read the top-level directory and identify the major code zones:

list_dir <project_root>
list_dir <project_root>/src

Classify each directory into one of these roles:

src/components/

src/services/

src/config/

src/styles/

src/utils/

api/

server/

src/main.ts

Step 2: Identify the Component Pattern

Find the base component class (usually the most imported file in

components/

read_file <project_root>/src/components/Panel.ts

Extract these structural elements:

1. Constructor options interface — what config each component accepts (id, title, className, etc.)
2. DOM structure — how the element tree is built (header, content area, resize handles)
3. Lifecycle methods — constructor, destroy, show/hide, refresh
4. State management — loading/error/content states, fetching guards
5. Data binding — how data flows from service → render → DOM

Record the pattern as:

COMPONENT PATTERN:
  Base class: [name]
  Options: [list of constructor params]
  DOM tree: [element hierarchy]
  States: [loading, error, content]
  Lifecycle: [init → fetch → render → destroy]
  Key methods: [getElement, showLoading, showError, setContent, refresh, destroy]

Step 3: Identify the Service Layer Pattern

Examine 2-3 service files to find the common structure:

read_file <project_root>/src/services/news.ts
read_file <project_root>/src/services/stock-market.ts

Look for:

1. Circuit breaker / resilience — retry logic, cooldown, cached fallback
2. Interface definitions — typed data shapes returned by each service
3. Fetch pattern — how HTTP calls are made (direct fetch, proxy, batching)
4. Caching strategy — TTLs, stale-while-revalidate, in-memory cache
5. Error handling — what happens on failure, default return values

Record as:

SERVICE PATTERN:
  Resilience: [circuit breaker with N failures → cooldown]
  Cache: [in-memory, TTL=Xms]
  Fetch: [browser fetch → /api/... proxy → external API]
  Error: [catch → recordFailure → return default]
  Exports: [async functions, not class instances]

Step 4: Identify the API Proxy Pattern

Read the server-side proxy layer:

list_dir <project_root>/api/
read_file <project_root>/api/_cors.js
read_file <project_root>/api/stocks.ts    # or similar endpoint

Extract:

1. File-per-endpoint structure — one file per API domain
2. CORS handling — origin allowlist, preflight response
3. API key isolation —

   process.env.*

   usage, never exposed to frontend
4. Cache headers —

   Cache-Control

   ,

   s-maxage

   ,

   stale-while-revalidate

5. Error wrapping — structured JSON errors, never raw upstream responses
6. Input validation — query parameter checks before upstream call

Step 5: Identify the Styling System

read_file <project_root>/src/styles/main.css   # first 100 lines for CSS variables

Extract:

1. CSS custom properties — color tokens, font stacks, spacing
2. Theme structure — dark/light mode switch mechanism
3. Grid layout —

   grid-template-columns

   ,

   auto-fill

   ,

   minmax()

   values
4. Component styles — panel base styles, header, content, scrollbar
5. Semantic colors — positive/negative, severity levels, status indicators
6. Typography — font family, sizes, letter-spacing, text-transform

Step 6: Identify the Scheduling / Refresh Pattern

read_file <project_root>/src/app/refresh-scheduler.ts

Extract:

1. Registration API — how panels register their refresh functions
2. Interval management — per-panel configurable intervals
3. Visibility awareness — pause when tab hidden, flush stale on return
4. In-flight guards — prevent duplicate concurrent refreshes
5. Stagger logic — avoid API burst when resuming

Step 7: Synthesize Into Pattern Descriptions

For each pattern discovered, produce a structured description:

## Pattern: [Name]

**Source file(s)**: [paths in reference codebase]
**Category**: component | service | api | style | scheduler | utility

### Structure
[Key structural elements — interfaces, classes, functions]

### Key Code
[Minimal representative code snippet, 20-40 lines]

### Conventions
[Naming, file organization, import paths]

### Dependencies
[Other patterns this depends on]

### Adaptation Notes
[What must change when applying to a different project]

Output

The final output should be a list of pattern descriptions, one per architectural concern. These become the input to the

skill-template-generator

Tips

• Read broadly first, deeply second — scan directory listings before reading individual files
• Follow imports — if a component imports from

  ../services/

  , read that service next
• Count instances — if 10+ components extend the same base class, that's a core pattern
• Note what's NOT used — no framework (React, Vue) means vanilla DOM; no ORM means raw fetch
• Compare 2-3 examples of the same pattern to distinguish the template from the instance-specific parts