Skip to content

update-codemap.md

Latest commit

 

History

History
58 lines (46 loc) · 2.2 KB

update-codemap.md

File metadata and controls

58 lines (46 loc) · 2.2 KB

Update the project codemap to reflect the current state of the codebase.

Steps

1. Scan Project Structure

  • Run find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' to get the file tree.
  • Identify the top-level directories and their purposes.
  • Note the primary language(s) and framework(s) from config files (package.json, pyproject.toml, go.mod, Cargo.toml).

2. Identify Key Modules

For each major directory:

  • Purpose: What this module is responsible for.
  • Entry point: The main file that exports or bootstraps the module.
  • Key files: The 3-5 most important files and what they contain.
  • Dependencies: Which other modules this one depends on.

3. Map Data Flow

  • Trace the request lifecycle: entry point -> routing -> business logic -> data access -> response.
  • Identify shared state: databases, caches, message queues, shared config.
  • Note async boundaries: background jobs, event handlers, webhooks.

4. Document Key Patterns

  • Architecture pattern (MVC, layered, hexagonal, microservices).
  • State management approach.
  • Error handling strategy.
  • Testing strategy and test location conventions.

5. Output Format

# Project Codemap

## Structure
src/
  api/        - REST API handlers and middleware
  services/   - Business logic layer
  models/     - Database models and schemas
  utils/      - Shared utilities

## Key Files
- src/api/server.ts    - Express app setup, middleware chain
- src/services/auth.ts - Authentication and JWT handling
- src/models/user.ts   - User model with validation

## Data Flow
Request -> Middleware (auth, validation) -> Handler -> Service -> Repository -> Database

## Patterns
- Dependency injection via constructor parameters
- Repository pattern for data access
- Result type for error handling (no thrown exceptions in services)

Rules

  • Keep the codemap concise. It should fit in one screen for small projects, two for large ones.
  • Focus on orientation, not exhaustive listing. A new developer should understand the project structure in 2 minutes.
  • Update the codemap in CLAUDE.md or a dedicated CODEMAP.md at the project root.
  • Include the build and test commands.