flowchart TB
    subgraph back ["docs/rules/code/back/"]
        API["api/"]
        DB["database/"]
        SVC["services/"]
        AUTH["auth/"]
        VALID["validation/"]
    end

    API --> |patterns| A1["REST design"]
    API --> |patterns| A2["response format"]
    DB --> |patterns| D1["queries"]
    SVC --> |patterns| S1["architecture"]
    AUTH --> |patterns| AU1["tokens"]

docs/rules/code/back/
├── api/                            # API design
│   ├── rest_design/
│   ├── response_format/
│   ├── versioning/
│   └── error_responses/
│
├── database/                       # Database patterns
│   ├── queries/
│   ├── migrations/
│   ├── naming/
│   └── transactions/
│
├── services/                       # Service architecture
│   ├── structure/
│   ├── dependencies/
│   └── error_handling/
│
├── auth/                           # Authentication
│   ├── tokens/
│   ├── sessions/
│   └── permissions/
│
└── validation/                     # Input validation
    ├── request_validation/
    └── sanitization/

undefined

GET /api/users # Collection
GET /api/users/123 # Single resource
POST /api/users # Create

router.get('/users', async (ctx) => {
  ctx.status = 200;
  ctx.body = { data: users };
});

router.post('/users', async (ctx) => {
  const user = await userService.create(ctx.request.body);
  ctx.status = 201;
  ctx.body = { data: user };
});

// BAD - verbs in URL
router.post('/api/createUser', ...);

// BAD - wrong status
router.post('/users', async (ctx) => {
  ctx.status = 200;  // Should be 201
});

---

undefined

// CORRECT
await db.query('SELECT * FROM users WHERE id = $1', [userId]);

// FORBIDDEN - SQL injection
await db.query(`SELECT * FROM users WHERE id = ${userId}`);

// CORRECT
await db.query("SELECT id, name FROM users WHERE id = $1", [id]);

// AVOID
await db.query("SELECT * FROM users WHERE id = $1", [id]);

// CORRECT
await db.query("SELECT * FROM posts LIMIT $1 OFFSET $2", [limit, offset]);

// BAD - N+1
for (const user of users) {
  user.posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
    user.id,
  ]);
}

// GOOD - batch
const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
  userIds,
]);

await db.transaction(async (trx) => {
  await trx.query("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [
    amount,
    fromId,
  ]);
  await trx.query("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [
    amount,
    toId,
  ]);
});

---

undefined

// CORRECT - focused services
class UserService { /* user operations */ }
class AuthService { /* authentication */ }
class EmailService { /* email sending */ }

// CORRECT
class UserService {
  constructor(
    private db: Database,
    private emailService: EmailService,
  ) {}
}

// INCORRECT - hard to test
class UserService {
  private db = new Database();
}

// CORRECT
class UserNotFoundError extends Error {
  constructor(public userId: string) {
    super(`User not found: ${userId}`);
  }
}

// INCORRECT
throw new Error("Not found");

---

undefined

// CORRECT
import { randomBytes } from 'crypto';
const token = randomBytes(32).toString('hex');

// INCORRECT - predictable
const token = Date.now().toString();

async function validateToken(token: string): Promise<User> {
  const payload = jwt.verify(token, secret);
  const user = await userService.findById(payload.userId);
  if (!user || !user.isActive) throw new InvalidTokenError();
  return user;
}

async function logout(userId: string, refreshToken: string) {
  await db.refreshTokens.delete({ where: { token: hashToken(refreshToken) } });
}

---

flowchart TD
    A[Identify Pattern] --> B{Category}

    B -->|API| C[api/]
    B -->|Database| D[database/]
    B -->|Services| E[services/]
    B -->|Auth| F[auth/]

    C --> G[Create Rule Folder]
    D --> G
    E --> G
    F --> G

    G --> H[Write rule.md]
    H --> I[Add examples.md]
    I --> J[Security review if auth/db]