docs-generator

name	docs-generator
description	Comprehensive documentation generation through automated codebase analysis, pattern detection, and diagram creation.

Purpose

Generate comprehensive, up-to-date documentation by analyzing the codebase to:

• Detect architectural patterns AND exceptions/outliers
• Document high-level architecture and low-level implementation details
• Analyze feature structures (core vs domain features)
• Map state management patterns (Redux, Sagas, Slices)
• Document component patterns and organization
• Generate Mermaid diagrams for visual understanding
• Create organized, navigable documentation structure
• Output to date-based directories (docs/YYYY-MM-DD/)

Problem Solved: After major refactoring, documentation becomes obsolete. This skill regenerates comprehensive documentation automatically by analyzing the actual codebase, ensuring docs always match reality.

Target Audience: Developers who will use this React template as a starter for their projects.

Scope

• Analyzes entire codebase structure
• Detects patterns in:
  • Feature organization (feature-model architecture)
  • State management (Redux Toolkit + Redux Saga)
  • Component patterns and hooks abstraction
  • Dependency injection and interfaces
  • Business logic separation
  • Testing patterns
• Generates multiple organized documentation files (NOT one god file)
• Creates Mermaid diagrams for architecture visualization
• Outputs to docs/YYYY-MM-DD/ (same day overwrites)
• Incremental generation: analyze one feature at a time

Documentation Structure

docs/YYYY-MM-DD/
├── README.md                         # Main navigation and overview
├── architecture/
│   ├── README.md                     # Architecture overview
│   ├── feature-model-pattern.md      # Core architectural pattern
│   ├── dependency-injection.md       # DI and interface pattern
│   ├── state-management.md           # Redux/Saga patterns
│   ├── business-logic-separation.md  # ActionEffects pattern
│   └── diagrams/
│       ├── architecture-overview.mmd
│       ├── feature-structure.mmd
│       ├── data-flow.mmd
│       └── dependency-graph.mmd
├── features/
│   ├── README.md                     # Features overview
│   ├── core/
│   │   ├── README.md                 # Core features summary
│   │   ├── app.md                    # Application bootstrap
│   │   ├── i18n.md                   # Internationalization
│   │   ├── router.md                 # Routing infrastructure
│   │   ├── slice-manager.md          # Redux slice lifecycle
│   │   └── ui.md                     # Design system
│   └── domain/
│       ├── README.md                 # Domain features summary
│       ├── wallet.md                 # Wallet feature (3 models)
│       ├── oauth.md                  # OAuth feature (1 model)
│       └── blog-demo.md              # Blog demo (2 models)
├── patterns/
│   ├── README.md                     # Patterns overview
│   ├── component-patterns.md         # Component organization
│   ├── hook-patterns.md              # Custom hooks patterns
│   ├── testing-patterns.md           # Test organization
│   └── code-quality.md               # Code quality patterns
├── guides/
│   ├── README.md                     # Guides overview
│   ├── getting-started.md            # Quick start guide
│   ├── adding-new-feature.md         # How to add domain feature
│   ├── creating-new-model.md         # How to add model to feature
│   ├── testing-guide.md              # Testing best practices
│   └── deployment.md                 # Deployment guide
└── api-reference/
    ├── README.md                     # API reference overview
    ├── hooks.md                      # All custom hooks
    ├── services.md                   # Service implementations
    ├── types.md                      # Important type definitions
    └── utilities.md                  # Utility functions

Analysis Scripts

Each script performs specific analysis and generates structured data for documentation.

1. Feature Analysis (analyze_feature.mjs)

Purpose: Analyze a single feature's structure, patterns, and implementation.

What it detects:

• Feature category (core vs domain)
• Models (for domain features)
• Directory structure and organization
• Interfaces and their relationships
• Redux slice structure
• Saga patterns and action effects
• Component organization
• Hook abstractions
• Exception cases and outliers

Output: JSON structure with feature metadata

Usage:

node ./.claude/skills/docs-generator/scripts/analyze_feature.mjs <feature-name>

2. Architecture Analysis (analyze_architecture.mjs)

Purpose: Analyze overall architectural patterns across all features.

What it detects:

• Feature dependency graph
• Core vs domain feature relationships
• Composition root pattern usage
• Dependency injection patterns
• Interface architecture patterns
• Common patterns across features
• Architectural outliers/exceptions

Output: JSON structure with architecture metadata

3. State Management Analysis (analyze_state_management.mjs)

Purpose: Analyze Redux/Saga patterns and state structure.

What it detects:

• Redux slice organization
• Saga patterns (takeEvery, takeLatest, etc.)
• Action creator patterns
• State shape and nesting
• Selector patterns
• Business logic location (actionEffects)

Output: JSON structure with state management patterns

4. Component Analysis (analyze_components.mjs)

Purpose: Analyze React component patterns.

What it detects:

• Component organization by feature
• Hook usage patterns (useActions, useTypedSelector)
• Component composition patterns
• Props interfaces
• HOC usage
• Storybook coverage

Output: JSON structure with component patterns

5. Diagram Generation (generate_diagrams.mjs)

Purpose: Generate Mermaid diagrams for visual documentation.

Diagrams generated:

• Architecture overview (features and relationships)
• Feature structure (model-based organization)
• Data flow (Redux → Saga → API)
• Dependency graph (feature dependencies)
• State shape (Redux store structure)

Output: .mmd files in docs/YYYY-MM-DD/architecture/diagrams/

6. Main Documentation Generator (generate_docs.mjs)

Purpose: Orchestrate all analysis scripts and generate final documentation.

Process:

1. Run all analysis scripts
2. Collect structured data (JSON)
3. Apply documentation templates
4. Generate markdown files
5. Create diagrams
6. Output to docs/YYYY-MM-DD/

Usage:

# Generate full documentation
node ./.claude/skills/docs-generator/scripts/generate_docs.mjs

# Generate for specific feature only
node ./.claude/skills/docs-generator/scripts/generate_docs.mjs --feature wallet

Incremental Generation Strategy

As requested, documentation generation should be incremental (one feature at a time):

Phase 1: Core Infrastructure

1. Analyze app/ feature (composition root, providers)
2. Analyze i18n/ feature (internationalization)
3. Analyze router/ feature (routing)
4. Analyze slice-manager/ feature (Redux lifecycle)
5. Analyze ui/ feature (Mantine theme)

Phase 2: Domain Features (Examples)

1. Analyze wallet/ feature (3 models: provider, network, account)
2. Analyze oauth/ feature (1 model: session)
3. Analyze blog-demo/ feature (2 models: post, author)

Phase 3: Cross-Cutting Concerns

1. Architecture patterns (dependency injection, interfaces)
2. State management patterns (Redux/Saga)
3. Component patterns (hooks abstraction)
4. Testing patterns

Phase 4: Diagrams

1. Architecture overview diagram
2. Feature structure diagrams
3. Data flow diagrams
4. Dependency graphs

Phase 5: Guides

1. Getting started guide
2. Adding new feature guide
3. Creating new model guide
4. Testing guide

Pattern Detection

The analysis scripts should detect both common patterns and exceptions/outliers.

Common Patterns (Expected)

Feature-Model Pattern

• Domain features have models/ directory
• Each model has own directory
• Model structure: IModelApi.ts, actions.ts, slice.ts, actionEffects/, types/
• Root has IFeatureApi.ts, slice.ts (combineReducers), sagas.ts

Business Logic Separation

• All business logic in actionEffects/ (Redux Saga)
• Slices are pure state containers
• Components are pure presentation

Interface Architecture

• Models define interfaces: IModelApi.ts
• Root combines: IFeatureApi.ts extends IModel1Api, IModel2Api
• Services implement interfaces
• ActionEffects receive injected APIs

Component-Hook Abstraction

• Components use feature hooks (NOT Redux directly)
• Each feature has hooks/ with useActions and state hooks
• NO direct useDispatch() or useSelector() in components

Outliers/Exceptions (Detected)

Core Features

• Do NOT follow model pattern (specialized structures)
• app/, i18n/, router/, slice-manager/, ui/
• Each has unique structure optimized for its purpose

Single Model Features

• Some features may have only ONE model
• Still must follow directory structure: models/session/
• Example: oauth/ has only session model

Composition Root

• src/config/ is special exception
• Can import anything (services, model internals, etc.)
• This is intentional for dependency injection

Special Cases

• Storybook files: require default exports (exception to rule)
• Type definition files: may use "any" type (exception)
• Test files: different structure and rules

Documentation Templates

Templates provide structure for consistent documentation generation.

Feature Template

# {Feature Name}

**Category:** {Core | Domain}
**Models:** {List of models or "N/A"}
**Purpose:** {Brief description}

## Overview

{Detailed description of feature purpose and responsibility}

## Structure

{Directory tree}

## Models

{For domain features - document each model}

### {Model Name}

**Purpose:** {Model responsibility}
**State:** {State shape}
**Actions:** {Key actions}
**Business Logic:** {ActionEffects overview}

## API

### Hooks

- `use{Feature}()` - {Description}
- `use{Feature}Actions()` - {Description}

### Interfaces

- `I{Feature}Api` - {Description}
- `I{Model}Api` - {Description}

## Usage Example

```typescript
{Code example}

Implementation Details

{Key implementation patterns}

Testing

{Testing patterns for this feature}

## Architecture Pattern Template

```markdown
# {Pattern Name}

## Overview

{Pattern description and purpose}

## Problem Solved

{What problem this pattern solves}

## Implementation

{How it's implemented in this codebase}

## Examples

{Real examples from codebase}

## Benefits

{Why this pattern is used}

## Common Pitfalls

{Things to avoid}

Process

Step 1: Invoke Skill

User invokes: docs-generator skill

Step 2: Initial Setup

1. Check if docs/ directory exists, create if needed
2. Determine date-based output directory: docs/YYYY-MM-DD/
3. If same day directory exists, confirm overwrite with user
4. Create output directory structure

Step 3: Feature Analysis (Incremental)

Start with ONE feature (as requested by user):

# Example: Start with wallet feature
node ./.claude/skills/docs-generator/scripts/analyze_feature.mjs wallet

This generates:

• Feature structure analysis (JSON)
• Model documentation (if domain feature)
• Hook documentation
• Component documentation
• Feature-specific diagram

Step 4: Expand to All Features

Once single-feature generation works:

# Generate all features
node ./.claude/skills/docs-generator/scripts/generate_docs.mjs --all

Step 5: Architecture Analysis

node ./.claude/skills/docs-generator/scripts/analyze_architecture.mjs

Generates:

• Architecture overview
• Pattern documentation
• Dependency graphs
• Architectural diagrams

Step 6: Generate Guides

node ./.claude/skills/docs-generator/scripts/generate_guides.mjs

Generates:

• Getting started guide
• How-to guides
• Best practices
• API reference

Step 7: Verification

1. Check all files generated successfully
2. Verify Mermaid diagrams render correctly
3. Check internal links work
4. Validate markdown formatting

Output Format

Documentation Generation Report
================================================================================

Analysis Phase:
  ✅ Feature Analysis: 8 features analyzed
  ✅ Architecture Analysis: Complete
  ✅ State Management Analysis: Complete
  ✅ Component Analysis: Complete

Generation Phase:
  ✅ Feature Documentation: 8 files generated
  ✅ Architecture Documentation: 5 files generated
  ✅ Pattern Documentation: 4 files generated
  ✅ Guides: 5 files generated
  ✅ API Reference: 4 files generated
  ✅ Diagrams: 5 Mermaid diagrams generated

Output: docs/2025-11-02/

Summary:
  - Total Files: 31
  - Total Diagrams: 5
  - Features Documented: 8 (5 core, 3 domain)
  - Patterns Documented: 4 core patterns

✅ Documentation generation complete!

Tools

• Bash: Run Node.js analysis scripts
• Read: Read source files for analysis
• Write: Generate documentation files in docs/YYYY-MM-DD/
• Glob: Find files by pattern for analysis
• Grep: Search for code patterns

Safety

• Read-only analysis (except documentation output)
• No source file modifications
• No external network calls
• Documentation isolated in docs/ directory
• Same-day overwrites are intentional (iterative workflow)

Implementation Notes

TypeScript AST Parsing

Scripts use TypeScript Compiler API for accurate code analysis:

• Parse interfaces and types
• Detect exports and imports
• Analyze function signatures
• Extract JSDoc comments

Pattern Detection Algorithm

1. Scan all features: Analyze directory structure
2. Identify common patterns: What 80% of features do
3. Flag exceptions: What 20% of features do differently
4. Categorize exceptions: Core features vs genuine outliers
5. Document both: Patterns as rules, exceptions as special cases

Diagram Generation

Use Mermaid syntax for diagrams:

• graph TD for architecture diagrams
• classDiagram for interface relationships
• sequenceDiagram for data flow
• flowchart for process flows

Template Application

1. Load template
2. Replace placeholders with analyzed data
3. Generate markdown
4. Write to output directory

Usage Examples

Generate Full Documentation

# Run the docs-generator skill
# This will analyze entire codebase and generate comprehensive docs

Generate Single Feature Documentation

# Analyze and document wallet feature only
node ./.claude/skills/docs-generator/scripts/analyze_feature.mjs wallet

Regenerate After Refactoring

# After major refactoring, regenerate all docs
# Same-day output will overwrite previous documentation
node ./.claude/skills/docs-generator/scripts/generate_docs.mjs --all

Custom Output Directory

# Generate docs to custom directory
export DOCS_DIR="docs/custom-timestamp"
node ./.claude/skills/docs-generator/scripts/generate_docs.mjs

Success Criteria

✅ Comprehensive: Covers all features, patterns, and architecture ✅ Accurate: Generated from actual code, not assumptions ✅ Organized: Multiple categorized files, not one huge file ✅ Visual: Includes Mermaid diagrams for complex concepts ✅ Navigable: Clear structure with README files and links ✅ Up-to-date: Regenerates from current codebase state ✅ Incremental: Can generate one feature at a time ✅ Pattern-aware: Detects both patterns AND exceptions ✅ Developer-focused: Written for template users, not just maintainers