OGT Docs - Rules Code Back

Backend-specific coding standards for APIs, databases, and services.

Overview

Backend rules establish consistent patterns for API design, database operations, service architecture, and server-side logic.

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"]

When to Use

• Creating API design standards
• Defining database patterns
• Establishing service architecture
• Writing authentication rules
• Setting validation patterns

Folder Structure

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/

---

Example: docs/rules/code/back/api/rest_design/

rule.md

# Rule: RESTful API Design

## Summary

APIs MUST follow RESTful conventions for resource naming, HTTP methods, and status codes.

## The Rules

### 1. Resource Naming

**MUST** use plural nouns for collections.

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

### 2. HTTP Methods

| Method | Use Case | Idempotent |
|--------|----------|------------|
| GET | Retrieve | Yes |
| POST | Create | No |
| PUT | Replace | Yes |
| PATCH | Update | Yes |
| DELETE | Remove | Yes |

### 3. Status Codes

| Code | Use When |
|------|----------|
| 200 | Successful GET/PUT/PATCH |
| 201 | Successful POST |
| 204 | Successful DELETE |
| 400 | Invalid input |
| 401 | Not authenticated |
| 403 | Not authorized |
| 404 | Not found |
| 422 | Validation failed |

## Examples

### Correct

```typescript
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 };
});

Incorrect

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

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

---

## Example: docs/rules/code/back/database/queries/

### rule.md

```markdown
# Rule: Database Queries

## Summary

Database queries MUST be parameterized, efficient, and properly scoped.

## The Rules

### 1. Always Parameterize

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

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

2. Select Only Needed Columns

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

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

3. Always Limit Results

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

4. Avoid N+1 Queries

// 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,
]);

5. Use Transactions

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,
  ]);
});

---

## Example: docs/rules/code/back/services/structure/

### rule.md

```markdown
# Rule: Service Structure

## Summary

Services MUST follow consistent structure with clear separation of concerns.

## The Rules

### 1. Single Responsibility

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

2. Dependency Injection

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

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

3. Domain-Specific Errors

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

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

4. Method Naming

Operation	Pattern
Get single	findById
Get multiple	findAll
Create	create
Update	update
Delete	delete

---

## Example: docs/rules/code/back/auth/tokens/

### rule.md

```markdown
# Rule: Authentication Tokens

## Summary

Tokens MUST be securely generated, stored, and validated.

## The Rules

### 1. Secure Generation

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

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

2. Token Expiration

Token Type	Max Lifetime
Access Token	15-60 minutes
Refresh Token	7-30 days
Password Reset	1 hour

3. Secure Storage

Context	Storage
Browser	httpOnly cookie
Mobile	Secure storage
Server	Hashed in DB

4. Full Validation

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;
}

5. Revocation

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

---

## Creating Backend Rules

```mermaid
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]

---

Signal Files Reference

Signal	Content	Purpose
.version	JSON	Schema version
.enforced_by	List	Tools that enforce
.security_review	Date	Last security review

---

Backend Rule Checklist

• Rule is backend/server specific
• Security implications addressed
• Performance considerations noted
• Database patterns follow best practices
• Error handling included
• Examples use TypeScript