# CodeGlance File Insights Prompt

You are a senior developer creating a deep-dive analysis of important files in a codebase. Your goal is to make each file's purpose and usage crystal clear.

## Input Repository
Analyze the repository located at: [REPOSITORY_PATH]

## Your Mission
Create `guide/file-insights.md` - a comprehensive guide to the most important files in the codebase, explaining not just what they do, but how to use them and how they connect to everything else.

## File Selection Criteria

### Intelligent Selection Based on Repository Size

**For Small Repositories (< 50 files):**
Analyze comprehensive selection - up to 20 important files including:
1. **Entry points** (main, index, app)
2. **Core business logic** 
3. **Configuration files**
4. **Key interfaces/contracts**
5. **Central components/modules**
6. **Database schemas/models**
7. **API endpoints/routes**
8. **Frequently modified files**
9. **Files with many dependencies**

**For Medium Repositories (50-500 files):**
Strategic sampling - focus on 12-15 most important files:
1. **Primary entry points** (main application entry)
2. **Key configuration** (most important config files only)
3. **Representative business logic** (1-2 core service files)
4. **Main data models** (primary schemas/models)
5. **Sample API endpoints** (1-2 representing different patterns)
6. **Central components** (main shared components)

**For Large Repositories (500-2000 files):**
Targeted analysis - 8-10 critical files:
1. **Main entry point**
2. **Root configuration** (package.json, main config file)
3. **Core architecture files** (main service, primary controller)
4. **Key data model** (most complex or central model)
5. **Representative API endpoint** (one showing main patterns)
6. **Central shared component** (most used utility/component)

**For Massive Repositories (2000+ files):**
Minimal essential analysis - 5-6 files maximum:
1. **Primary entry point**
2. **Root package.json or main config**
3. **One representative service/controller per major workspace**
4. **Main data model or schema**
5. **Key shared utility or component**

### File Priority Algorithm

Use this scoring system to select files automatically:

**Priority Score = (Dependency Score × 3) + (Complexity Score × 2) + (Centrality Score × 2) + (Modification Score × 1)**

- **Dependency Score**: Number of files importing this file (0-10 scale)
- **Complexity Score**: Lines of code and cyclomatic complexity (0-10 scale)  
- **Centrality Score**: Position in dependency graph centrality (0-10 scale)
- **Modification Score**: Recent commit frequency (0-10 scale)

### Repository Size Detection

Before analysis, count total files using this approach:
```bash
find . -type f -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" | wc -l
```

Adjust analysis depth based on results.

## Document Structure

### Header (Adapted for Repository Size)
```markdown
# 📚 File Insights Guide

> Deep dive into the most important files in this codebase. Each file is explained with its purpose, key functions, connections, and real usage examples.

[For Large/Massive Repositories, add:]
> **Repository Scale**: This is a [size] repository with [X] files. This guide focuses on the most architecturally significant files. For comprehensive exploration, use the navigation guides provided.

## 🎯 Quick Navigation

[Create a table of contents with all documented files grouped by category]

[For Large/Massive Repositories, add:]
### 🗺️ File Selection Strategy
This analysis covers [X] files selected using:
- **Entry Points**: Main application and configuration files
- **Architectural Significance**: Files that define system structure  
- **Representative Sampling**: Key files from each major component/workspace
- **Business Logic**: Core domain logic and data models

**Not Covered**: Individual utility files, generated code, and comprehensive component analysis. See [file-directory-index.md] for complete file listings.
```

### For Each Important File

Create a detailed section following this template:

```markdown
## 📄 [File Path]

### 🎯 Purpose
[One clear sentence explaining why this file exists]

### 📊 Quick Stats
- **Type**: [Component/Service/Config/Model/etc.]
- **Lines**: [Number]
- **Dependencies**: [Count]
- **Imported by**: [Count] files
- **Tests**: [Link to test file if exists]
- **Last modified**: [Date]

### 🔑 Key Exports/Functions

#### `functionName(params)`
**Purpose**: [What it does in plain English]
**Parameters**: 
- `param1` (Type): [Description]
- `param2` (Type): [Description]
**Returns**: [Type] - [Description]
**Usage Example**:
```[language]
// Real-world usage
const result = functionName(value1, value2);
// What this accomplishes: [explanation]
```

[Repeat for each major function/export]

### 🔗 Connections

#### Uses (Dependencies)
- 📁 `[file/module]` - [Why it needs this]
- 📁 `[file/module]` - [Why it needs this]

#### Used By (Dependents)
- 📁 `[file/module]` - [How it uses this file]
- 📁 `[file/module]` - [How it uses this file]

#### Data Flow
```
[Input Source] → This File → [Output Destination]
                    ↓
              [Side Effects]
```

### 💡 Important Concepts

[Explain any complex logic, patterns, or domain concepts in this file]

- **[Concept/Pattern]**: [Clear explanation]
- **[Business Rule]**: [Why it works this way]

### 🎪 Real Usage Examples

#### Example 1: [Common Use Case]
```[language]
// Complete, runnable example
import { something } from './this-file';

// Setup
const config = { ... };

// Usage
const result = something(config);

// What happens: [explanation]
```

#### Example 2: [Another Use Case]
```[language]
// Show different scenario
```

### ⚠️ Important Notes

- [Any gotchas or things to watch out for]
- [Performance considerations]
- [Security implications]
- [Common mistakes to avoid]

### 🔄 Related Files

- **Similar functionality**: `[file]`
- **Tests**: `[test file]`
- **Configuration**: `[config file]`
- **Documentation**: `[docs file]`

---
```

## File Categories

Organize files into logical groups:

### 1. 🚀 Entry Points
Files where the application starts

### 2. 🎯 Core Business Logic
The heart of the application

### 3. 🔌 API/Routes
Endpoints and route handlers

### 4. 💾 Data Layer
Models, schemas, database interaction

### 5. 🎨 UI Components
User interface elements (if applicable)

### 6. ⚙️ Configuration
Settings and environment setup

### 7. 🔧 Utilities
Helper functions and shared tools

### 8. 🧪 Tests
Key test files and patterns

## Analysis Guidelines

### Universal Principles (All Repository Sizes)

1. **Purpose Over Implementation**
   - Explain WHY the file exists before HOW it works
   - Focus on the problem it solves

2. **Connection Mapping**
   - Show how files work together
   - Trace data flow through the system

3. **Visual Aids**
   - Use diagrams for complex flows
   - Add emojis for quick scanning
   - Format for readability

### Adaptive Detail Level

**Small Repositories:**
4. **Comprehensive Examples**
   - Include multiple runnable code examples
   - Show common use cases and edge cases
   - Detailed function-by-function analysis

5. **Complete Connection Analysis**
   - Map all major file relationships
   - Trace full data flows
   - Include detailed dependency graphs

**Medium Repositories:**
4. **Representative Examples**
   - Include key usage patterns
   - Focus on most important functions
   - Show main architectural patterns

5. **Selective Connection Analysis**
   - Focus on most important relationships
   - Highlight key data flows
   - Simplified dependency mapping

**Large/Massive Repositories:**
4. **Strategic Examples**
   - Focus on architectural patterns
   - Show representative usage only
   - Emphasize how files fit in larger system

5. **High-Level Connection Analysis**
   - Focus on component/service boundaries
   - Show major data flows only
   - Abstract dependency relationships

## Special Sections

### 🗺 File Relationship Map
Create a visual overview showing how major files connect:
```
        [Entry Point]
              ↓
        [Router/Controller]
         ↓          ↓
    [Service A] [Service B]
         ↓          ↓
        [Database Layer]
```

### 📈 Complexity Analysis
Identify the most complex files that need extra attention:
```markdown
## 📈 Complexity Analysis

### High Complexity Files (Need careful study)
1. `[file]` - [Why it's complex]
2. `[file]` - [Why it's complex]

### Good Starting Points (Simple and clear)
1. `[file]` - [Why it's good to start here]
2. `[file]` - [Why it's good to start here]
```

### 🎓 Learning Path
Suggest an order for understanding the files:
```markdown
## 🎓 Suggested Reading Order

1. **Start Here**: `[file]` - Understand the entry point
2. **Then**: `[file]` - See how requests are handled
3. **Next**: `[file]` - Learn the business logic
4. **Finally**: `[file]` - Understand data persistence
```

## Output Quality Checks

Ensure each file documentation has:
- ✅ Clear one-sentence purpose
- ✅ Practical usage examples
- ✅ Connection to other files
- ✅ Real code that could be copy-pasted
- ✅ Visual elements for easy scanning
- ✅ Warnings about common pitfalls
- ✅ Links to related resources

Generate the file-insights.md for [REPOSITORY_PATH] now.