repowiki

name	repowiki
description	Generate DeepWiki-style repository analysis reports. Deeply analyze codebase architecture, module dependencies, and core systems, outputting structured documentation with Mermaid diagrams, source file references, and tables.
version	1.0.0
allowed-tools	["Read","Bash","Glob","Grep"]
triggers	["generate repo report","repowiki","deepwiki","analyze this repo","generate project docs","repository report","codebase analysis","generate wiki"]

RepoWiki - Repository Report Generator

Generate a DeepWiki-style in-depth analysis report based on the current repository's code structure, configuration files, and dependency relationships.

Report Structure Specification

The generated report must strictly follow the layered structure below, output as a single Markdown file.

Layer 1: Project Overview

# {Project Name}

> {One-line project positioning description}

## Purpose & Scope

{2-3 paragraphs describing what problem the project solves, core value, target users}

## Tech Stack

| Category | Technology | Purpose |
|----------|-----------|---------|
| Language | ... | ... |
| Framework | ... | ... |
| Build Tool | ... | ... |
| Testing | ... | ... |
| Database | ... | ... |

## Repository Structure

{Mermaid graph showing top-level directory structure and module relationships}

## Core Systems Overview

{Mermaid graph showing interactions between major subsystems}

Layer 1.5: Concept & Design Philosophy

Between the project overview and module analysis, add a section that explains the core ideas and technical rationale behind the project — not what it does, but why it was built this way.

## Design Philosophy & Key Decisions

### Core Concept
{1-2 paragraphs explaining the fundamental insight or approach that drives the project's design.
 What problem does the conventional approach have? What alternative mental model does this project adopt?}

### Key Technical Decisions

| Decision | Chose | Over | Rationale |
|----------|-------|------|-----------|
| {e.g., State management} | {Zustand} | {Redux, Context API} | {Why — specific trade-off reasoning} |
| ... | ... | ... | ... |

### Architecture Principles
{2-4 bullet points capturing the non-obvious design principles extracted from the code.
 Each should explain a constraint or convention the codebase follows, and WHY.}

This layer is critical for DeepWiki-quality reports: readers need to understand the "why" before diving into the "what".

Layer 2: Module & Package Analysis

## Module Inventory

| Module | Path | Responsibility | Key Dependencies |
|--------|------|---------------|-----------------|
| ... | ... | ... | ... |

## Module Dependency Architecture

{Mermaid graph: inter-module dependency diagram}

## {Module Name} Detailed Analysis

<details>
<summary>Related Source Files</summary>

- `path/to/file1.ts`
- `path/to/file2.ts`
</details>

### Responsibilities & Boundaries
{What this module is and isn't responsible for}

### Internal Architecture
{Mermaid graph: class/function relationships within the module}

### Key Interfaces
{Code block: main exported APIs, type definitions, interfaces}

### Data Flow
{Mermaid sequence/flowchart: how data flows within the module}

Layer 3: Core System Deep Analysis

Generate an independent section for each core system:

## {System Name}

<details>
<summary>Related Source Files</summary>

- `path/to/relevant/file.ts`
</details>

### Problem & Approach
{Start each core system section with a narrative arc:
 1. What problem does this system solve?
 2. What is the conventional/naive approach, and why doesn't it work here?
 3. What insight or approach does this project use instead?
 This "problem → conventional failure → project's solution" arc is critical for DeepWiki-quality analysis.}

### System Architecture
{Mermaid graph: overall architecture diagram of the system}

### Core Workflows
{Mermaid sequence diagram: main business processes}

### Key Components

| Component | File | Responsibility |
|-----------|------|---------------|
| ... | ... | ... |

### Design Decisions & Trade-offs

| Decision | Chose | Over | Rationale |
|----------|-------|------|-----------|
| ... | ... | ... | ... |

{For each major design decision within this system, explain what was chosen over what alternatives, and why. This comparison table is required for every core system section.}

### Configuration & Extension Points
{Code block: key configuration file snippets}

Layer 4: Infrastructure & Toolchain

## Build System

### Build Pipeline
{Mermaid flowchart: complete process from source to artifacts}

### Build Configuration
{Table: key build configuration items}

## Testing Infrastructure

### Testing Strategy
| Test Type | Tool | Coverage |
|-----------|------|----------|
| Unit Tests | ... | ... |
| Integration Tests | ... | ... |
| E2E Tests | ... | ... |

### Test Configuration
{Code block: key test configuration file snippets}

## CI/CD Pipeline
{Mermaid flowchart: CI/CD process}

## Dependency Management
### Key Dependencies
| Dependency | Version | Purpose |
|-----------|---------|---------|
| ... | ... | ... |

### Dependency Strategy
{Version locking, update strategy, security auditing}

Mermaid Diagram Specifications

IMPORTANT: Mermaid syntax pitfalls to avoid:

• Do NOT use parentheses () inside node labels or edge labels — they break the parser. Use （） (fullwidth) or rephrase instead.
• Do NOT use special characters {}[]() unescaped inside label strings. Wrap labels in ["..."] if they contain special characters.
• Always test that your diagram type declaration (graph, flowchart, sequenceDiagram, stateDiagram-v2) matches the syntax used in the body.

Each report must include the following types of diagrams:

1. Repository Structure Diagram (Required)

graph TD
    Root[Project Root]
    Root --> Src[src/]
    Root --> Config[Configuration]
    Root --> Tests[tests/]
    Src --> Core[core/]
    Src --> Utils[utils/]
    Src --> Types[types/]

2. Module Dependency Diagram (Required)

graph LR
    A[Module A] --> B[Module B]
    A --> C[Module C]
    B --> D[Module D]
    C --> D

3. Core Workflow Diagram (Required)

sequenceDiagram
    participant User
    participant API
    participant Service
    participant DB
    User->>API: Request
    API->>Service: Process
    Service->>DB: Query
    DB-->>Service: Result
    Service-->>API: Response
    API-->>User: Return

4. Data Flow Diagram (As Needed)

flowchart LR
    Input[Input] --> Validate[Validate]
    Validate --> Transform[Transform]
    Transform --> Process[Process]
    Process --> Output[Output]

5. State/Lifecycle Diagram (As Needed)

stateDiagram-v2
    [*] --> Created
    Created --> Active
    Active --> Paused
    Paused --> Active
    Active --> Completed
    Completed --> [*]

Analysis Execution Flow

Step 1: Collect Repository Metadata

Use the following tools to gather information (execute in parallel):

1. Directory Structure - Use Glob to scan **/* for the complete file tree
2. Package Management - Read package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml, etc.
3. Configuration Files - Read tsconfig.json, .eslintrc.*, vite.config.*, webpack.config.*, etc.
4. CI/CD - Read .github/workflows/*, .gitlab-ci.yml, Dockerfile, etc.
5. Git History - Get file change frequency from the last 100 commits

Step 2: Identify Core Systems

Determine core systems based on the following signals:

Signal	Weight	Method
File change frequency	High	git log statistics
Directory size	Medium	File count
Entry file references	High	grep import/require
README mentions	Medium	Read documentation
Export count	Medium	grep export

Step 3: Deep Analysis of Each System

For each core system, perform:

1. Read all files in that directory
2. Identify main class, function, and type definitions — include file:line references (e.g., src/engine.ts:42) for key definitions so readers can navigate directly to the source
3. Trace import/export dependency chains
4. Identify design patterns (Repository, Factory, Observer, etc.)
5. Extract key configurations and constants
6. For critical algorithms or workflows, provide step-by-step code logic analysis — trace through the actual implementation, not just describe what it does at interface level

Step 4: Generate Mermaid Diagrams

Based on the analysis results, generate:

• At least 1 architecture overview diagram
• At least 1 module dependency diagram
• At least 1 core workflow sequence diagram
• Add state diagrams and data flow diagrams as needed

Step 5: Assemble Report

Assemble the complete report according to the structure specification above, output to REPOWIKI.md.

Source File Reference Specification

Each section must include collapsible source file references:

<details>
<summary>Related Source Files</summary>

- `src/core/engine.ts` - Core engine implementation
- `src/core/types.ts` - Type definitions
- `src/config/default.ts` - Default configuration
</details>

Reference rules:

• Only reference files directly related to the current section
• Each reference includes a brief description
• Sort by importance, most critical files first
• 3-10 referenced files per section

Table Usage Specification

Tables must be used in the following scenarios:

1. Tech Stack - Inventory of languages, frameworks, and tools
2. Module Inventory - Paths, responsibilities, and dependencies of all modules
3. Configuration Comparison - Configuration differences across environments/modes
4. API Inventory - Methods, parameters, and return values of public APIs
5. Dependency Inventory - Versions and purposes of key dependencies

Output Requirements

1. Filename: REPOWIKI.md, placed in the repository root
2. Language: Match the user's conversation language (Chinese conversation = Chinese report)
3. Length:
   • Small projects (<50 files): 800-1500 lines
   • Medium projects (50-200 files): 1500-3000 lines
   • Large projects (>200 files): 3000-6000 lines
4. Diagram count: At least 3 Mermaid diagrams, 6-10 for large projects
5. Table count: At least 3 tables
6. Code blocks: Key configurations and interface definitions, no more than 30 lines each

Quality Checklist

After generating the report, verify the following items:

• Contains project overview and one-line positioning
• Tech stack table is complete and accurate
• Repository structure Mermaid diagram matches reality
• Each core system has an independent section
• Each section has collapsible source file references
• Module dependency diagram correctly reflects actual dependencies
• At least one sequence diagram shows core workflows
• All tables are correctly formatted with accurate content
• Code block syntax highlighting is correct
• No fabricated files or modules
• Mermaid diagram syntax is correct and renderable

Example Snippet

Below is a report snippet example for a TypeScript web project:

# MyApp

> A full-stack e-commerce platform built on Next.js, supporting multi-tenancy and real-time inventory management.

## Purpose & Scope

MyApp is an e-commerce SaaS platform for small and medium-sized merchants. It provides
product management, order processing, payment integration, and real-time inventory
synchronization as core features. The project uses Next.js App Router architecture,
Prisma as the ORM, and PostgreSQL as the primary database.

## Tech Stack

| Category | Technology | Purpose |
|----------|-----------|---------|
| Language | TypeScript 5.3 | Full-stack development language |
| Framework | Next.js 14 | Full-stack React framework |
| ORM | Prisma 5.8 | Database access layer |
| Database | PostgreSQL 16 | Primary data storage |
| Cache | Redis 7 | Session and hot data caching |
| Testing | Vitest + Playwright | Unit and E2E testing |

## Repository Structure

```mermaid
graph TD
    Root["myapp/"]
    Root --> App["app/ - Next.js App Router"]
    Root --> Lib["lib/ - Shared Business Logic"]
    Root --> Components["components/ - UI Components"]
    Root --> Prisma["prisma/ - Database Schema"]
    Root --> Tests["tests/ - Test Files"]

    App --> API["api/ - API Routes"]
    App --> Pages["(routes)/ - Pages"]
    Lib --> Services["services/ - Business Services"]
    Lib --> Utils["utils/ - Utility Functions"]

Core Systems Overview

graph LR
    Client["Client"] --> AppRouter["App Router"]
    AppRouter --> Auth["Auth System"]
    AppRouter --> API["API Layer"]
    API --> OrderService["Order Service"]
    API --> ProductService["Product Service"]
    API --> PaymentService["Payment Service"]
    OrderService --> DB["PostgreSQL"]
    ProductService --> DB
    ProductService --> Cache["Redis"]
    PaymentService --> Stripe["Stripe API"]

Order System

Related Source Files

• lib/services/order.ts - Order service core logic
• app/api/orders/route.ts - Order API routes
• prisma/schema.prisma - Order data model
• lib/validators/order.ts - Order data validation
• components/order/OrderForm.tsx - Order form component

Purpose & Scope

The order system manages the complete order lifecycle from shopping cart to payment completion. This includes order creation, inventory locking, payment processing, status transitions, and notification delivery.

Order Lifecycle

stateDiagram-v2
    [*] --> Created: User places order
    Created --> Paying: Initiate payment
    Paying --> Paid: Payment successful
    Paying --> Cancelled: Payment timeout/failure
    Paid --> Shipping: Merchant ships
    Shipping --> Completed: Delivery confirmed
    Completed --> [*]
    Cancelled --> [*]

## Language/Framework Adaptation

Adjust analysis focus based on project type:

| Project Type | Analysis Focus |
|-------------|---------------|
| Node.js/TypeScript | package.json, tsconfig, module exports |
| Go | go.mod, package structure, interface definitions |
| Python | pyproject.toml, package structure, class hierarchy |
| Rust | Cargo.toml, crate structure, trait definitions |
| Java/Kotlin | pom.xml/build.gradle, package structure, class hierarchy |
| Monorepo | workspace config, inter-package dependencies, build order |
| Frontend SPA | routing structure, state management, component tree |
| Backend API | route definitions, middleware chain, data models |
| CLI Tool | command structure, argument parsing, subcommands |