# Project Analysis Methods

How to read and understand an unfamiliar code project.

## 1. Identify the Entry Point

Every project has a door. Find it first.

### By Language

| Language | Look for |
|---|---|
| **JavaScript/TypeScript** | `package.json` → `main` / `bin` / `scripts.dev` |
| **Python** | `setup.py` → `entry_points`, `pyproject.toml` → `[project.scripts]`, or top-level `app.py` / `main.py` / `__main__.py` |
| **Go** | `package main` in any file, conventionally `main.go` or `cmd/*/main.go` |
| **Rust** | `src/main.rs` or `src/bin/*.rs` |
| **Java** | Class with `public static void main(String[] args)` |
| **C/C++** | `main()` function, conventionally in `src/main.c` |
| **Swift** | `main.swift` or file with `@main` attribute |

### In Frameworks

| Framework | Entry point |
|---|---|
| Next.js | `app/` or `pages/` directory, `next.config.js` |
| React (Vite) | `src/main.tsx` or `src/main.jsx` |
| Vue (Vite) | `src/main.ts` or `src/main.js` |
| Express | File that calls `app.listen()` |
| FastAPI | File that creates `FastAPI()` instance |
| Django | `manage.py`, then project name directory with `urls.py` / `wsgi.py` |
| Flask | `app.py` or `app/__init__.py` |
| Spring Boot | `*Application.java` with `@SpringBootApplication` |

## 2. Judge Project Complexity

Don't over-engineer simple projects. Don't under-analyze complex ones.

### Simple (<50 files, single language)
- Read every source file.
- No need for flow diagrams beyond a simple sequence.
- A light `/explore` pass is probably enough.

### Standard (50-500 files, 1-2 languages)
- Read entry point + core modules + 1-2 feature files.
- Build 1-2 flow diagrams.
- `/explore` is the right level.

### Complex (>500 files, multi-language, monorepo)
- Read entry point + architecture docs + one representative module.
- Use `/essence` to find standout designs, or `/explore` for one package at a time.
- Do NOT try to understand the whole project in one pass.

## 3. Separate Core Code from Scaffolding

Not all files are worth reading.

### Ignore (scaffolding)
- `*.config.js`, `*.config.ts` — configuration, not logic
- `dist/`, `build/`, `out/` — generated output
- `node_modules/`, `vendor/`, `.venv/` — dependencies
- `*.lock`, `yarn.lock`, `go.sum` — lock files
- `LICENSE`, `CODEOWNERS`, `.editorconfig` — project meta
- `test/fixtures/`, `test/data/` — test data

### Read (core)
- Entry point file
- Router/middleware/config handlers
- Model/entity/schema definitions
- Core algorithm or business logic files
- Files referenced most in imports

### Hint: Follow imports

```
entry file → import A → import B → core logic
```

Each import is a dependency. Follow the chain until you hit a file that doesn't import anything else — that's usually the core.

## 4. Read Unfamiliar Framework Code

You don't know every framework. That's fine.

### Strategy

1. **Find the routing layer first.** Every framework has a way to map URLs or events to handlers. Find it. It tells you the project's capabilities.

2. **Follow ONE request end-to-end.** Don't try to understand all routes. Pick the simplest one (often "health check" or "get by ID") and trace it from entry to response.

3. **Identify the framework's conventions.** Most frameworks follow a pattern:
   - MVC: Controller → Model → View
   - Middleware: Request → Middleware chain → Handler → Response
   - Component: Parent renders children, props flow down, events flow up
   - Plugin: Core calls hooks, plugins register handlers

4. **Don't fight the framework's abstraction.** If the project uses ORM, don't look for raw SQL. If it uses dependency injection, don't look for `new()` calls. Understand what abstraction layer they chose.

5. **Use the framework's own docs.** If stuck on "how does this framework work?", check the official docs. Don't reverse-engineer what's documented.