Backend Development

Backend engineering guidance for Node.js/TypeScript and Go projects. Covers everything from adding a small feature to designing a new microservice — including vague tasks where you need to figure out the right approach from context.

Related Skills:

• kavak-documentation — for Kavak-specific patterns (kbroker, STS, GitLab CI, Docker)
• test-driven-development — use for new features and bug fixes (Red-Green-Refactor)
• Check .claude/CLAUDE.md or .cursor/rules/* for project-specific conventions

MCP: Use kavak-platform/platform_docs_search to query Kavak internal docs and kavak-platform/search_resource for workload/infrastructure info before implementing.

First: Understand the Codebase

Before writing any code, explore the project to understand its structure, patterns, and existing implementations. This matters because the biggest source of wasted effort is reimplementing something that already exists — or writing code that clashes with the project's established patterns.

1. Read the project structure — identify the architecture, naming conventions, and patterns in use
2. Search for similar code — extract keywords from your task (verbs, nouns, domain concepts) and search. You're looking for code you can reuse, extend, or extract shared logic from
3. Document your reuse decision — REUSE (>70% similar), EXTEND (50-70%), EXTRACT (shared helper), or NEW (<30% similar)

Full process, search templates, and decision matrix: references/code-reuse-analysis.md

Core Principles

Architecture: Clean Architecture (4-layer) for new projects → references/architecture.md

• SOLID — each module does one thing, depends on abstractions not implementations
• DRY — every piece of business logic has ONE source of truth → references/dry-detection.md
• YAGNI — only build what the task requires right now, not hypothetical future needs
• KISS — the simplest solution that works is the right one

Code should be self-documenting. Comments explain "why", not "what". See references/code-quality.md for examples.

Existing Projects Rule

Follow the project's established patterns — if it uses flat structure, keep flat structure. If it uses callbacks, use callbacks. Don't force Clean Architecture on a codebase that doesn't use it. Apply good practices to new code you write, but match the project's conventions.

Clean Architecture applies to: new greenfield projects, new modules (when it fits), or explicit refactoring requests.

Quick Start

Language	Test	Lint
Node/TS	npm test	npm run lint
Go	go test ./...	golangci-lint run

Technology Selection

Need	Choose
TypeScript API	NestJS
High concurrency	Go + Chi
Go database	pgx/v5 + sqlc
Node database	Drizzle (new), keep existing
Go Redis	rueidis (new), keep existing
Go job queue	River (PostgreSQL-backed)
Node job queue	pg-boss (PostgreSQL-backed)
Events (Kavak)	kbroker (Kafka-by-REST)
Rate limiting	pg-boss throttle / River snooze
Testing	Vitest (new Node), Jest (existing)
Tracing	OpenTelemetry + dd-trace

Note: Use kbroker for events between services. Use pg-boss (Node) or River (Go) for job queues.

Common Workflows

New API Endpoint (TDD Approach)

Use test-driven-development skill for Red-Green-Refactor cycle

1. Write failing test first → test-driven-development skill
2. Design endpoint → references/api-design.md
3. Set up handler → references/go/http-handlers.md or references/node/frameworks.md
4. Add database access → references/go/database.md or references/node/database.md
5. Implement auth → references/authentication.md
6. Refactor with tests passing → references/code-quality.md

Add Similar Feature (DRY-First)

When the task says "do X like Y" or "add similar to existing":

1. Find the existing implementation first — search for the feature mentioned
2. >70% similar: inject existing service, call its method (5-10 lines)
3. 50-70% similar: extract shared helper, refactor both old and new to use it
4. <50% similar: OK to create new, keep it minimal
5. Test both old and new paths — ensure refactoring didn't break existing

If your new code exceeds 50 lines, you likely missed a reuse opportunity.

Fix Slow Query

1. Profile query → references/debugging.md (EXPLAIN ANALYZE)
2. Add indexes → references/performance.md
3. Add caching → references/go/redis-queues.md or references/node/database.md

Deploy New Service

1. Write Dockerfile → references/devops/docker.md
2. Set up CI/CD → references/devops/ci-cd.md

Debug Production Issue

1. Check logs/traces → references/debugging.md
2. Profile if slow → references/debugging.md (pprof/clinic.js)
3. Check DB queries → references/debugging.md (pg_stat_statements)

References

Reference	When to Use
Go
references/go/http-handlers.md	Set up Chi routes, handlers, middleware
references/go/database.md	Implement pgx/v5, sqlc queries
references/go/patterns.md	Apply error handling, validation, testing
references/go/redis-queues.md	Add rueidis caching, River job queue
Node.js
references/node/frameworks.md	Set up NestJS, Express, Fastify
references/node/database.md	Implement Drizzle, Prisma, caching
references/node/patterns.md	Apply validation, errors, testing
DevOps
references/devops/docker.md	Write Dockerfiles, compose, health checks, DataDog metrics
references/devops/ci-cd.md	Configure GitLab CI pipelines
Cross-Cutting
references/architecture.md	Clean Architecture (4-layer), microservices, events
references/code-quality.md	SOLID, DRY, YAGNI, KISS, design patterns
references/code-reuse-analysis.md	MANDATORY - Code reuse gate, decision matrix
references/dry-detection.md	MANDATORY - DRY detection, code reuse patterns
references/api-design.md	Design REST endpoints, versioning
references/authentication.md	Implement OAuth 2.1, JWT, RBAC
references/security.md	Apply OWASP Top 10, input validation
references/performance.md	Optimize caching, queries, pooling
references/testing.md	Write unit, integration, E2E tests
references/debugging.md	Debug with logs, profilers, tracing
Kavak
references/kavak/kbroker.md	Publish/subscribe events between services
references/kavak/queues-ratelimit.md	Job queues, rate limiting with River/pg-boss
references/kavak/microservice-auth.md	Authenticate between services (STS)
references/kavak/gitlab-ci.md	Set up kavak-it/ci-jobs v3 pipelines
references/kavak/docker-images.md	Build with docker-debian base
references/kavak/workload-config.md	Configure .kavak/ dir, cron jobs
references/kavak/logging-metrics.md	Use kvklog, kvkmetric SDKs