understand-codebase

name	understand-codebase
description	Codebase'i derinlemesine anla. Onboarding, architecture discovery, dependency mapping.

Understand Codebase

Onboarding Workflow (Yeni Developer)

Hizli Baslangic (5 Dakika)

1. Tech stack tespit:
   ls package.json go.mod pyproject.toml tsconfig.json Cargo.toml manage.py

2. Proje yapisi:
   tldr tree . --depth 2

3. Entry point'leri bul:
   tldr structure . --lang <detected-lang>

4. README/docs oku:
   cat README.md CONTRIBUTING.md docs/

5. CI/CD kontrol:
   ls .github/workflows/ .gitlab-ci.yml Jenkinsfile Dockerfile

Detayli Kesif (30 Dakika)

1. Architecture overview:
   tldr arch src/

2. Import/dependency graph:
   tldr calls src/

3. Test yapisi:
   tldr tree . --ext .test.ts,.spec.ts,.test.py,_test.go

4. Config dosyalari:
   ls *.config.* .env.example docker-compose.yml

5. Data modelleri:
   Grep "interface|type|class|struct|model" --type ts/py/go

Codebase Overview Olusturma

Otomatik Overview

# 1. Dosya dagilimi
tldr tree . | wc -l  # toplam dosya
tldr tree . --ext .ts,.tsx  # TypeScript dosyalari
tldr tree . --ext .test.ts  # Test dosyalari

# 2. Kod yapisi
tldr structure src/ --lang typescript
# Fonksiyonlar, class'lar, export'lar

# 3. Mimari katmanlar
tldr arch src/
# Entry (controller/handler) > Middle (service) > Leaf (util)

# 4. Dead code
tldr dead src/ --entry main,test_

Overview Template

# Project: <name>

## Tech Stack
- Language: <lang> <version>
- Framework: <framework> <version>
- Database: <db>
- CI/CD: <tool>

## Architecture
- Pattern: <MVC|Clean|Hexagonal|Monolith|Microservice>
- Entry points: <files>
- Layers: <controller → service → repository → model>

## Key Directories
- src/         → Kaynak kod
- tests/       → Test dosyalari
- config/      → Konfigürasyon
- scripts/     → Yardimci scriptler
- docs/        → Dokumantasyon

## Key Files
- <entry-file>  → Uygulama entry point
- <config-file> → Ana konfigürasyon
- <schema-file> → Data modelleri
- <route-file>  → API routing

## Data Flow
<request → middleware → controller → service → repository → database>

## External Dependencies
- <key-dep-1>: <purpose>
- <key-dep-2>: <purpose>

Architecture Dokumentasyonu

Katman Tespiti

# tldr arch ile otomatik tespit
tldr arch src/
# Cikti: entry_layer, middle_layer, leaf_layer, circular_deps

# Manuel tespit: import yonlerini takip et
tldr calls src/ --depth 3

Mimari Patern Tespiti

Ipucu	Patern
controllers/, routes/, handlers/	MVC / REST API
domain/, application/, infrastructure/	Clean Architecture
ports/, adapters/	Hexagonal
services/, modules/	Modular Monolith
packages/, apps/	Monorepo
pages/, app/ (Next.js)	File-based routing
resolvers/, schema/	GraphQL
commands/, queries/, events/	CQRS
aggregates/, entities/, value-objects/	DDD

Architectural Decision Records (ADR)

# codebase-memory MCP ile ADR yonetimi
mcp_codebase_memory.manage_adr({
  action: "create",
  title: "Use PostgreSQL for primary database",
  status: "accepted",
  context: "Need ACID transactions, complex queries",
  decision: "PostgreSQL 16 with pgvector extension",
  consequences: "Need DBA expertise, managed service cost"
})

# ADR listele
mcp_codebase_memory.manage_adr({ action: "list" })

Key File Identification

Otomatik Tespit

# Entry point'ler
tldr structure . --lang typescript | grep -i "main\|index\|app\|server"

# Konfigürasyon
ls -la *.config.* .env* tsconfig.json package.json

# Schema/Model
tldr search "schema\|model\|entity\|interface" src/ --lang typescript

# Routing
tldr search "router\|route\|endpoint\|controller" src/

Kritik Dosya Kategorileri

Kategori	Nasil Bul	Neden Onemli
Entry point	main.ts, index.ts, app.ts	Uygulamanin baslangici
Config	.config., .env	Ortam ayarlari
Schema/Model	models/, schema/, types/	Data yapisi
Routes	routes/, controllers/	API surface
Middleware	middleware/	Cross-cutting concerns
Database	migrations/, seeds/	DB yapisi
Tests	.test., .spec.	Test coverage
CI/CD	.github/workflows/	Build/deploy
Docker	Dockerfile, docker-compose	Container config

Dependency Mapping

Package Dependency Analizi

# Node.js
cat package.json | jq '.dependencies, .devDependencies'

# Python
cat requirements.txt  # veya pyproject.toml
pip list --outdated

# Go
cat go.mod
go list -m all

# Rust
cat Cargo.toml

Internal Dependency Graph

# Dosyalar arasi import iliskileri
tldr calls src/ --depth 2

# Spesifik dosyanin import'lari
tldr imports src/services/auth.ts

# Kim bu modulu import ediyor?
tldr importers auth src/

# Impact analizi (refactoring oncesi)
tldr impact processOrder src/ --depth 3

Dependency Risk Analizi

Risk	Kontrol	Arac
CVE/vulnerability	npm audit / pip audit	snyk, dependabot
Outdated	major version farki	npm outdated
Unmaintained	Son commit 1+ yil	GitHub API
License risk	GPL in commercial	license-checker
Size bloat	Bundle size	bundlephobia

Data Flow Tracing

Request-Response Flow

# Fonksiyon cagri zinciri
tldr calls src/ --depth 4

# Spesifik fonksiyonun cagri yolu
tldr trace_call_path src/ fromFunction toFunction

# Data flow analizi
tldr dfg src/services/order.ts processOrder

# Program slice (spesifik satiri etkileyen her sey)
tldr slice src/services/order.ts processOrder 42

Data Flow Mapping Template

USER INPUT
  → Validation (middleware/schema)
  → Controller (routing, request parse)
  → Service (business logic)
  → Repository (data access)
  → Database (persistence)
  → Response (serialization)
  → USER OUTPUT

Side effects:
  → Queue (async processing)
  → Cache (read optimization)
  → External API (3rd party)
  → Event bus (pub/sub)

State Management Flow (Frontend)

User Action
  → Event Handler (onClick, onChange)
  → State Update (useState, dispatch, store.set)
  → Re-render (component tree)
  → Side Effect (useEffect, subscription)
  → API Call (fetch, axios)
  → State Update (response)
  → Re-render

API Surface Discovery

REST API Endpoints

# Route tanimlarini bul
Grep "router\.(get|post|put|patch|delete)\|app\.(get|post|put|patch|delete)" src/

# Express/Fastify route'lar
tldr search "route\|endpoint" src/ --lang typescript

# OpenAPI spec varsa
cat openapi.yaml  # veya swagger.json

GraphQL Schema

# Schema tanimlarini bul
Grep "type Query|type Mutation|type Subscription" src/

# Resolver'lari bul
tldr search "resolver\|Resolver" src/

API Dokumantasyonu

Her endpoint icin:
  - Method + Path: GET /api/users/:id
  - Auth: Bearer token / API key / Public
  - Request: Query params, body schema
  - Response: Success (200), Error (4xx, 5xx)
  - Rate limit: X req/min

Test Coverage Mapping

Test Yapisi Analizi

# Test dosyalarini bul
tldr tree . --ext .test.ts,.spec.ts,.test.py,_test.go

# Test/source orani
echo "Source files:" && tldr tree src/ --ext .ts,.tsx | wc -l
echo "Test files:" && tldr tree . --ext .test.ts,.spec.ts | wc -l

# Hangi dosyalarin testi YOK
tldr dead src/ --entry test_  # test'lerden cagrilmayan fonksiyonlar

Coverage Raporu

# Node.js
npx jest --coverage --coverageReporters=text-summary

# Python
pytest --cov=src --cov-report=term-missing

# Go
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Test Gap Analizi

Dosya/Modul	Unit Test	Integration	E2E	Risk
Auth service	var	var	yok	HIGH
Payment	var	var	var	LOW
User CRUD	var	yok	yok	MEDIUM
Config	yok	yok	yok	LOW

Tech Debt Identification

Otomatik Tespit

# Dead code
tldr dead src/ --entry main,test_,handle,route

# Buyuk dosyalar (800+ satir)
find src/ -name "*.ts" -exec wc -l {} + | sort -rn | head -20

# TODO/FIXME/HACK
Grep "TODO|FIXME|HACK|XXX|TEMP|WORKAROUND" src/

# Complexity (control flow)
tldr cfg src/services/complex.ts processData
# Cok fazla branch = refactoring gerekli

# Diagnostics (type error + lint)
tldr diagnostics src/ --project

Tech Debt Kategorileri

Kategori	Gostergeler	Oncelik
Dead code	Kullanilmayan fonksiyon/import	LOW
God file	800+ satir dosya	MEDIUM
Missing tests	Coverage <50%	HIGH
Outdated deps	Major version farki	MEDIUM
Security	CVE, hardcoded secret	CRITICAL
Duplication	Benzer kod bloklari	MEDIUM
Complexity	Cyclomatic >10	HIGH

Knowledge Graph (codebase-memory MCP)

Repository Indexleme

mcp_codebase_memory.index_repository({
  path: "/path/to/project",
  name: "my-project"
})

Graph Sorgulama

// Mimari overview
mcp_codebase_memory.get_architecture({
  project: "my-project"
})

// Kod arama
mcp_codebase_memory.search_code({
  project: "my-project",
  query: "authentication flow"
})

// Graph schema
mcp_codebase_memory.get_graph_schema({
  project: "my-project"
})

// Degisiklik tespiti
mcp_codebase_memory.detect_changes({
  project: "my-project"
})

Entegrasyon: tldr CLI + codebase-memory MCP

Tam Analiz Workflow

# 1. Yapi (tldr)
tldr tree . --depth 2
tldr structure src/ --lang typescript

# 2. Mimari (tldr)
tldr arch src/
tldr calls src/ --depth 3

# 3. Indexle (codebase-memory MCP)
mcp_codebase_memory.index_repository({ path: ".", name: "project" })

# 4. Graph sorgu (codebase-memory MCP)
mcp_codebase_memory.get_architecture({ project: "project" })

# 5. Impact analizi (tldr)
tldr impact targetFunction src/ --depth 3

# 6. Dead code (tldr)
tldr dead src/ --entry main

# 7. Diagnostics (tldr)
tldr diagnostics src/ --project

# 8. Test impact (tldr)
tldr change-impact --git

Surekli Guncelleme

Her onemli degisiklikte:
1. tldr change-impact → etkilenen testleri bul
2. mcp_codebase_memory.detect_changes → graph'i guncelle
3. tldr dead src/ → yeni dead code kontrol
4. tldr diagnostics src/ → type/lint hata kontrolu

Anti-Patterns

Anti-Pattern	Dogru Yol
Hemen koda dal	Once overview al, sonra oku
Tek dosya oku, anladim san	Cagri zincirini takip et
grep ile yetiniyor	tldr structure + arch kullan
Mimariyi varsay	tldr arch ile dogrula
Dead code'u gormezden gel	tldr dead ile periyodik temizlik
Test coverage bilme	Coverage raporu al, gap analiz yap
Dependency'leri kontrol etme	npm audit / pip audit periyodik calistir

Quick Reference

HIZLI: "Bu proje ne yapar?"
  → tldr tree . && cat README.md

ORTA: "Nasil calisir?"
  → tldr arch src/ && tldr calls src/

DERIN: "Bu fonksiyon neyi etkiler?"
  → tldr impact <func> src/ && tldr dfg <file> <func>

TAM: "Her seyi anlamam lazim"
  → Yukaridaki Tam Analiz Workflow'u takip et