generate-map

name	generate-map
description	Analyze codebase and generate a comprehensive project-map.md overview
argument-hint	[--force]

Generate Project Map Command

You are generating a comprehensive .claude/project-map.md file for this codebase.

Your Task

Analyze the entire codebase and create a clear, concise project map that a new developer can read in a few minutes to understand the system.

Workflow

1. Scan the codebase structure

   • List all top-level directories
   • Identify the main technology stack
   • Find configuration files (package.json, pyproject.toml, docker-compose.yml, etc.)

2. Identify the tech stack

   • Backend framework and language
   • Frontend framework (if any)
   • Database(s)
   • Infrastructure (Docker, K8s, cloud services)
   • Key libraries and dependencies

3. Map the project structure

   • Main folders and their responsibilities
   • Entry points and important files
   • Configuration locations

4. Document the API surface (if applicable)

   • Main endpoints grouped by domain
   • Authentication method
   • Link to OpenAPI/Swagger if available

5. Document the database (if applicable)

   • Main entities and relationships
   • Migration tool and location

6. Document the frontend (if applicable)

   • Main pages/routes
   • Component organization
   • State management approach

7. Document infrastructure

   • How to run the project locally
   • Docker services and ports
   • Environment variables needed

8. Document testing

   • Test frameworks in use
   • How to run tests

Output Format

Create/overwrite .claude/project-map.md with this structure:

# Project Map

> Auto-generated overview of the codebase. Last updated: [date]

## Tech Stack

- **Backend:** [framework, language, version]
- **Frontend:** [framework, language, version]
- **Database:** [type, version]
- **Infrastructure:** [Docker, etc.]
- **Key Libraries:** [list]

## Project Structure

/ ├── backend/ # [description] ├── frontend/ # [description] ├── ...

## API Surface

### [Domain 1]
- `GET /api/...` - [description]
- `POST /api/...` - [description]

### [Domain 2]
...

## Database Schema

Main entities:
- **Entity1** - [description, key fields]
- **Entity2** - [description, key fields]

Relationships: [brief description]

## Frontend Architecture

Main routes:
- `/` - [description]
- `/dashboard` - [description]

Key components: [list]

## Infrastructure

### Local Development
```bash
# Commands to run the project

Docker Services

Service	Port	Description
...	...	...

Environment Variables

Variable	Purpose	Required
...	...	...

Testing

• Framework: [pytest/jest/etc.]
• Run tests: [command]

Development Workflow

1. [Setup step]
2. [Run step]
3. [Test step]

Current Features

• [Feature 1]
• [Feature 2]

Known Limitations

• [Limitation 1]
• [Limitation 2]

## Guidelines

- Keep it concise - aim for a document readable in 5 minutes
- Use bullet points and tables
- Link to detailed docs rather than copying content
- Remove any sections that don't apply
- Be accurate - verify information from actual files

## After Generation

Report to the user:
- Summary of what was documented
- Any areas that need manual review
- Suggestions for missing documentation