software-architecture

Define backend service architecture with bounded contexts and API conventions.

1|Updated Mar 18, 2024
One-click install
npx skills add https://github.com/erfianugrah/dotfiles --skill software-architecture-erfianugrah
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: software-architecture
Source: https://github.com/erfianugrah/dotfiles/tree/main/.pi/agent/skills/software-architecture
Command: npx skills add https://github.com/erfianugrah/dotfiles --skill software-architecture-erfianugrah

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you avoid brittle, tangled service code by providing a consistent system shape for backend services and full-stack apps, including module boundaries, API contracts, persistence choices, and observability standards.

Core Features & Use Cases

  • Bounded contexts (DDD-lite): Organizes code by business concept so features remain cohesive, testable, and changeable without cross-cutting refactors.
  • API surface conventions (REST + WS): Defines routing, state transitions, correlation IDs, and a reliable WebSocket event envelope with replay safety.
  • Persistence + observability defaults: Establishes Postgres-first persistence with sqlc/goose patterns, optional Valkey hot-path caching with in-process fallbacks, and standardized slog/Prometheus request metrics plus error-handling rules.

Quick Start

Use the software-architecture skill to draft the architecture skeleton for your new backend service and specify REST routes, WebSocket envelopes, bounded contexts, and persistence/observability conventions for a coherent system shape.

Frequently Asked Questions about software-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure backend services to prevent ad-hoc module coupling?

To prevent ad-hoc module coupling, structure backend services using bounded contexts to organize code by business concept, ensuring features remain cohesive and testable without cross-cutting refactors. This approach establishes clear module boundaries and interface-driven cross-context dependencies.

What is the best way to design REST and WebSocket API surfaces with durable conventions?

The best way to design REST and WebSocket API surfaces is to establish durable conventions for data flow, including routing, state transitions, correlation IDs, and a reliable WebSocket event envelope with replay safety to ensure consistent communication across backend services.

How does correlation-ID logging and Prometheus metrics work for backend observability?

Correlation-ID logging and Prometheus metrics work together to provide backend observability by tracing requests across service boundaries and capturing standardized request metrics. This combination enables tracking data flow and diagnosing errors within distributed system architectures.

When do I need bounded context organization for my full-stack app?

You need bounded context organization when starting a new backend service or refactoring module boundaries in a full-stack app. It prevents tangled service code by grouping features by business concept, keeping modules testable and changeable without triggering cross-cutting refactors.

Can I use Postgres migrations with Valkey caching without breaking data flow?

Yes, you can use Postgres-first persistence with sqlc/goose migration patterns alongside optional Valkey hot-path caching. The architecture includes in-process fallbacks to ensure data flow remains durable and consistent even if the caching layer becomes unavailable.

Why does structured error handling require an async escalation model in system design?

Structured error handling requires an async escalation model to manage fault tolerance across distributed boundaries. This architecture pattern prevents brittle service code by standardizing how errors are logged, propagated, and escalated asynchronously without blocking core data flow.