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

Technology Selection

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