Backend Patterns

1---
2name: backend-patterns
3description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
4author: affaan-m
5version: "1.0"
6---
7 
8# Backend Development Patterns
9 
10Backend architecture patterns and best practices for scalable server-side applications.
11 
12## API Design Patterns
13 
14### RESTful API Structure
15 
16```typescript
17// ✅ Resource-based URLs
18GET    /api/markets                 # List resources
19GET    /api/markets/:id             # Get single resource
20POST   /api/markets                 # Create resource
21PUT    /api/markets/:id             # Replace resource
22PATCH  /api/markets/:id             # Update resource
23DELETE /api/markets/:id             # Delete resource
24 
25// ✅ Query parameters for filtering, sorting, pagination
26GET /api/markets?status=active&sort=volume&limit=20&offset=0
27```
28 
29### Repository Pattern
30 
31```typescript
32// Abstract data access logic
33interface MarketRepository {
34  findAll(filters?: MarketFilters): Promise<Market[]>
35  findById(id: string): Promise<Market | null>
36  create(data: CreateMarketDto): Promise<Market>
37  update(id: string, data: UpdateMarketDto): Promise<Market>
38  delete(id: string): Promise<void>
39}
40 
41class SupabaseMarketRepository implements MarketRepository {
42  async findAll(filters?: MarketFilters): Promise<Market[]> {
43    let query = supabase.from('markets').select('*')
44 
45    if (filters?.status) {
46      query = query.eq('status', filters.status)
47    }
48 
49    if (filters?.limit) {
50      query = query.limit(filters.limit)
51    }
52 
53    const { data, error } = await query
54 
55    if (error) throw new Error(error.message)
56    return data
57  }
58 
59  // Other methods...
60}
61```
62 
63### Service Layer Pattern
64 
65```typescript
66// Business logic separated from data access
67class MarketService {
68  constructor(private marketRepo: MarketRepository) {}
69 
70  async searchMarkets(query: string, limit: number = 10): Promise<Market[]> {
71    // Business logic
72    const embedding = await generateEmbedding(query)
73    const results = await this.vectorSearch(embedding, limit)
74 
75    // Fetch full data
76    const markets = await this.marketRepo.findByIds(results.map(r => r.id))
77 
78    // Sort by similarity
79    return markets.sort((a, b) => {
80      const scoreA = results.find(r => r.id === a.id)?.score || 0
81      const scoreB = results.find(r => r.id === b.id)?.score || 0
82      return scoreA - scoreB
83    })
84  }
85 
86  private async vectorSearch(embedding: number[], limit: number) {
87    // Vector search implementation
88  }
89}
90```
91 
92### Middleware Pattern
93 
94```typescript
95// Request/response processing pipeline
96export function withAuth(handler: NextApiHandler): NextApiHandler {
97  return async (req, res) => {
98    const token = req.headers.authorization?.replace('Bearer ', '')
99 
100    if (!token) {
101      return res.status(401).json({ error: 'Unauthorized' })
102    }
103 
104    try {
105      const user = await verifyToken(token)
106      req.user = user
107      return handler(req, res)
108    } catch (error) {
109      return res.status(401).json({ error: 'Invalid token' })
110    }
111  }
112}
113 
114// Usage
115export default withAuth(async (req, res) => {
116  // Handler has access to req.user
117})
118```
119 
120## Database Patterns
121 
122### Query Optimization
123 
124```typescript
125// ✅ GOOD: Select only needed columns
126const { data } = await supabase
127  .from('markets')
128  .select('id, name, status, volume')
129  .eq('status', 'active')
130  .order('volume', { ascending: false })
131  .limit(10)
132 
133// ❌ BAD: Select everything
134const { data } = await supabase
135  .from('markets')
136  .select('*')
137```
138 
139### N+1 Query Prevention
140 
141```typescript
142// ❌ BAD: N+1 query problem
143const markets = await getMarkets()
144for (const market of markets) {
145  market.creator = await getUser(market.creator_id)  // N queries
146}
147 
148// ✅ GOOD: Batch fetch
149const markets = await getMarkets()
150const creatorIds = markets.map(m => m.creator_id)
151const creators = await getUsers(creatorIds)  // 1 query
152const creatorMap = new Map(creators.map(c => [c.id, c]))
153 
154markets.forEach(market => {
155  market.creator = creatorMap.get(market.creator_id)
156})
157```
158 
159### Transaction Pattern
160 
161```typescript
162async function createMarketWithPosition(
163  marketData: CreateMarketDto,
164  positionData: CreatePositionDto
165) {
166  // Use Supabase transaction
167  const { data, error } = await supabase.rpc('create_market_with_position', {
168    market_data: marketData,
169    position_data: positionData
170  })
171 
172  if (error) throw new Error('Transaction failed')
173  return data
174}
175 
176// SQL function in Supabase
177CREATE OR REPLACE FUNCTION create_market_with_position(
178  market_data jsonb,
179  position_data jsonb
180)
181RETURNS jsonb
182LANGUAGE plpgsql
183AS $$
184BEGIN
185  -- Start transaction automatically
186  INSERT INTO markets VALUES (market_data);
187  INSERT INTO positions VALUES (position_data);
188  RETURN jsonb_build_object('success', true);
189EXCEPTION
190  WHEN OTHERS THEN
191    -- Rollback happens automatically
192    RETURN jsonb_build_object('success', false, 'error', SQLERRM);
193END;
194$$;
195```
196 
197## Caching Strategies
198 
199### Redis Caching Layer
200 
201```typescript
202class CachedMarketRepository implements MarketRepository {
203  constructor(
204    private baseRepo: MarketRepository,
205    private redis: RedisClient
206  ) {}
207 
208  async findById(id: string): Promise<Market | null> {
209    // Check cache first
210    const cached = await this.redis.get(`market:${id}`)
211 
212    if (cached) {
213      return JSON.parse(cached)
214    }
215 
216    // Cache miss - fetch from database
217    const market = await this.baseRepo.findById(id)
218 
219    if (market) {
220      // Cache for 5 minutes
221      await this.redis.setex(`market:${id}`, 300, JSON.stringify(market))
222    }
223 
224    return market
225  }
226 
227  async invalidateCache(id: string): Promise<void> {
228    await this.redis.del(`market:${id}`)
229  }
230}
231```
232 
233### Cache-Aside Pattern
234 
235```typescript
236async function getMarketWithCache(id: string): Promise<Market> {
237  const cacheKey = `market:${id}`
238 
239  // Try cache
240  const cached = await redis.get(cacheKey)
241  if (cached) return JSON.parse(cached)
242 
243  // Cache miss - fetch from DB
244  const market = await db.markets.findUnique({ where: { id } })
245 
246  if (!market) throw new Error('Market not found')
247 
248  // Update cache
249  await redis.setex(cacheKey, 300, JSON.stringify(market))
250 
251  return market
252}
253```
254 
255## Error Handling Patterns
256 
257### Centralized Error Handler
258 
259```typescript
260class ApiError extends Error {
261  constructor(
262    public statusCode: number,
263    public message: string,
264    public isOperational = true
265  ) {
266    super(message)
267    Object.setPrototypeOf(this, ApiError.prototype)
268  }
269}
270 
271export function errorHandler(error: unknown, req: Request): Response {
272  if (error instanceof ApiError) {
273    return NextResponse.json({
274      success: false,
275      error: error.message
276    }, { status: error.statusCode })
277  }
278 
279  if (error instanceof z.ZodError) {
280    return NextResponse.json({
281      success: false,
282      error: 'Validation failed',
283      details: error.errors
284    }, { status: 400 })
285  }
286 
287  // Log unexpected errors
288  console.error('Unexpected error:', error)
289 
290  return NextResponse.json({
291    success: false,
292    error: 'Internal server error'
293  }, { status: 500 })
294}
295 
296// Usage
297export async function GET(request: Request) {
298  try {
299    const data = await fetchData()
300    return NextResponse.json({ success: true, data })
301  } catch (error) {
302    return errorHandler(error, request)
303  }
304}
305```
306 
307### Retry with Exponential Backoff
308 
309```typescript
310async function fetchWithRetry<T>(
311  fn: () => Promise<T>,
312  maxRetries = 3
313): Promise<T> {
314  let lastError: Error
315 
316  for (let i = 0; i < maxRetries; i++) {
317    try {
318      return await fn()
319    } catch (error) {
320      lastError = error as Error
321 
322      if (i < maxRetries - 1) {
323        // Exponential backoff: 1s, 2s, 4s
324        const delay = Math.pow(2, i) * 1000
325        await new Promise(resolve => setTimeout(resolve, delay))
326      }
327    }
328  }
329 
330  throw lastError!
331}
332 
333// Usage
334const data = await fetchWithRetry(() => fetchFromAPI())
335```
336 
337## Authentication & Authorization
338 
339### JWT Token Validation
340 
341```typescript
342import jwt from 'jsonwebtoken'
343 
344interface JWTPayload {
345  userId: string
346  email: string
347  role: 'admin' | 'user'
348}
349 
350export function verifyToken(token: string): JWTPayload {
351  try {
352    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload
353    return payload
354  } catch (error) {
355    throw new ApiError(401, 'Invalid token')
356  }
357}
358 
359export async function requireAuth(request: Request) {
360  const token = request.headers.get('authorization')?.replace('Bearer ', '')
361 
362  if (!token) {
363    throw new ApiError(401, 'Missing authorization token')
364  }
365 
366  return verifyToken(token)
367}
368 
369// Usage in API route
370export async function GET(request: Request) {
371  const user = await requireAuth(request)
372 
373  const data = await getDataForUser(user.userId)
374 
375  return NextResponse.json({ success: true, data })
376}
377```
378 
379### Role-Based Access Control
380 
381```typescript
382type Permission = 'read' | 'write' | 'delete' | 'admin'
383 
384interface User {
385  id: string
386  role: 'admin' | 'moderator' | 'user'
387}
388 
389const rolePermissions: Record<User['role'], Permission[]> = {
390  admin: ['read', 'write', 'delete', 'admin'],
391  moderator: ['read', 'write', 'delete'],
392  user: ['read', 'write']
393}
394 
395export function hasPermission(user: User, permission: Permission): boolean {
396  return rolePermissions[user.role].includes(permission)
397}
398 
399export function requirePermission(permission: Permission) {
400  return async (request: Request) => {
401    const user = await requireAuth(request)
402 
403    if (!hasPermission(user, permission)) {
404      throw new ApiError(403, 'Insufficient permissions')
405    }
406 
407    return user
408  }
409}
410 
411// Usage
412export const DELETE = requirePermission('delete')(async (request: Request) => {
413  // Handler with permission check
414})
415```
416 
417## Rate Limiting
418 
419### Simple In-Memory Rate Limiter
420 
421```typescript
422class RateLimiter {
423  private requests = new Map<string, number[]>()
424 
425  async checkLimit(
426    identifier: string,
427    maxRequests: number,
428    windowMs: number
429  ): Promise<boolean> {
430    const now = Date.now()
431    const requests = this.requests.get(identifier) || []
432 
433    // Remove old requests outside window
434    const recentRequests = requests.filter(time => now - time < windowMs)
435 
436    if (recentRequests.length >= maxRequests) {
437      return false  // Rate limit exceeded
438    }
439 
440    // Add current request
441    recentRequests.push(now)
442    this.requests.set(identifier, recentRequests)
443 
444    return true
445  }
446}
447 
448const limiter = new RateLimiter()
449 
450export async function GET(request: Request) {
451  const ip = request.headers.get('x-forwarded-for') || 'unknown'
452 
453  const allowed = await limiter.checkLimit(ip, 100, 60000)  // 100 req/min
454 
455  if (!allowed) {
456    return NextResponse.json({
457      error: 'Rate limit exceeded'
458    }, { status: 429 })
459  }
460 
461  // Continue with request
462}
463```
464 
465## Background Jobs & Queues
466 
467### Simple Queue Pattern
468 
469```typescript
470class JobQueue<T> {
471  private queue: T[] = []
472  private processing = false
473 
474  async add(job: T): Promise<void> {
475    this.queue.push(job)
476 
477    if (!this.processing) {
478      this.process()
479    }
480  }
481 
482  private async process(): Promise<void> {
483    this.processing = true
484 
485    while (this.queue.length > 0) {
486      const job = this.queue.shift()!
487 
488      try {
489        await this.execute(job)
490      } catch (error) {
491        console.error('Job failed:', error)
492      }
493    }
494 
495    this.processing = false
496  }
497 
498  private async execute(job: T): Promise<void> {
499    // Job execution logic
500  }
501}
502 
503// Usage for indexing markets
504interface IndexJob {
505  marketId: string
506}
507 
508const indexQueue = new JobQueue<IndexJob>()
509 
510export async function POST(request: Request) {
511  const { marketId } = await request.json()
512 
513  // Add to queue instead of blocking
514  await indexQueue.add({ marketId })
515 
516  return NextResponse.json({ success: true, message: 'Job queued' })
517}
518```
519 
520## Logging & Monitoring
521 
522### Structured Logging
523 
524```typescript
525interface LogContext {
526  userId?: string
527  requestId?: string
528  method?: string
529  path?: string
530  [key: string]: unknown
531}
532 
533class Logger {
534  log(level: 'info' | 'warn' | 'error', message: string, context?: LogContext) {
535    const entry = {
536      timestamp: new Date().toISOString(),
537      level,
538      message,
539      ...context
540    }
541 
542    console.log(JSON.stringify(entry))
543  }
544 
545  info(message: string, context?: LogContext) {
546    this.log('info', message, context)
547  }
548 
549  warn(message: string, context?: LogContext) {
550    this.log('warn', message, context)
551  }
552 
553  error(message: string, error: Error, context?: LogContext) {
554    this.log('error', message, {
555      ...context,
556      error: error.message,
557      stack: error.stack
558    })
559  }
560}
561 
562const logger = new Logger()
563 
564// Usage
565export async function GET(request: Request) {
566  const requestId = crypto.randomUUID()
567 
568  logger.info('Fetching markets', {
569    requestId,
570    method: 'GET',
571    path: '/api/markets'
572  })
573 
574  try {
575    const markets = await fetchMarkets()
576    return NextResponse.json({ success: true, data: markets })
577  } catch (error) {
578    logger.error('Failed to fetch markets', error as Error, { requestId })
579    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
580  }
581}
582```
583 
584**Remember**: Backend patterns enable scalable, maintainable server-side applications. Choose patterns that fit your complexity level.