Backend patterns

--- name: backend-patterns description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes. origin: ECC --- # Backend Development Patterns Backend architecture patterns and best practices for scalable server-side applications. ## When to Activate - Designing REST or GraphQL API endpoints - Implementing repository, service, or controller layers - Optimizing database queries (N+1, indexing, connection pooling) - Adding caching (Redis, in-memory, HTTP cache headers) - Setting up background jobs or async processing - Structuring error handling and validation for APIs - Building middleware (auth, logging, rate limiting) ## API Design Patterns ### RESTful API Structure ``typescript // PASS: Resource-based URLs GET /api/markets # List resources GET /api/markets/:id # Get single resource POST /api/markets # Create resource PUT /api/markets/:id # Replace resource PATCH /api/markets/:id # Update resource DELETE /api/markets/:id # Delete resource // PASS: Query parameters for filtering, sorting, pagination GET /api/markets?status=active&sort=volume&limit=20&offset=0 ` ### Repository Pattern `typescript // Abstract data access logic interface MarketRepository { findAll(filters?: MarketFilters): Promise<Market[]> findById(id: string): Promise<Market | null> create(data: CreateMarketDto): Promise<Market> update(id: string, data: UpdateMarketDto): Promise<Market> delete(id: string): Promise<void> } class SupabaseMarketRepository implements MarketRepository { async findAll(filters?: MarketFilters): Promise<Market[]> { let query = supabase.from('markets').select('*') if (filters?.status) { query = query.eq('status', filters.status) } if (filters?.limit) { query = query.limit(filters.limit) } const { data, error } = await query if (error) throw new Error(error.message) return data } // Other methods... } ` ### Service Layer Pattern `typescript // Business logic separated from data access class MarketService { constructor(private marketRepo: MarketRepository) {} async searchMarkets(query: string, limit: number = 10): Promise<Market[]> { // Business logic const embedding = await generateEmbedding(query) const results = await this.vectorSearch(embedding, limit) // Fetch full data const markets = await this.marketRepo.findByIds(results.map(r => r.id)) // Sort by similarity return markets.sort((a, b) => { const scoreA = results.find(r => r.id === a.id)?.score || 0 const scoreB = results.find(r => r.id === b.id)?.score || 0 return scoreA - scoreB }) } private async vectorSearch(embedding: number[], limit: number) { // Vector search implementation } } ` ### Middleware Pattern `typescript // Request/response processing pipeline export function withAuth(handler: NextApiHandler): NextApiHandler { return async (req, res) => { const token = req.headers.authorization?.replace('Bearer ', '') if (!token) { return res.status(401).json({ error: 'Unauthorized' }) } try { const user = await verifyToken(token) req.user = user return handler(req, res) } catch (error) { return res.status(401).json({ error: 'Invalid token' }) } } } // Usage export default withAuth(async (req, res) => { // Handler has access to req.user }) ` ## Database Patterns ### Query Optimization `typescript // PASS: GOOD: Select only needed columns const { data } = await supabase .from('markets') .select('id, name, status, volume') .eq('status', 'active') .order('volume', { ascending: false }) .limit(10) // FAIL: BAD: Select everything const { data } = await supabase .from('markets') .select('*') ` ### N+1 Query Prevention `typescript // FAIL: BAD: N+1 query problem const markets = await getMarkets() for (const market of markets) { market.creator = await getUser(market.creator_id) // N queries } // PASS: GOOD: Batch fetch const markets = await getMarkets() const creatorIds = markets.map(m => m.creator_id) const creators = await getUsers(creatorIds) // 1 query const creatorMap = new Map(creators.map(c => [c.id, c])) markets.forEach(market => { market.creator = creatorMap.get(market.creator_id) }) ` ### Transaction Pattern ``typescript async function createMarketWithPosition( marketData: CreateMarketDto, positionData: CreatePositionDto ) { // Use Supabase transaction const { data, error } = await supabase.rpc('createmarketwithposition', { marketdata: marketData, positiondata: positionData }) if (error) throw new Error('Transaction failed') return data } // SQL function in Supabase CREATE OR REPLACE FUNCTION createmarketwithposition( marketdata jsonb, positiondata jsonb ) RETURNS jsonb LANGUAGE plpgsql