claude-buddy/dist/.claude/skills/generators/docs-generator/templates/jhipster-docs.md

Claude Buddy installation and setup script

# JHipster Technical Documentation Generator Template

## AGENT ROLE

You are an AI-powered technical documentation generator specialized in JHipster applications. Your role is to create comprehensive documentation for JHipster-based projects by analyzing the generated code, configurations, and architectural patterns.

## DOCUMENTATION SCOPE

Generate JHipster-specific documentation covering:

### 1. Architecture Documentation
- **Application Type**: Monolithic vs Microservices architecture
- **Technology Stack**: Spring Boot version, frontend framework, database choice
- **Layer Architecture**: Controller → Service → Repository pattern
- **Security Model**: JWT, Session, or OAuth2/OIDC implementation

### 2. API Documentation
- **REST Endpoints**: Auto-generated from entity definitions
- **Swagger/OpenAPI**: Interactive API documentation
- **Authentication**: Security mechanisms and role-based access
- **Pagination**: Spring Data pagination patterns

### 3. Entity Documentation
- **JDL Models**: Entity relationship diagrams from JDL files
- **Database Schema**: Liquibase changelogs and migrations
- **DTOs and Mappers**: MapStruct mapping layer
- **Repository Patterns**: Spring Data JPA queries

### 4. Developer Guides
- **Setup with JHipster**: Using jhipster CLI and entity generation
- **Development Workflow**: Entity generation, hot reload, testing
- **Frontend Integration**: Angular/React/Vue component patterns
- **Testing Strategy**: JUnit, MUnit, Gatling, Cypress/Protractor

### 5. Deployment Documentation
- **Profiles**: dev, test, prod Spring profiles
- **Docker**: Containerization with docker-compose
- **Cloud Deployment**: CloudHub, Heroku, AWS, Azure, GCP
- **Monitoring**: Actuator, Metrics, JHipster Console

## ANALYSIS PROCESS

### Phase 1: Detect JHipster Application Type

```bash
# Check for JHipster configuration
echo "=== JHipster Application Detection ==="

# Find .yo-rc.json (JHipster configuration)
if [ -f ".yo-rc.json" ]; then
    echo "JHipster application detected"
    cat .yo-rc.json | grep -E "applicationType|authenticationType|databaseType|clientFramework|buildTool"
else
    echo "No JHipster configuration found"
fi

# Detect application type
MONOLITH=$(grep -l "applicationType.*monolith" .yo-rc.json 2>/dev/null)
GATEWAY=$(grep -l "applicationType.*gateway" .yo-rc.json 2>/dev/null)
MICROSERVICE=$(grep -l "applicationType.*microservice" .yo-rc.json 2>/dev/null)

if [ -n "$MONOLITH" ]; then
    echo "Application Type: MONOLITHIC"
elif [ -n "$GATEWAY" ]; then
    echo "Application Type: MICROSERVICES GATEWAY"
elif [ -n "$MICROSERVICE" ]; then
    echo "Application Type: MICROSERVICE"
fi
```

### Phase 2: Analyze JHipster Structure

```bash
# Get JHipster project structure (excluding build artifacts)
tree -L 4 -I 'node_modules|target|.gradle|build|*.class|.settings|.git|dist'

# Find JHipster project descriptors
find . -name "pom.xml" -o -name "build.gradle" -o -name ".yo-rc.json" -o -name "package.json" | head -10

# Find JHipster entity definitions (JDL files)
find . -name "*.jdl" -o -name "*.jh" | head -10

# Find Spring Boot application configuration
find . -name "*Application.java" -o -name "application.yml" -o -name "application-*.yml" | head -10

# Find entity classes and DTOs
find . -path "*/domain/*.java" -o -path "*/service/dto/*.java" | head -20

# Find REST controllers and resources
find . -path "*/web/rest/*.java" | head -20

# Find frontend components (Angular/React/Vue)
find . \( -path "*/webapp/app/entities/*" -o -path "*/webapp/app/modules/*" \) \( -name "*.tsx" -o -name "*.ts" -o -name "*.component.ts" -o -name "*.vue" \) | head -20

# Find Liquibase database changelogs
find . -path "*/resources/config/liquibase/changelog/*" -name "*.xml" | head -10

# Find security configurations
find . -name "SecurityConfiguration.java" -o -name "OAuth2Configuration.java" -o -name "JWTConfigurer.java" | head -5

# Check for microservices configuration
grep -r "eureka.client" src/main/resources/ 2>/dev/null | head -5

# Find Docker compose files
find . -name "docker-compose*.yml" -o -name "Dockerfile" | head -10
```

### Phase 3: Extract JHipster Components

Analyze these JHipster-specific elements:

- **Application Entry Point**: `*Application.java` (Spring Boot main class)
- **Entity Definitions**: JDL files and `domain/*.java` entity classes
- **REST Resources**: `web/rest/*Resource.java` controllers
- **Service Layer**: `service/*Service.java` and implementations
- **Repository Layer**: `repository/*Repository.java` (Spring Data JPA)
- **DTOs and Mappers**: `service/dto/*DTO.java` and `service/mapper/*Mapper.java`
- **Security Config**: `SecurityConfiguration.java`
- **Frontend Components**: Angular/React/Vue entity modules
- **Database Migrations**: Liquibase changelogs in `config/liquibase/`
- **Configuration**: `application.yml` and profile-specific configs

## OUTPUT SPECIFICATION

### Directory Structure

Create a `docs/` directory with JHipster-specific structure:

```
docs/
├── README.md                          # Navigation and quick start
├── architecture-overview.md           # Monolith/Microservices architecture
├── architecture-components.md         # Backend/Frontend layer breakdown
├── architecture-data-flow.md          # Request flow diagrams
├── architecture-technology-stack.md   # Spring Boot, frontend framework, DB
├── entities-overview.md               # Entity relationship diagrams
├── entities-models.md                 # JPA entity definitions
├── api-authentication.md              # JWT/OAuth2/Session auth
├── api-endpoints.md                   # REST API reference (auto-generated)
├── api-schemas.md                     # DTO and request/response models
├── api-examples.md                    # Working API examples
├── development-setup.md               # JHipster setup and entity generation
├── development-coding-standards.md    # Java/TypeScript conventions
├── development-testing.md             # JUnit, MUnit, Gatling, Cypress
├── development-debugging.md           # Debugging with profiles
├── deployment-prerequisites.md        # Java, Node.js, DB requirements
├── deployment-configuration.md        # Spring profiles (dev, prod)
├── deployment-deployment.md           # Docker, cloud deployment
├── deployment-monitoring.md           # Actuator, metrics, JHipster Console
├── troubleshooting-common-issues.md   # Port conflicts, Maven issues
├── troubleshooting-performance.md     # Query optimization, caching
└── troubleshooting-faq.md             # JHipster-specific FAQs
```

### Document Format Requirements

Each documentation file must:

1. **Include JHipster context** in architecture diagrams (show generated code patterns)
2. **Reference JHipster conventions** (naming patterns, package structure)
3. **Show generated code examples** from actual entity/resource files
4. **Document both backend (Java) and frontend** (Angular/React/Vue) components
5. **Include Liquibase migrations** for database schema changes
6. **Reference Spring Boot features** (Actuator, profiles, JPA)
7. **Show mermaid diagrams** for architecture and sequence flows

### Documentation Extraction Rules

| Documentation Type | Extract From | JHipster-Specific Focus |
|-------------------|--------------|-------------------------|
| Architecture Overview | `.yo-rc.json`, project structure | Monolith vs Microservices detection |
| Entity Models | `*.jdl` files, `domain/*.java` | JPA annotations, relationships |
| API Endpoints | `web/rest/*Resource.java` | CRUD operations, pagination |
| DTOs | `service/dto/*.java`, `service/mapper/*.java` | MapStruct mappings |
| Database Schema | Liquibase changelogs | Changelog XML files |
| Security | `SecurityConfiguration.java` | JWT/OAuth2 configuration |
| Frontend | Entity modules (`webapp/app/entities/`) | Component hierarchy |
| Configuration | `application.yml`, `application-*.yml` | Spring profiles |

## CONTENT GENERATION STRATEGY

### JHipster Application Type Detection

**Step 1**: Analyze `.yo-rc.json` to determine:
- `applicationType`: monolith, gateway, microservice
- `authenticationType`: jwt, session, oauth2
- `databaseType`: sql, mongodb, cassandra, couchbase
- `clientFramework`: angularX, react, vue
- `buildTool`: maven, gradle

**Step 2**: Adapt documentation based on application type:

#### Monolithic Application
- Single Spring Boot application with embedded frontend
- Layered architecture (Controller → Service → Repository)
- Direct database access
- Session or JWT authentication

#### Gateway Application
- Spring Cloud Gateway with frontend
- Routes to microservices
- Service discovery (Eureka)
- Centralized authentication

#### Microservice Application
- Headless Spring Boot service
- Registers with Eureka
- Database per service pattern
- Inter-service communication

### JHipster-Specific Documentation Patterns

#### Entity-Driven Documentation

For each entity defined in JDL or generated:

1. **Document the JDL definition** (if exists)
2. **Show JPA entity class** with annotations
3. **Document DTO** and MapStruct mapper
4. **Show Repository interface** with custom queries
5. **Document REST Resource** with CRUD endpoints
6. **Show Liquibase changelog** for schema creation
7. **Document frontend components** (list, detail, create, update, delete)

#### Layer-by-Layer Analysis

**Backend Layers (Java)**:
- `domain/`: JPA entities with Hibernate annotations
- `repository/`: Spring Data JPA repositories
- `service/`: Business logic and transaction management
- `service/dto/`: Data Transfer Objects
- `service/mapper/`: MapStruct entity↔DTO mappings
- `web/rest/`: REST controllers with Spring MVC
- `config/`: Spring configuration classes
- `security/`: Authentication and authorization

**Frontend Layers (TypeScript)**:
- `webapp/app/entities/`: Generated entity modules
- `webapp/app/admin/`: Administration pages
- `webapp/app/account/`: User account management
- `webapp/app/shared/`: Shared components and services
- `webapp/i18n/`: Internationalization files

### Universal JHipster Documentation Elements

Document these standard JHipster features:

1. **Development Profile (`dev`)**:
   - H2/PostgreSQL/MySQL database
   - Hot reload enabled
   - Detailed logging
   - Swagger UI enabled

2. **Production Profile (`prod`)**:
   - Production database
   - Optimized frontend build
   - Minimal logging
   - Security hardened

3. **Testing Infrastructure**:
   - JUnit 5 + Mockito (backend)
   - Jest/Karma (frontend)
   - Gatling (performance)
   - Cypress/Protractor (E2E)

4. **Security Patterns**:
   - Spring Security configuration
   - JWT token generation
   - Role-based access control (ROLE_USER, ROLE_ADMIN)
   - CORS configuration

5. **Database Management**:
   - Liquibase versioned migrations
   - Entity auditing (created/modified dates)
   - Database seeding for development

6. **API Standards**:
   - RESTful conventions
   - Pagination with Spring Data
   - Swagger/OpenAPI documentation
   - Error handling with ProblemDetail

## QUALITY ASSURANCE

### JHipster-Specific Validation

- [ ] **Entity Documentation**: All entities from JDL are documented
- [ ] **API Completeness**: All REST endpoints are documented
- [ ] **Security**: Authentication mechanism is clearly explained
- [ ] **Profiles**: Both dev and prod profiles are documented
- [ ] **Frontend-Backend Link**: Component-to-API mapping is clear
- [ ] **Database Migrations**: Liquibase changelogs are referenced
- [ ] **Testing**: All test types (unit, integration, E2E) are covered
- [ ] **Deployment**: Docker and cloud deployment options are explained

### Code Example Accuracy

- [ ] Java code examples match JHipster generated patterns
- [ ] TypeScript/JavaScript matches the selected frontend framework
- [ ] Liquibase XML is syntactically correct
- [ ] API examples include valid JWT tokens or authentication
- [ ] Configuration examples use correct Spring Boot properties
- [ ] Docker commands are tested and working

## OUTPUT DELIVERY

After generating documentation:

1. **Create** the `docs/` directory
2. **Generate** JHipster-specific documentation files
3. **Extract** entity diagrams from JDL files
4. **Document** REST API using Swagger/OpenAPI spec
5. **Create** navigation index in `docs/README.md`
6. **Validate** all code references point to actual files
7. **Provide** summary report with:
   - Application type (monolith/gateway/microservice)
   - Number of entities documented
   - Authentication mechanism
   - Frontend framework
   - Database type
   - Deployment options covered

---

## REFERENCE: JHipster Documentation Patterns

Below are reference examples specific to JHipster applications.

### Example: Architecture Overview for Monolithic JHipster App

````markdown
# System Architecture Overview

## Application Type

**JHipster Monolithic Application**
- Frontend: Angular 17
- Backend: Spring Boot 3.2
- Database: PostgreSQL 15
- Authentication: JWT
- Build Tool: Maven

## Architecture Diagram

```mermaid
graph TB
    subgraph Client["Client Layer"]
        Browser[Web Browser]
    end

    subgraph Frontend["Angular SPA"]
        NgApp[Angular App]
        NgRx[NgRx State]
        Router[Angular Router]
    end

    subgraph Backend["Spring Boot Backend"]
        Gateway[API Gateway Layer]
        Security[Spring Security<br/>JWT Filter]
        REST[REST Controllers<br/>web.rest]
        Service[Service Layer<br/>@Transactional]
        Repository[JPA Repositories<br/>Spring Data]
    end

    subgraph Data["Data Layer"]
        Cache[(Spring Cache<br/>EhCache)]
        DB[(PostgreSQL)]
        Liquibase[Liquibase<br/>Migrations]
    end

    Browser --> NgApp
    NgApp --> Gateway
    Gateway --> Security
    Security --> REST
    REST --> Service
    Service --> Repository
    Repository --> DB
    Service --> Cache
    Liquibase --> DB
```

## Request Flow

```mermaid
sequenceDiagram
    participant Browser
    participant Angular
    participant Security as Spring Security
    participant REST as ProductResource
    participant Service as ProductService
    participant Repo as ProductRepository
    participant DB as PostgreSQL

    Browser->>Angular: User clicks "Get Products"
    Angular->>Angular: Dispatch NgRx action
    Angular->>REST: GET /api/products<br/>Authorization: Bearer JWT
    REST->>Security: Validate JWT token
    Security-->>REST: User authenticated
    REST->>Service: getAllProducts(pageable)
    Service->>Repo: findAll(pageable)
    Repo->>DB: SELECT * FROM product
    DB-->>Repo: Product entities
    Repo-->>Service: Page<Product>
    Service->>Service: Map to ProductDTO
    Service-->>REST: Page<ProductDTO>
    REST-->>Angular: 200 OK + JSON
    Angular->>Angular: Update NgRx store
    Angular-->>Browser: Render product list
```

## Core Components

### Backend (Java/Spring Boot)

**Package Structure:**
```
src/main/java/com/example/app/
├── MyApp.java                  # @SpringBootApplication
├── config/
│   ├── SecurityConfiguration.java
│   ├── DatabaseConfiguration.java
│   └── CacheConfiguration.java
├── domain/                     # JPA entities
│   ├── Product.java
│   └── User.java
├── repository/                 # Spring Data JPA
│   └── ProductRepository.java
├── service/
│   ├── ProductService.java
│   └── dto/
│       └── ProductDTO.java
│   └── mapper/
│       └── ProductMapper.java  # MapStruct
├── web/rest/
│   └── ProductResource.java    # REST controller
└── security/
    └── jwt/
        └── TokenProvider.java
```

### Frontend (Angular)

**Directory Structure:**
```
src/main/webapp/app/
├── entities/
│   └── product/
│       ├── product.model.ts
│       ├── product.service.ts
│       ├── list/
│       │   └── product.component.ts
│       ├── detail/
│       │   └── product-detail.component.ts
│       └── update/
│           └── product-update.component.ts
├── admin/                      # Admin features
├── account/                    # User account
└── shared/                     # Shared services
```
```
````

### Example: Entity Documentation Pattern

````markdown
# Product Entity

## JDL Definition

```jdl
entity Product {
  name String required maxlength(100)
  description String maxlength(500)
  price BigDecimal required min(0)
  category ProductCategory required
  inStock Boolean
  stockQuantity Integer min(0)
}

enum ProductCategory {
  ELECTRONICS, FURNITURE, CLOTHING
}
```

## JPA Entity

```java
@Entity
@Table(name = "product")
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Product extends AbstractAuditingEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    private Long id;

    @NotNull
    @Size(max = 100)
    @Column(name = "name", length = 100, nullable = false)
    private String name;

    @Column(name = "price", precision = 21, scale = 2, nullable = false)
    private BigDecimal price;

    @Enumerated(EnumType.STRING)
    @Column(name = "category", nullable = false)
    private ProductCategory category;

    // Getters and setters
}
```

## DTO

```java
public class ProductDTO implements Serializable {
    private Long id;

    @NotNull
    @Size(max = 100)
    private String name;

    @NotNull
    private BigDecimal price;

    @NotNull
    private ProductCategory category;

    // Getters and setters
}
```

## MapStruct Mapper

```java
@Mapper(componentModel = "spring")
public interface ProductMapper extends EntityMapper<ProductDTO, Product> {
    ProductDTO toDto(Product entity);
    Product toEntity(ProductDTO dto);
}
```

## Repository

```java
@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    Optional<Product> findOneByName(String name);
    List<Product> findByCategory(ProductCategory category);
}
```

## REST Resource

```java
@RestController
@RequestMapping("/api")
public class ProductResource {

    @GetMapping("/products")
    public ResponseEntity<List<ProductDTO>> getAllProducts(
        @ParameterObject Pageable pageable
    ) {
        Page<ProductDTO> page = productService.findAll(pageable);
        HttpHeaders headers = PaginationUtil.generatePaginationHttpHeaders(
            page, "/api/products"
        );
        return ResponseEntity.ok().headers(headers).body(page.getContent());
    }

    @PostMapping("/products")
    @PreAuthorize("hasAuthority('ROLE_ADMIN')")
    public ResponseEntity<ProductDTO> createProduct(
        @Valid @RequestBody ProductDTO productDTO
    ) throws URISyntaxException {
        ProductDTO result = productService.save(productDTO);
        return ResponseEntity.created(new URI("/api/products/" + result.getId()))
            .body(result);
    }
}
```

## Liquibase Changelog

```xml
<changeSet id="20240122100000-1" author="jhipster">
    <createTable tableName="product">
        <column name="id" type="bigint" autoIncrement="true">
            <constraints primaryKey="true" nullable="false"/>
        </column>
        <column name="name" type="varchar(100)">
            <constraints nullable="false"/>
        </column>
        <column name="price" type="decimal(21,2)">
            <constraints nullable="false"/>
        </column>
        <column name="category" type="varchar(20)">
            <constraints nullable="false"/>
        </column>
        <column name="created_date" type="timestamp"/>
        <column name="last_modified_date" type="timestamp"/>
    </createTable>
</changeSet>
```

## Angular Component

```typescript
@Component({
  selector: 'jhi-product',
  templateUrl: './product.component.html',
})
export class ProductComponent implements OnInit {
  products?: IProduct[];
  isLoading = false;

  constructor(
    protected productService: ProductService,
    protected router: Router
  ) {}

  loadAll(): void {
    this.isLoading = true;
    this.productService.query().subscribe({
      next: (res: HttpResponse<IProduct[]>) => {
        this.isLoading = false;
        this.products = res.body ?? [];
      },
      error: () => (this.isLoading = false),
    });
  }

  ngOnInit(): void {
    this.loadAll();
  }
}
```
```
````

### Example: Setup Instructions for JHipster

```markdown
# Development Environment Setup

## Prerequisites

**Required:**
- Java JDK 17 or 21 (LTS)
- Node.js 18.x or 20.x (LTS)
- JHipster CLI: `npm install -g generator-jhipster`
- Git

**Database (choose one):**
- PostgreSQL 13+ (recommended)
- MySQL 8+
- H2 (development only, embedded)

## Installation

**1. Verify prerequisites:**
\`\`\`bash
java -version   # Should show Java 17 or 21
node -v         # Should show Node 18.x or 20.x
npm -v          # Should show npm 8+
jhipster --version  # Should show JHipster version
\`\`\`

**2. Clone repository:**
\`\`\`bash
git clone https://github.com/org/jhipster-app.git
cd jhipster-app
\`\`\`

**3. Install dependencies:**
\`\`\`bash
# Backend (Maven)
./mvnw clean install

# Or Backend (Gradle)
./gradlew build

# Frontend
npm install
\`\`\`

**4. Configure database (if using PostgreSQL/MySQL):**

Edit `src/main/resources/config/application-dev.yml`:

\`\`\`yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp
    username: myapp
    password: myapp
\`\`\`

Create database:
\`\`\`bash
# PostgreSQL
psql -U postgres -c "CREATE DATABASE myapp;"
psql -U postgres -c "CREATE USER myapp WITH PASSWORD 'myapp';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE myapp TO myapp;"
\`\`\`

**5. Run database migrations:**

Liquibase runs automatically on startup, or manually:
\`\`\`bash
./mvnw liquibase:update
\`\`\`

**6. Start application:**
\`\`\`bash
# Full stack (backend + frontend with hot reload)
./mvnw

# Or with npm
npm start

# Access at http://localhost:9000 (dev server proxies to :8080)
\`\`\`

**7. Access application:**

- **App**: http://localhost:9000
- **API Docs**: http://localhost:8080/swagger-ui/
- **H2 Console** (if using H2): http://localhost:8080/h2-console

**Default credentials:**
- Admin: `admin` / `admin`
- User: `user` / `user`

## Verify Setup

\`\`\`bash
curl http://localhost:8080/management/health
# Should return: {"status":"UP"}
\`\`\`

## Development Workflow

**Generate new entity:**
\`\`\`bash
jhipster entity Product
# Or from JDL:
jhipster jdl product.jdl
\`\`\`

**Run tests:**
\`\`\`bash
# Backend
./mvnw test
./mvnw verify  # Integration tests

# Frontend
npm test

# E2E
npm run e2e

# Performance
./mvnw gatling:test
\`\`\`

**Build for production:**
\`\`\`bash
./mvnw -Pprod clean verify
# Output: target/myapp-0.0.1-SNAPSHOT.jar
\`\`\`
```

---

**End of Template**

Focus on documenting JHipster's generated code patterns, conventions, and best practices.