🧠 Codebase Understanding Skill

---

name: codebase-understanding description: Deeply understand entire codebases including file relationships, architecture patterns, and data flows

🎯 Purpose

เข้าใจ codebase ทั้งหมดอย่างลึกซึ้ง รู้ความสัมพันธ์ระหว่างไฟล์, architecture patterns, และ data flows เพื่อให้แก้ไขได้ตรงจุด

📋 When to Use

• เริ่มทำงานกับ project ใหม่
• ต้องการแก้ไขที่กระทบหลายไฟล์
• Debug ปัญหาที่ซับซ้อน
• Refactor code ขนาดใหญ่
• ทำความเข้าใจ legacy code

🔧 Analysis Dimensions

1. File Structure Analysis

📁 Project Root
├── 📁 src/
│   ├── 📁 components/  ← UI components (React/Vue)
│   ├── 📁 pages/       ← Page components / routes
│   ├── 📁 hooks/       ← Custom hooks
│   ├── 📁 services/    ← API calls
│   ├── 📁 stores/      ← State management
│   ├── 📁 utils/       ← Helper functions
│   └── 📁 types/       ← TypeScript types
├── 📁 public/          ← Static assets
├── 📁 tests/           ← Test files
└── 📄 config files     ← package.json, tsconfig, etc.

2. Dependency Graph

Component A
    │
    ├──imports──► Hook B
    │               │
    │               └──uses──► Store C
    │                            │
    └──imports──► Util D         │
                    │            │
                    └──uses──────┘

3. Data Flow Analysis

User Action
    │
    ▼
Component (Event Handler)
    │
    ▼
Store Action (State Update)
    │
    ▼
API Service (Fetch Data)
    │
    ▼
Component Re-render (Display Data)

📝 Understanding Process

1. SCAN Project Structure
   - Read package.json (dependencies, scripts)
   - Identify framework (React, Vue, Next.js)
   - Map folder structure

2. IDENTIFY Key Files
   - Entry points (main.tsx, App.tsx)
   - Config files (tsconfig, vite.config)
   - Route definitions

3. TRACE Dependencies
   - Import relationships
   - Component hierarchy
   - State management flow

4. UNDERSTAND Patterns
   - Architecture patterns used
   - Coding conventions
   - State management approach

5. MAP Data Flows
   - User interactions → Events
   - Events → State changes
   - State → API calls → Renders

🔍 Key Questions to Answer

Question	How to Find
What framework?	package.json dependencies
How is routing done?	App.tsx, pages folder
Where is state?	stores/, context/, hooks/
How are API calls made?	services/, api/ folders
What's the component tree?	Trace from App.tsx
Where are types?	types/, *.d.ts files

📊 Analysis Output Template

## 🧠 Codebase Analysis: {project-name}

### Tech Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **State**: Zustand
- **API**: REST with React Query

### Architecture
- **Pattern**: Feature-based structure
- **Components**: Atomic design (atoms, molecules, organisms)
- **State Flow**: Unidirectional (Zustand stores)

### Key Files
| Purpose | File |
|---------|------|
| Entry | `app/layout.tsx` |
| Routing | `app/*/page.tsx` |
| Main Store | `stores/appStore.ts` |
| API Client | `lib/api.ts` |

### Dependency Map
```mermaid
graph TD
    A[App Layout] --> B[Pages]
    B --> C[Components]
    C --> D[Hooks]
    D --> E[Stores]
    E --> F[API Services]

Notable Patterns

• Uses custom hooks for data fetching
• Implements optimistic updates
• Server components for static content

Potential Issues

• Some circular dependencies in utils
• Large component files (>300 lines)

## 🎯 Framework-Specific Patterns

### React/Next.js

• Components: src/components/
• Pages: app/ or pages/
• Hooks: src/hooks/
• State: Zustand, Redux, Context

### Vue/Nuxt

• Components: src/components/
• Pages: pages/
• Composables: composables/
• State: Pinia

### Express/Node

• Routes: routes/
• Controllers: controllers/
• Models: models/
• Middleware: middleware/

## ✅ Understanding Checklist

- [ ] Framework and key dependencies identified
- [ ] File structure understood
- [ ] Entry points located
- [ ] State management approach known
- [ ] API patterns understood
- [ ] Component relationships mapped
- [ ] Coding conventions noted

## 🔗 Related Skills

- `code-search` - Find specific code patterns
- `code-explanation` - Explain complex code
- `refactoring` - Improve codebase structure