Skip to content

SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist

documentation-specialist

Verified

This skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".

FileKindSize
SKILL.mdskill md10.0 KB
references/examples/TOC.mdmarkdown6.5 KB
references/examples/brownfield/database-failover-runbook.mdmarkdown8.1 KB
references/examples/brownfield/spring-boot-sdd.mdmarkdown5.6 KB
references/examples/greenfield/adr-microservices.mdmarkdown6.3 KB
references/examples/greenfield/architecture-doc.mdmarkdown3.7 KB
references/examples/greenfield/billing-srs.mdmarkdown12.4 KB
references/examples/greenfield/cli-getting-started.mdmarkdown9.3 KB
references/examples/greenfield/collaboration-prd.mdmarkdown13.8 KB
references/examples/greenfield/document-specialist-sdd.mdmarkdown15.4 KB
references/examples/greenfield/ecommerce-sdd.mdmarkdown7.8 KB
references/examples/greenfield/rest-api-tutorial.mdmarkdown13.8 KB
references/examples/greenfield/task-api-openapi.yamlconfig19.0 KB
references/examples/greenfield/taskmanager-user-manual.mdmarkdown8.7 KB
references/examples/greenfield/ui-wireframes.mdmarkdown5.8 KB
references/guides/requirements/README.mdmarkdown3.7 KB
references/mappings/backend/fastapi-mapping.yamlconfig9.7 KB
references/mappings/backend/spring-boot-mapping.yamlconfig24.1 KB
references/reference/01-philosophy.mdmarkdown2.0 KB
references/reference/02-requirements-srs-vs-prd.mdmarkdown1.2 KB
references/reference/02-requirements-traceability.mdmarkdown1.7 KB
references/reference/02-requirements-writing.mdmarkdown1.4 KB
references/reference/03-design-adrs.mdmarkdown2.2 KB
references/reference/03-design-arc42.mdmarkdown2.6 KB
references/reference/03-design-requirements-matrix.mdmarkdown1.3 KB
references/reference/04-diagrams-c4-hierarchy.mdmarkdown2.0 KB
references/reference/04-diagrams-selection.mdmarkdown5.1 KB
references/reference/04-diagrams-state-vs-activity.mdmarkdown2.3 KB
references/reference/05-api-checklist.mdmarkdown2.0 KB
references/reference/05-api-openapi.mdmarkdown3.4 KB
references/reference/05-api-stripe-gold-standard.mdmarkdown1.8 KB
references/reference/06-deployment-diagrams.mdmarkdown1.8 KB
references/reference/06-deployment-documentation.mdmarkdown2.9 KB
references/reference/06-deployment-runbooks.mdmarkdown2.5 KB
references/reference/06-operational-docs.mdmarkdown2.7 KB
references/reference/07-user-kb-approach.mdmarkdown1.8 KB
references/reference/07-user-kb-template.mdmarkdown3.1 KB
references/reference/07-user-writing-style.mdmarkdown2.0 KB
references/reference/08-agile-process.mdmarkdown3.2 KB
references/reference/08-tutorial-writing.mdmarkdown7.4 KB
references/reference/09-code-to-docs-detection.mdmarkdown2.5 KB
references/reference/09-code-to-docs-example.mdmarkdown3.2 KB
references/reference/09-code-to-docs-when.mdmarkdown1.7 KB
references/reference/09-code-to-docs-workflow.mdmarkdown2.0 KB
references/reference/10-quality-bonsai-pruning.mdmarkdown2.4 KB
references/reference/10-quality-checklist.mdmarkdown2.6 KB
references/reference/10-quality-metrics.mdmarkdown3.1 KB
references/reference/11-voice-and-style.mdmarkdown1.5 KB
references/reference/comprehensive-guide.mdmarkdown7.3 KB
references/templates/markdown/DESIGN_DOC.mdmarkdown4.5 KB
references/templates/markdown/api-openapi.yamlconfig17.7 KB
references/templates/markdown/architecture.mdmarkdown1.6 KB
references/templates/markdown/design-sdd.mdmarkdown143 B
references/templates/markdown/developer-tutorial.mdmarkdown7.1 KB
references/templates/markdown/getting-started.mdmarkdown6.5 KB
references/templates/markdown/howto-guide.mdmarkdown4.1 KB
references/templates/markdown/requirements-prd.mdmarkdown10.2 KB
references/templates/markdown/requirements-srs.mdmarkdown17.0 KB
references/templates/markdown/runbook.mdmarkdown8.8 KB
references/templates/markdown/user-manual.mdmarkdown4.8 KB
references/workflows/TOC.mdmarkdown1.9 KB
references/workflows/audit-workflow.mdmarkdown2.5 KB
references/workflows/brownfield-workflow.mdmarkdown3.6 KB
references/workflows/brownfield/fastapi-guide.mdmarkdown1.8 KB
references/workflows/brownfield/pulumi-guide.mdmarkdown1.9 KB
references/workflows/brownfield/springboot-guide.mdmarkdown2.2 KB
references/workflows/convert-workflow.mdmarkdown1.4 KB
references/workflows/design-workflow.mdmarkdown3.0 KB
references/workflows/diagram-workflow.mdmarkdown3.7 KB
references/workflows/greenfield-workflow.mdmarkdown3.4 KB
references/workflows/greenfield/advanced.mdmarkdown1.9 KB
references/workflows/greenfield/openapi-guide.mdmarkdown2.5 KB
references/workflows/greenfield/prd-guide.mdmarkdown2.0 KB
references/workflows/greenfield/srs-guide.mdmarkdown2.0 KB
references/workflows/runbook-workflow.mdmarkdown2.4 KB
references/workflows/tutorial-workflow.mdmarkdown2.3 KB
references/workflows/user-docs-workflow.mdmarkdown2.3 KB

references/examples/greenfield/rest-api-tutorial.md

View on GitHub
# Tutorial: Build a Task API with Node.js and Express

**Learning Objective**: Create a fully functional REST API with CRUD operations, authentication, and database persistence in under 45 minutes.

**Level**: Intermediate
**Time**: ~45 minutes
**Last Updated**: January 18, 2025

---

## What You'll Build

By the end of this tutorial, you'll have created:
- A REST API with full CRUD operations for tasks
- JWT-based authentication (register, login)
- SQLite database for data persistence
- Error handling and validation
- Automated tests with Jest

**Technologies Used**:
- Node.js 18+
- Express.js 4.x
- SQLite3 (via better-sqlite3)
- JWT for authentication
- Jest for testing

**Complete Code**: https://github.com/example/task-api-tutorial

---

## Prerequisites

### Required Knowledge
- JavaScript ES6+ syntax (arrow functions, destructuring, async/await)
- Basic understanding of REST APIs (GET, POST, PUT, DELETE)
- Familiarity with command-line tools

### Required Tools
- [ ] Node.js 18 or higher (`node --version`)
- [ ] npm 8+ or yarn (`npm --version`)
- [ ] Text editor (VS Code recommended)
- [ ] Git (for cloning starter)

### Optional (Recommended)
- [ ] Postman or Insomnia (for API testing)
- [ ] REST Client VS Code extension

**Verify your setup**:
```bash
node --version  # v18.0.0 or higher
npm --version   # 8.0.0 or higher
```

---

## Project Setup (5 Minutes)

### Initialize Project
```bash
mkdir task-api
cd task-api
npm init -y
```

### Install Dependencies
```bash
npm install express better-sqlite3 jsonwebtoken bcrypt dotenv
npm install --save-dev jest supertest nodemon
```

### Project Structure
Create these files:
```bash
touch server.js db.js routes/auth.js routes/tasks.js middleware/auth.js .env
```

**Final structure**:
```
task-api/
├── server.js           # Express app entry point
├── db.js               # Database setup
├── routes/
│   ├── auth.js         # Authentication endpoints
│   └── tasks.js        # Task CRUD endpoints
├── middleware/
│   └── auth.js         # JWT verification middleware
├── tests/
│   └── api.test.js     # Integration tests
├── .env                # Environment variables
└── package.json
```

### Configure Environment
Create `.env`:
```env
PORT=3000
JWT_SECRET=your-secret-key-change-in-production
NODE_ENV=development
```

### Add Scripts to package.json
```json
{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "jest --coverage"
  }
}
```

### Verify Setup
Create minimal `server.js`:
```javascript
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Task API is running' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
```

Start server:
```bash
npm run dev
```

Visit `http://localhost:3000` → should see: `{"message":"Task API is running"}`

✅ **Checkpoint**: If you see the message, your environment is ready!

---

## Step 1: Set Up Database

### What We're Building
A SQLite database with two tables: `users` (authentication) and `tasks` (CRUD operations). We're using SQLite for simplicity, but the patterns apply to PostgreSQL, MySQL, etc.

### The Code
Create `db.js`:
```javascript
const Database = require('better-sqlite3');
const path = require('path');

// Initialize database
const db = new Database(path.join(__dirname, 'tasks.db'));

// Create tables
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT UNIQUE NOT NULL,
    password TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

db.exec(`
  CREATE TABLE IF NOT EXISTS tasks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    description TEXT,
    completed BOOLEAN DEFAULT 0,
    user_id INTEGER NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
  )
`);

console.log('✅ Database initialized');

module.exports = db;
```

### Explanation
**Key Concepts**:
- **better-sqlite3**: Synchronous SQLite library (faster than async for simple operations)
- **Line 8-15**: Users table with unique username constraint
- **Line 17-26**: Tasks table with foreign key to users
- **AUTOINCREMENT**: SQLite auto-generates IDs

💡 **Why SQLite?**: Perfect for development/learning. In production, use PostgreSQL/MySQL with connection pooling.

### Test It
Add to `server.js` (top):
```javascript
require('dotenv').config();
const db = require('./db');  // Initialize database
```

Restart server:
```bash
npm run dev
```

**Expected Output**:
```
✅ Database initialized
Server running on port 3000
```

You should see a `tasks.db` file created in your project directory.

---

## Step 2: Implement Authentication

### What We're Building
User registration and login with JWT tokens. Passwords are hashed with bcrypt (never stored plain-text!).

### The Code
Create `routes/auth.js`:
```javascript
const express = require('express');
const router = express.Router();
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const db = require('../db');

// Register new user
router.post('/register', async (req, res) => {
  try {
    const { username, password } = req.body;

    // Validate input
    if (!username || !password) {
      return res.status(400).json({ error: 'Username and password required' });
    }

    if (password.length < 6) {
      return res.status(400).json({ error: 'Password must be at least 6 characters' });
    }

    // Hash password
    const hashedPassword = await bcrypt.hash(password, 10);

    // Insert user
    const stmt = db.prepare('INSERT INTO users (username, password) VALUES (?, ?)');
    const result = stmt.run(username, hashedPassword);

    res.status(201).json({
      message: 'User created successfully',
      userId: result.lastInsertRowid
    });
  } catch (error) {
    if (error.code === 'SQLITE_CONSTRAINT') {
      return res.status(409).json({ error: 'Username already exists' });
    }
    res.status(500).json({ error: 'Registration failed' });
  }
});

// Login user
router.post('/login', async (req, res) => {
  try {
    const { username, password } = req.body;

    // Find user
    const user = db.prepare('SELECT * FROM users WHERE username = ?').get(username);

    if (!user) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }

    // Verify password
    const validPassword = await bcrypt.compare(password, user.password);

    if (!validPassword) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }

    // Generate JWT
    const token = jwt.sign(
      { userId: user.id, username: user.username },
      process.env.JWT_SECRET,
      { expiresIn: '24h' }
    );

    res.json({
      message: 'Login successful',
      token,
      user: { id: user.id, username: user.username }
    });
  } catch (error) {
    res.status(500).json({ error: 'Login failed' });
  }
});

module.exports = router;
```

### Explanation
**Security Concepts**:
- **bcrypt.hash(password, 10)**: Hashes password with 10 salt rounds (industry standard)
- **bcrypt.compare()**: Safely compares plain-text password with hash
- **JWT**: Stateless authentication token (no session storage needed)
- **expiresIn**: Token auto-expires after 24 hours

**Error Handling**:
- **SQLITE_CONSTRAINT**: Catches duplicate username error
- **401 Unauthorized**: Invalid credentials (vague for security - don't reveal if username or password is wrong)

### Wire It Up
Update `server.js`:
```javascript
require('dotenv').config();
const express = require('express');
const db = require('./db');
const authRoutes = require('./routes/auth');

const app = express();

// Middleware
app.use(express.json());

// Routes
app.use('/auth', authRoutes);

app.get('/', (req, res) => {
  res.json({ message: 'Task API is running' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
```

### Test It
**Register a user**:
```bash
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'
```

**Expected Response**:
```json
{
  "message": "User created successfully",
  "userId": 1
}
```

**Login**:
```bash
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'
```

**Expected Response**:
```json
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {"id": 1, "username": "alice"}
}
```

🔒 **Save this token** - you'll need it for task operations!

### Checkpoint ✅
You should now have:
- Working user registration
- Secure password hashing
- JWT token generation
- Error handling for duplicate users

---

## Step 3: Protect Routes with Middleware

### What We're Building
Middleware that verifies JWT tokens before allowing access to protected routes.

### The Code
Create `middleware/auth.js`:
```javascript
const jwt = require('jsonwebtoken');

function authenticateToken(req, res, next) {
  // Get token from header
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // "Bearer <token>"

  if (!token) {
    return res.status(401).json({ error: 'Access token required' });
  }

  // Verify token
  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) {
      return res.status(403).json({ error: 'Invalid or expired token' });
    }

    // Attach user to request object
    req.user = user;
    next(); // Proceed to route handler
  });
}

module.exports = authenticateToken;
```

### Explanation
**Middleware Pattern**:
- **Line 6**: Extract token from `Authorization: Bearer <token>` header
- **Line 13**: Verify token using same secret used to sign it
- **Line 18**: Attach decoded user info to `req.user` for route handlers
- **Line 19**: Call `next()` to proceed to route handler

**Error Handling**:
- **401 Unauthorized**: No token provided
- **403 Forbidden**: Token invalid or expired

---

## Step 4: Implement Task CRUD Operations

### The Code
Create `routes/tasks.js`:
```javascript
const express = require('express');
const router = express.Router();
const db = require('../db');
const authenticateToken = require('../middleware/auth');

// All routes require authentication
router.use(authenticateToken);

// Get all tasks for current user
router.get('/', (req, res) => {
  const tasks = db.prepare('SELECT * FROM tasks WHERE user_id = ? ORDER BY created_at DESC')
    .all(req.user.userId);
  res.json(tasks);
});

// Create new task
router.post('/', (req, res) => {
  const { title, description } = req.body;

  if (!title) {
    return res.status(400).json({ error: 'Title required' });
  }

  const stmt = db.prepare('INSERT INTO tasks (title, description, user_id) VALUES (?, ?, ?)');
  const result = stmt.run(title, description || '', req.user.userId);

  res.status(201).json({
    id: result.lastInsertRowid,
    title,
    description,
    completed: false,
    user_id: req.user.userId
  });
});

// Update task
router.put('/:id', (req, res) => {
  const { title, description, completed } = req.body;

  const stmt = db.prepare(`
    UPDATE tasks
    SET title = ?, description = ?, completed = ?
    WHERE id = ? AND user_id = ?
  `);

  const result = stmt.run(title, description, completed ? 1 : 0, req.params.id, req.user.userId);

  if (result.changes === 0) {
    return res.status(404).json({ error: 'Task not found' });
  }

  res.json({ message: 'Task updated successfully' });
});

// Delete task
router.delete('/:id', (req, res) => {
  const stmt = db.prepare('DELETE FROM tasks WHERE id = ? AND user_id = ?');
  const result = stmt.run(req.params.id, req.user.userId);

  if (result.changes === 0) {
    return res.status(404).json({ error: 'Task not found' });
  }

  res.json({ message: 'Task deleted successfully' });
});

module.exports = router;
```

### Wire It Up
Add to `server.js`:
```javascript
const taskRoutes = require('./routes/tasks');
app.use('/tasks', taskRoutes);  // Add after auth routes
```

### Test Full Workflow
**1. Register & Login** (get token):
```bash
TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}' \
  | grep -o '"token":"[^"]*' | cut -d'"' -f4)
```

**2. Create Task**:
```bash
curl -X POST http://localhost:3000/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Build Task API","description":"Complete tutorial"}'
```

**3. Get All Tasks**:
```bash
curl http://localhost:3000/tasks \
  -H "Authorization: Bearer $TOKEN"
```

**4. Update Task**:
```bash
curl -X PUT http://localhost:3000/tasks/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Build Task API","description":"Tutorial completed!","completed":true}'
```

**5. Delete Task**:
```bash
curl -X DELETE http://localhost:3000/tasks/1 \
  -H "Authorization: Bearer $TOKEN"
```

---

## What You've Learned

✅ RESTful API design (CRUD operations)
✅ JWT authentication (register, login, protected routes)
✅ Secure password handling with bcrypt
✅ SQLite database with foreign keys
✅ Express middleware pattern
✅ Error handling and validation
✅ HTTP status codes (200, 201, 400, 401, 403, 404, 500)

---

## Challenge Yourself

1. **Easy**: Add pagination to GET /tasks (limit, offset)
2. **Medium**: Add task filtering by completed status
3. **Hard**: Implement refresh tokens for extended sessions

---

## Next Steps

- [Add Testing with Jest](link)
- [Deploy to Production](link)
- [Add PostgreSQL](link)
- [API Documentation with Swagger](link)

---

**Complete Code**: https://github.com/example/task-api-tutorial
**Tutorial Author**: Documentation Specialist Skill
**Last Tested**: January 18, 2025 with Node 18.17.0
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall