---

name: backend-fundamentals description: Auto-invoke when reviewing API routes, server logic, Express/Node.js code, or backend architecture. Enforces REST conventions, middleware patterns, and separation of concerns.

Backend Fundamentals Review

"APIs are contracts. Break them, and you break trust."

When to Apply

Activate this skill when reviewing:

• API route handlers
• Express/Fastify/Hono middleware
• Database queries and models
• Authentication/authorization logic
• Server-side business logic

---

Review Checklist

API Design

• RESTful: Do routes follow REST conventions? (GET for read, POST for create, etc.)
• Naming: Are endpoints nouns, not verbs? (/users not /getUsers)
• Versioning: Is API versioned for future changes? (/api/v1/)
• Status Codes: Are correct HTTP status codes returned?

Separation of Concerns

• Routes: Do routes only handle HTTP concerns (req/res)?
• Controllers: Is business logic in controllers/services, not routes?
• Services: Is data access abstracted from business logic?
• Models: Are models responsible only for data shape/validation?

Error Handling

• Try/Catch: Are async operations wrapped properly?
• Error Responses: Are errors returned with proper status codes?
• Logging: Are errors logged with context?
• No Leaks: Are internal errors hidden from clients?

Security

• Input Validation: Is ALL input validated before use?
• Authentication: Are protected routes actually protected?
• Authorization: Can users only access their own data?
• Rate Limiting: Are endpoints protected from abuse?

---

Common Mistakes (Anti-Patterns)

1. Fat Routes

Copy❌ app.post('/users', async (req, res) => {
     // 100 lines of validation, business logic, DB queries
   });

✅ app.post('/users', validateUser, userController.create);

2. No Input Validation

Copy❌ const { email } = req.body;
   await db.query(`SELECT * FROM users WHERE email = '${email}'`);

✅ const { email } = validateBody(req.body, userSchema);
   await User.findByEmail(email); // parameterized

3. Wrong Status Codes

Copy❌ res.status(200).json({ error: 'Not found' });

✅ res.status(404).json({ error: 'User not found' });

4. Leaking Internal Errors

Copy❌ catch (error) {
     res.status(500).json({ error: error.message, stack: error.stack });
   }

✅ catch (error) {
     logger.error('User creation failed', { error, userId });
     res.status(500).json({ error: 'Something went wrong' });
   }

---

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Architecture: "If I wanted to switch from Express to Fastify, what would need to change?"
2. Validation: "What happens if someone sends malformed JSON?"
3. Auth: "How do you know this user owns this resource?"
4. Errors: "What does the client see when the database is down?"
5. Testing: "How would you test this endpoint in isolation?"

---

HTTP Status Code Reference

---

Architecture Layers

CopyRequest → Route → Controller → Service → Repository → Database
                     ↓
              Middleware (auth, validation, logging)

---

Red Flags to Call Out