mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
Add comprehensive documentation templates for API, folder navigation, module README, project architecture, examples, and project-level README
- Introduced a unified API documentation template covering both Code API and HTTP API sections. - Created a folder navigation documentation template for directories containing subdirectories. - Developed a module README documentation template focusing on module purpose, usage, and dependencies. - Added a project architecture documentation template synthesizing module information and system design. - Implemented a project examples documentation template showcasing practical usage scenarios. - Established a project-level documentation template outlining project overview, architecture, and navigation.
This commit is contained in:
catlog22
@@ -1,240 +0,0 @@
|
||||
# API-Level Documentation Template
|
||||
|
||||
Generate comprehensive API documentation following this structure:
|
||||
|
||||
## Overview
|
||||
[Brief description of the API's purpose and capabilities]
|
||||
|
||||
## Authentication
|
||||
### Authentication Method
|
||||
[e.g., JWT, OAuth2, API Keys]
|
||||
|
||||
### Obtaining Credentials
|
||||
```bash
|
||||
# Example authentication flow
|
||||
```
|
||||
|
||||
### Using Credentials
|
||||
```http
|
||||
GET /api/resource HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Base URL
|
||||
```
|
||||
Production: https://api.example.com/v1
|
||||
Staging: https://staging.api.example.com/v1
|
||||
```
|
||||
|
||||
## Common Response Codes
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 200 | Success |
|
||||
| 201 | Created |
|
||||
| 400 | Bad Request |
|
||||
| 401 | Unauthorized |
|
||||
| 403 | Forbidden |
|
||||
| 404 | Not Found |
|
||||
| 500 | Internal Server Error |
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Resource: Users
|
||||
|
||||
#### GET /users
|
||||
**Description**: Retrieves a paginated list of users.
|
||||
|
||||
**Query Parameters**:
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `limit` | number | No | Number of results (default: 20, max: 100) |
|
||||
| `offset` | number | No | Pagination offset (default: 0) |
|
||||
| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (401 Unauthorized)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or expired token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### GET /users/:id
|
||||
**Description**: Retrieves a single user by ID.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users/123 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### POST /users
|
||||
**Description**: Creates a new user.
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"name": "Jane Smith",
|
||||
"email": "jane@example.com",
|
||||
"password": "securePassword123"
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Rules**:
|
||||
- `name`: Required, 2-100 characters
|
||||
- `email`: Required, valid email format, must be unique
|
||||
- `password`: Required, minimum 8 characters
|
||||
|
||||
**Response (201 Created)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"name": "Jane Smith",
|
||||
"email": "jane@example.com",
|
||||
"created_at": "2024-01-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (400 Bad Request)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "Validation failed",
|
||||
"details": [
|
||||
{
|
||||
"field": "email",
|
||||
"message": "Email already exists"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### PUT /users/:id
|
||||
**Description**: Updates an existing user.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"name": "Jane Doe",
|
||||
"email": "jane.doe@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"name": "Jane Doe",
|
||||
"email": "jane.doe@example.com",
|
||||
"updated_at": "2024-01-21T09:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### DELETE /users/:id
|
||||
**Description**: Deletes a user.
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | User ID |
|
||||
|
||||
**Response (204 No Content)**:
|
||||
[Empty response body]
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
- **Limit**: 1000 requests per hour per API key
|
||||
- **Headers**:
|
||||
- `X-RateLimit-Limit`: Total requests allowed
|
||||
- `X-RateLimit-Remaining`: Requests remaining
|
||||
- `X-RateLimit-Reset`: Unix timestamp when limit resets
|
||||
|
||||
---
|
||||
|
||||
## SDKs and Client Libraries
|
||||
- [JavaScript/TypeScript SDK](./sdks/javascript.md)
|
||||
- [Python SDK](./sdks/python.md)
|
||||
|
||||
---
|
||||
|
||||
## Webhooks
|
||||
[Description of webhook system if applicable]
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
### v1.1.0 (2024-01-20)
|
||||
- Added user sorting functionality
|
||||
- Improved error messages
|
||||
|
||||
### v1.0.0 (2024-01-01)
|
||||
- Initial API release
|
||||
|
||||
---
|
||||
|
||||
**API Version**: 1.1.0
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Support**: api-support@example.com
|
||||
337
.claude/workflows/cli-templates/prompts/documentation/api.txt
Normal file
337
.claude/workflows/cli-templates/prompts/documentation/api.txt
Normal file
@@ -0,0 +1,337 @@
|
||||
# Unified API Documentation Template
|
||||
|
||||
Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
|
||||
|
||||
---
|
||||
|
||||
## Part A: Code API (For Libraries, Modules, SDKs)
|
||||
|
||||
**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.
|
||||
|
||||
**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.
|
||||
|
||||
### 1. Exported Functions
|
||||
|
||||
For each exported function, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of what the function does
|
||||
* @param paramName - Parameter type and description
|
||||
* @returns Return type and description
|
||||
* @throws ErrorType - When this error occurs
|
||||
*/
|
||||
export function functionName(paramName: ParamType): ReturnType;
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Authenticates a user with email and password
|
||||
* @param credentials - User email and password
|
||||
* @returns Authentication token and user info
|
||||
* @throws AuthenticationError - When credentials are invalid
|
||||
*/
|
||||
export function authenticate(credentials: Credentials): Promise<AuthResult>;
|
||||
```
|
||||
|
||||
### 2. Exported Classes
|
||||
|
||||
For each exported class, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of the class purpose
|
||||
*/
|
||||
export class ClassName {
|
||||
constructor(param: Type);
|
||||
|
||||
// Public properties
|
||||
propertyName: Type;
|
||||
|
||||
// Public methods
|
||||
methodName(param: Type): ReturnType;
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Manages user session lifecycle and token refresh
|
||||
*/
|
||||
export class SessionManager {
|
||||
constructor(config: SessionConfig);
|
||||
|
||||
// Current session state
|
||||
isActive: boolean;
|
||||
|
||||
// Refresh the session token
|
||||
refresh(): Promise<void>;
|
||||
|
||||
// Terminate the session
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Exported Interfaces
|
||||
|
||||
For each exported interface, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this interface represents
|
||||
*/
|
||||
export interface InterfaceName {
|
||||
field1: Type; // Field description
|
||||
field2: Type; // Field description
|
||||
method?: (param: Type) => ReturnType; // Optional method
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Type Definitions
|
||||
|
||||
For each exported type, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this type represents
|
||||
*/
|
||||
export type TypeName = string | number | CustomType;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part B: HTTP API (For Web Services, REST APIs, GraphQL)
|
||||
|
||||
**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.
|
||||
|
||||
**Omit this section if**: This is a library/SDK with no HTTP interface.
|
||||
|
||||
### 1. Overview
|
||||
|
||||
[Brief description of the API's purpose and capabilities]
|
||||
|
||||
**Base URL**:
|
||||
```
|
||||
Production: https://api.example.com/v1
|
||||
Staging: https://staging.api.example.com/v1
|
||||
Development: http://localhost:3000/api/v1
|
||||
```
|
||||
|
||||
### 2. Authentication
|
||||
|
||||
#### Authentication Method
|
||||
[e.g., JWT Bearer Token, OAuth2, API Keys]
|
||||
|
||||
#### Obtaining Credentials
|
||||
```bash
|
||||
# Example: Login to get token
|
||||
curl -X POST https://api.example.com/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com", "password": "password"}'
|
||||
```
|
||||
|
||||
#### Using Credentials
|
||||
```http
|
||||
GET /api/resource HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 3. Common Response Codes
|
||||
|
||||
| Code | Description | Common Causes |
|
||||
|------|-------------|---------------|
|
||||
| 200 | Success | Request completed successfully |
|
||||
| 201 | Created | Resource created successfully |
|
||||
| 400 | Bad Request | Invalid request body or parameters |
|
||||
| 401 | Unauthorized | Missing or invalid authentication |
|
||||
| 403 | Forbidden | Authenticated but not authorized |
|
||||
| 404 | Not Found | Resource does not exist |
|
||||
| 429 | Too Many Requests | Rate limit exceeded |
|
||||
| 500 | Internal Server Error | Server-side error |
|
||||
|
||||
### 4. Endpoints
|
||||
|
||||
#### Resource: [Resource Name, e.g., Users]
|
||||
|
||||
##### GET /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Query Parameters**:
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| `limit` | number | No | Number of results | 20 |
|
||||
| `offset` | number | No | Pagination offset | 0 |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users?limit=10&offset=0 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (401 Unauthorized)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or expired token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### POST /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": 123
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Rules**:
|
||||
- `field1`: Required, 2-100 characters
|
||||
- `field2`: Required, positive integer
|
||||
|
||||
**Response (201 Created)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "value",
|
||||
"field2": 123,
|
||||
"created_at": "2024-01-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### PUT /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"field1": "new value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "new value",
|
||||
"updated_at": "2024-01-21T09:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### DELETE /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Response (204 No Content)**:
|
||||
[Empty response body]
|
||||
|
||||
---
|
||||
|
||||
### 5. Rate Limiting
|
||||
|
||||
- **Limit**: 1000 requests per hour per API key
|
||||
- **Headers**:
|
||||
- `X-RateLimit-Limit`: Total requests allowed
|
||||
- `X-RateLimit-Remaining`: Requests remaining
|
||||
- `X-RateLimit-Reset`: Unix timestamp when limit resets
|
||||
|
||||
**Example Response Headers**:
|
||||
```http
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 847
|
||||
X-RateLimit-Reset: 1640000000
|
||||
```
|
||||
|
||||
### 6. Webhooks (Optional)
|
||||
|
||||
[Description of webhook system if applicable]
|
||||
|
||||
**Webhook Events**:
|
||||
- `resource.created` - Triggered when a new resource is created
|
||||
- `resource.updated` - Triggered when a resource is updated
|
||||
- `resource.deleted` - Triggered when a resource is deleted
|
||||
|
||||
**Webhook Payload Example**:
|
||||
```json
|
||||
{
|
||||
"event": "resource.created",
|
||||
"timestamp": "2024-01-20T12:00:00Z",
|
||||
"data": {
|
||||
"id": 124,
|
||||
"field1": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
|
||||
2. **Signatures only in Part A** - No implementation code in Code API section
|
||||
3. **Complete examples in Part B** - All HTTP examples should be runnable
|
||||
4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
|
||||
5. **Brief descriptions** - One line per item is sufficient for Code API
|
||||
6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
|
||||
7. **Alphabetical order** - Sort items within each section for easy lookup
|
||||
8. **Public API only** - Do not document internal/private exports or endpoints
|
||||
|
||||
---
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### For Module-Level API.md (Code API)
|
||||
**Use**: Part A only
|
||||
**Location**: `modules/[module-name]/API.md`
|
||||
**Focus**: Exported functions, classes, interfaces
|
||||
|
||||
### For Project-Level HTTP API Documentation
|
||||
**Use**: Part B only
|
||||
**Location**: `.workflow/docs/api/README.md`
|
||||
**Focus**: REST/GraphQL endpoints, authentication
|
||||
|
||||
### For Full-Stack Projects (Both Code and HTTP APIs)
|
||||
**Use**: Both Part A and Part B
|
||||
**Organization**:
|
||||
- Part A for SDK/client library APIs
|
||||
- Part B for HTTP endpoints
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**API Version**: [Version number]
|
||||
**Module/Service Path**: [Auto-fill with actual path]
|
||||
@@ -0,0 +1,68 @@
|
||||
# Folder Navigation Documentation Template
|
||||
|
||||
Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Overview
|
||||
|
||||
Brief description of what this directory/category contains:
|
||||
|
||||
> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
|
||||
|
||||
### 2. Directory Structure
|
||||
|
||||
Provide a tree view of the subdirectories with brief descriptions:
|
||||
|
||||
```
|
||||
modules/
|
||||
├── auth/ - User authentication and authorization
|
||||
├── api/ - API route handlers and middleware
|
||||
├── database/ - Database connections and ORM models
|
||||
└── utils/ - Shared utility functions
|
||||
```
|
||||
|
||||
### 3. Module Quick Reference
|
||||
|
||||
Table format for quick scanning:
|
||||
|
||||
| Module | Purpose | Key Features |
|
||||
|--------|---------|--------------|
|
||||
| [auth](./auth/) | Authentication | JWT tokens, session management |
|
||||
| [api](./api/) | API routing | REST endpoints, validation |
|
||||
| [database](./database/) | Data layer | PostgreSQL, migrations |
|
||||
| [utils](./utils/) | Utilities | Logging, helpers |
|
||||
|
||||
### 4. How to Navigate
|
||||
|
||||
Guidance on which module to explore based on needs:
|
||||
|
||||
- **For authentication logic** → [auth module](./auth/)
|
||||
- **For API endpoints** → [api module](./api/)
|
||||
- **For database queries** → [database module](./database/)
|
||||
- **For helper functions** → [utils module](./utils/)
|
||||
|
||||
### 5. Module Relationships (Optional)
|
||||
|
||||
If modules have significant dependencies, show them:
|
||||
|
||||
```
|
||||
api → auth (uses for authentication)
|
||||
api → database (uses for data access)
|
||||
auth → database (uses for user storage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Keep it brief** - This is an index, not detailed documentation
|
||||
2. **One-line descriptions** - Each module gets a concise purpose statement
|
||||
3. **Scannable format** - Use tables and lists for quick navigation
|
||||
4. **Link to submodules** - Every module mentioned should link to its README
|
||||
5. **No code examples** - This is navigation only
|
||||
|
||||
---
|
||||
|
||||
**Directory Path**: [Auto-fill with actual directory path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
@@ -1,91 +0,0 @@
|
||||
# Module-Level Documentation Template
|
||||
|
||||
Generate detailed module documentation following this structure:
|
||||
|
||||
## 1. Purpose and Responsibilities
|
||||
[What this module does, its boundaries, and its role in the larger system]
|
||||
|
||||
## 2. Internal Architecture
|
||||
- **Key Components**:
|
||||
- [Component 1]: [Description and responsibility]
|
||||
- [Component 2]: [Description and responsibility]
|
||||
- **Data Flow**: [How data moves through the module, with diagrams if applicable]
|
||||
- **Core Logic**: [Explanation of the main business logic and algorithms]
|
||||
- **State Management**: [How state is managed within the module]
|
||||
|
||||
## 3. Public API / Interface
|
||||
### Exported Functions
|
||||
```typescript
|
||||
/**
|
||||
* Function description
|
||||
* @param param1 - Parameter description
|
||||
* @returns Return value description
|
||||
*/
|
||||
export function exampleFunction(param1: Type): ReturnType;
|
||||
```
|
||||
|
||||
### Exported Classes
|
||||
```typescript
|
||||
/**
|
||||
* Class description
|
||||
*/
|
||||
export class ExampleClass {
|
||||
// Public methods and properties
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
```typescript
|
||||
import { exampleFunction } from './module';
|
||||
|
||||
// Example 1: Basic usage
|
||||
const result = exampleFunction(input);
|
||||
|
||||
// Example 2: Advanced usage
|
||||
// ...
|
||||
```
|
||||
|
||||
## 4. Dependencies
|
||||
### Internal Dependencies
|
||||
- **[Module A]**: [Why this dependency exists, what it provides]
|
||||
- **[Module B]**: [Purpose of dependency]
|
||||
|
||||
### External Dependencies
|
||||
- **[Library 1]** (`version`): [Purpose and usage]
|
||||
- **[Library 2]** (`version`): [Purpose and usage]
|
||||
|
||||
## 5. Configuration
|
||||
### Environment Variables
|
||||
- `ENV_VAR_NAME`: [Description, default value]
|
||||
|
||||
### Configuration Options
|
||||
```typescript
|
||||
interface ModuleConfig {
|
||||
option1: Type; // Description
|
||||
option2: Type; // Description
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Testing
|
||||
### Running Tests
|
||||
```bash
|
||||
npm test -- module-name
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
- Unit tests: [Coverage percentage or key test files]
|
||||
- Integration tests: [Coverage or test scenarios]
|
||||
|
||||
## 7. Common Use Cases
|
||||
1. **Use Case 1**: [Description and code example]
|
||||
2. **Use Case 2**: [Description and code example]
|
||||
|
||||
## 8. Troubleshooting
|
||||
### Common Issues
|
||||
- **Issue 1**: [Description and solution]
|
||||
- **Issue 2**: [Description and solution]
|
||||
|
||||
---
|
||||
**Module Path**: [File path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**Owner/Maintainer**: [Team or individual]
|
||||
@@ -0,0 +1,98 @@
|
||||
# Module README Documentation Template
|
||||
|
||||
Generate comprehensive module documentation focused on understanding and usage. Explain WHAT the module does, WHY it exists, and HOW to use it. Do NOT duplicate API signatures (those belong in API.md).
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Purpose
|
||||
|
||||
**What**: Clearly state what this module is responsible for
|
||||
**Why**: Explain why this module exists and what problems it solves
|
||||
**Boundaries**: Define what is IN scope and OUT of scope
|
||||
|
||||
Example:
|
||||
> The `auth` module handles user authentication and authorization. It exists to centralize security logic and provide a consistent authentication interface across the application. It does NOT handle user profile management or session storage.
|
||||
|
||||
### 2. Core Concepts
|
||||
|
||||
List and explain key concepts, patterns, or abstractions used by this module:
|
||||
|
||||
- **Concept 1**: [Brief explanation of important concept]
|
||||
- **Concept 2**: [Another key concept users should understand]
|
||||
- **Pattern**: [Architectural pattern used, e.g., "Uses middleware pattern for request processing"]
|
||||
|
||||
### 3. Usage Scenarios
|
||||
|
||||
Provide 2-4 common use cases with code examples:
|
||||
|
||||
#### Scenario 1: [Common use case title]
|
||||
```typescript
|
||||
// Brief example showing how to use the module for this scenario
|
||||
import { functionName } from './module';
|
||||
|
||||
const result = functionName(input);
|
||||
```
|
||||
|
||||
#### Scenario 2: [Another common use case]
|
||||
```typescript
|
||||
// Another practical example
|
||||
```
|
||||
|
||||
### 4. Dependencies
|
||||
|
||||
#### Internal Dependencies
|
||||
List other project modules this module depends on and explain why:
|
||||
- **[Module Name]** - [Why this dependency exists and what it provides]
|
||||
|
||||
#### External Dependencies
|
||||
List third-party libraries and their purpose:
|
||||
- **[Library Name]** (`version`) - [What functionality it provides to this module]
|
||||
|
||||
### 5. Configuration
|
||||
|
||||
#### Environment Variables
|
||||
List any environment variables the module uses:
|
||||
- `ENV_VAR_NAME` - [Description, type, default value]
|
||||
|
||||
#### Configuration Options
|
||||
If the module accepts configuration objects:
|
||||
```typescript
|
||||
// Example configuration
|
||||
const config = {
|
||||
option1: value, // Description of option1
|
||||
option2: value, // Description of option2
|
||||
};
|
||||
```
|
||||
|
||||
### 6. Testing
|
||||
|
||||
Explain how to test code that uses this module:
|
||||
```bash
|
||||
# Command to run tests for this module
|
||||
npm test -- path/to/module
|
||||
```
|
||||
|
||||
**Test Coverage**: [Brief note on what's tested]
|
||||
|
||||
### 7. Common Issues
|
||||
|
||||
List 2-3 common problems and their solutions:
|
||||
|
||||
#### Issue: [Common problem description]
|
||||
**Solution**: [How to resolve it]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **No API duplication** - Refer to API.md for signatures
|
||||
2. **Focus on understanding** - Explain concepts, not just code
|
||||
3. **Practical examples** - Show real usage, not trivial cases
|
||||
4. **Clear dependencies** - Help readers understand module relationships
|
||||
5. **Concise** - Each section should be scannable and to-the-point
|
||||
|
||||
---
|
||||
|
||||
**Module Path**: [Auto-fill with actual module path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**: [Link to API.md for interface details]
|
||||
@@ -0,0 +1,167 @@
|
||||
# Project Architecture Documentation Template
|
||||
|
||||
Generate comprehensive architecture documentation that synthesizes information from all module documents. Focus on system-level design, module relationships, and aggregated API overview. This document should be created AFTER all module documentation is complete.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. System Overview
|
||||
|
||||
High-level description of the system architecture:
|
||||
|
||||
**Architectural Style**: [e.g., Layered, Microservices, Event-Driven, Hexagonal]
|
||||
|
||||
**Core Principles**:
|
||||
- [Principle 1, e.g., "Separation of concerns"]
|
||||
- [Principle 2, e.g., "Dependency inversion"]
|
||||
- [Principle 3, e.g., "Single responsibility"]
|
||||
|
||||
**Technology Stack**:
|
||||
- **Languages**: [Primary programming languages]
|
||||
- **Frameworks**: [Key frameworks]
|
||||
- **Databases**: [Data storage solutions]
|
||||
- **Infrastructure**: [Deployment, hosting, CI/CD]
|
||||
|
||||
### 2. System Structure
|
||||
|
||||
Visual representation of the system structure using text diagrams:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (API Routes, Controllers) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Business Logic Layer │
|
||||
│ (Modules: auth, orders, payments) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Data Access Layer │
|
||||
│ (Database, ORM, Repositories) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. Module Map
|
||||
|
||||
Comprehensive list of all modules with their responsibilities:
|
||||
|
||||
| Module | Layer | Responsibility | Dependencies |
|
||||
|--------|-------|----------------|--------------|
|
||||
| `auth` | Business | Authentication & authorization | database, utils |
|
||||
| `api` | Application | HTTP routing & validation | auth, orders |
|
||||
| `database` | Data | Data persistence | - |
|
||||
| `utils` | Infrastructure | Shared utilities | - |
|
||||
|
||||
### 4. Module Interactions
|
||||
|
||||
Describe key interaction patterns between modules:
|
||||
|
||||
#### Data Flow Example: User Authentication
|
||||
```
|
||||
1. Client → api/login endpoint
|
||||
2. api → auth.authenticateUser()
|
||||
3. auth → database.findUser()
|
||||
4. database → PostgreSQL
|
||||
5. auth → JWT token generation
|
||||
6. api → Response with token
|
||||
```
|
||||
|
||||
#### Dependency Graph
|
||||
```
|
||||
api ──────┐
|
||||
├──→ auth ───→ database
|
||||
orders ───┤ ↑
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 5. Design Patterns
|
||||
|
||||
Document key architectural patterns used:
|
||||
|
||||
#### Pattern 1: [Pattern Name, e.g., "Repository Pattern"]
|
||||
- **Where**: [Which modules use this pattern]
|
||||
- **Why**: [Reason for using this pattern]
|
||||
- **How**: [Brief explanation of implementation]
|
||||
|
||||
#### Pattern 2: [Another pattern]
|
||||
[Similar structure]
|
||||
|
||||
### 6. Aggregated API Overview
|
||||
|
||||
High-level summary of all public APIs across modules. Group by category:
|
||||
|
||||
#### Authentication APIs
|
||||
- `auth.authenticate(credentials)` - Validate user credentials
|
||||
- `auth.authorize(user, permission)` - Check user permissions
|
||||
- `auth.generateToken(userId)` - Create JWT token
|
||||
|
||||
#### Data APIs
|
||||
- `database.findOne(query)` - Find single record
|
||||
- `database.findMany(query)` - Find multiple records
|
||||
- `database.insert(data)` - Insert new record
|
||||
|
||||
#### Utility APIs
|
||||
- `utils.logger.log(message)` - Application logging
|
||||
- `utils.validator.validate(data, schema)` - Data validation
|
||||
|
||||
*Note: For detailed API signatures, refer to individual module API.md files*
|
||||
|
||||
### 7. Data Flow
|
||||
|
||||
Describe how data moves through the system:
|
||||
|
||||
**Request Lifecycle**:
|
||||
1. HTTP request enters through API layer
|
||||
2. Request validation and authentication (auth module)
|
||||
3. Business logic processing (domain modules)
|
||||
4. Data persistence (database module)
|
||||
5. Response formatting and return
|
||||
|
||||
**Event Flow** (if applicable):
|
||||
- [Describe event-driven flows if present]
|
||||
|
||||
### 8. Security Architecture
|
||||
|
||||
Overview of security measures:
|
||||
|
||||
- **Authentication**: [JWT, OAuth2, etc.]
|
||||
- **Authorization**: [RBAC, ACL, etc.]
|
||||
- **Data Protection**: [Encryption, hashing]
|
||||
- **API Security**: [Rate limiting, CORS, etc.]
|
||||
|
||||
### 9. Scalability Considerations
|
||||
|
||||
Architectural decisions that support scalability:
|
||||
|
||||
- [Horizontal scaling approach]
|
||||
- [Caching strategy]
|
||||
- [Database optimization]
|
||||
- [Load balancing]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Synthesize, don't duplicate** - Reference module docs, don't copy them
|
||||
2. **System-level perspective** - Focus on how modules work together
|
||||
3. **Visual aids** - Use diagrams for clarity (ASCII art is fine)
|
||||
4. **Aggregated APIs** - One-line summaries only, link to detailed docs
|
||||
5. **Design rationale** - Explain WHY decisions were made
|
||||
6. **Maintain consistency** - Ensure all module docs are considered
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
This document requires the following to be available:
|
||||
- All module README.md files (for understanding module purposes)
|
||||
- All module API.md files (for aggregating API overview)
|
||||
- Project README.md (for context and navigation)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for project overview
|
||||
- [Module Documentation](./modules/) for detailed module docs
|
||||
@@ -0,0 +1,205 @@
|
||||
# Project Examples Documentation Template
|
||||
|
||||
Generate practical, end-to-end examples demonstrating core usage patterns of the project. Focus on realistic scenarios that span multiple modules. These examples should help users understand how to accomplish common tasks.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Introduction
|
||||
|
||||
Brief overview of what these examples cover:
|
||||
|
||||
> This document provides complete, working examples for common use cases. Each example demonstrates how multiple modules work together to accomplish a specific task.
|
||||
|
||||
**Prerequisites**:
|
||||
- [List required setup, e.g., "Project installed and configured"]
|
||||
- [Environment requirements, e.g., "PostgreSQL running on localhost"]
|
||||
|
||||
### 2. Quick Start Example
|
||||
|
||||
The simplest possible working example to get started:
|
||||
|
||||
```typescript
|
||||
// The minimal example to verify setup
|
||||
import { App } from './src';
|
||||
|
||||
const app = new App();
|
||||
await app.start();
|
||||
console.log('Application running!');
|
||||
```
|
||||
|
||||
**What this does**: [Brief explanation]
|
||||
|
||||
### 3. Core Use Cases
|
||||
|
||||
Provide 3-5 complete examples for common scenarios:
|
||||
|
||||
#### Example 1: [Scenario Name, e.g., "User Registration and Login"]
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
|
||||
**Modules involved**: `auth`, `database`, `api`
|
||||
|
||||
**Complete code**:
|
||||
```typescript
|
||||
import { createUser, authenticateUser } from './modules/auth';
|
||||
import { startServer } from './modules/api';
|
||||
|
||||
// Step 1: Initialize the application
|
||||
const app = await startServer({ port: 3000 });
|
||||
|
||||
// Step 2: Register a new user
|
||||
const user = await createUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123',
|
||||
name: 'John Doe'
|
||||
});
|
||||
|
||||
// Step 3: Authenticate the user
|
||||
const session = await authenticateUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123'
|
||||
});
|
||||
|
||||
// Step 4: Use the authentication token
|
||||
console.log('Login successful, token:', session.token);
|
||||
```
|
||||
|
||||
**Expected output**:
|
||||
```
|
||||
Server started on port 3000
|
||||
User created: { id: 1, email: 'user@example.com', name: 'John Doe' }
|
||||
Login successful, token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**Explanation**:
|
||||
1. [Step-by-step breakdown of what each part does]
|
||||
2. [How modules interact]
|
||||
3. [Common variations or customizations]
|
||||
|
||||
---
|
||||
|
||||
#### Example 2: [Another Common Scenario]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
---
|
||||
|
||||
#### Example 3: [Another Use Case]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
### 4. Advanced Examples
|
||||
|
||||
More complex scenarios for power users:
|
||||
|
||||
#### Advanced Example 1: [Complex Scenario]
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
|
||||
**Modules involved**: [List]
|
||||
|
||||
```typescript
|
||||
// Complete working code with detailed comments
|
||||
```
|
||||
|
||||
**Key points**:
|
||||
- [Important concept or gotcha]
|
||||
- [Performance consideration]
|
||||
- [Security note]
|
||||
|
||||
### 5. Integration Examples
|
||||
|
||||
Examples showing how to integrate with external systems:
|
||||
|
||||
#### Integration with [External System]
|
||||
|
||||
```typescript
|
||||
// Example of integrating with a third-party service
|
||||
```
|
||||
|
||||
### 6. Testing Examples
|
||||
|
||||
Show how to test code that uses this project:
|
||||
|
||||
```typescript
|
||||
// Example test case using the project
|
||||
import { describe, it, expect } from 'your-test-framework';
|
||||
|
||||
describe('User authentication', () => {
|
||||
it('should authenticate valid credentials', async () => {
|
||||
const result = await authenticateUser({
|
||||
email: 'test@example.com',
|
||||
password: 'password123'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.token).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 7. Best Practices
|
||||
|
||||
Demonstrate recommended patterns:
|
||||
|
||||
#### Pattern 1: [Best Practice Title]
|
||||
```typescript
|
||||
// Good: Recommended approach
|
||||
const result = await handleWithErrorRecovery(operation);
|
||||
|
||||
// Bad: Anti-pattern to avoid
|
||||
const result = operation(); // No error handling
|
||||
```
|
||||
|
||||
**Why**: [Explanation of why this is the best approach]
|
||||
|
||||
#### Pattern 2: [Another Best Practice]
|
||||
[Similar structure]
|
||||
|
||||
### 8. Troubleshooting Common Issues
|
||||
|
||||
Example-based solutions to common problems:
|
||||
|
||||
#### Issue: [Common Problem]
|
||||
|
||||
**Symptom**: [What the user experiences]
|
||||
|
||||
**Solution**:
|
||||
```typescript
|
||||
// Before: Code that causes the issue
|
||||
const broken = doSomethingWrong();
|
||||
|
||||
// After: Corrected code
|
||||
const fixed = doSomethingRight();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Complete, runnable code** - Every example should be copy-paste ready
|
||||
2. **Real-world scenarios** - Avoid trivial or contrived examples
|
||||
3. **Explain the flow** - Show how modules work together
|
||||
4. **Include output** - Show what users should expect to see
|
||||
5. **Error handling** - Demonstrate proper error handling patterns
|
||||
6. **Comment complex parts** - Help readers understand non-obvious code
|
||||
7. **Version compatibility** - Note if examples are version-specific
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
All example code should:
|
||||
- Follow project coding standards
|
||||
- Include proper error handling
|
||||
- Use async/await correctly
|
||||
- Show TypeScript types where applicable
|
||||
- Be tested and verified to work
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for getting started
|
||||
- [Architecture](./ARCHITECTURE.md) for understanding system design
|
||||
- [Module Documentation](./modules/) for API details
|
||||
Reference in New Issue
Block a user