[dummy-responder] Service Architecture

Version: 1.0
Status: Active Development
Last Updated: August 2025

Introduction and Goals

The [dummy-responder] Service is a lightweight, configurable mock service designed for comprehensive testing and development workflows. It provides simulation capabilities across multiple protocols (HTTP, WebSocket, SSE) with advanced configuration options for realistic testing scenarios.

Requirements Overview

The [dummy-responder] must deliver flexible testing capabilities that enable:

• HTTP Response Simulation: Configurable status codes, delays, failure rates, and content types
• Real-time Protocol Testing: WebSocket and Server-Sent Events for real-time communication testing
• Configuration Flexibility: Multiple configuration methods (CLI, environment, YAML, defaults)
• Development Support: Interactive testing pages, comprehensive API documentation
• Production Readiness: Container deployment, health checks, graceful shutdown
• Configuration Introspection: Runtime configuration visibility and debugging support

Quality Goals

Priority	Quality Goal	Scenario
1	Simplicity	Zero-configuration startup with sensible defaults for immediate use
2	Flexibility	Multi-layered configuration system supporting all common deployment patterns
3	Performance	Handle concurrent requests with minimal resource overhead
4	Reliability	Graceful error handling, proper resource cleanup, and stable operation
5	Configuration Introspection	Runtime configuration visibility, debugging support, and system transparency

Stakeholders

Role	Expectations
Development Teams	Easy integration, realistic testing scenarios, comprehensive documentation
QA Engineers	Reliable failure simulation, edge case testing, repeatable test conditions
DevOps Engineers	Container-ready deployment, Kubernetes integration, operational monitoring
Product Teams	Stable testing environments, consistent behavior across development stages

[dummy-responder] Domain Scope

Architecture Constraints

• Technology Stack: Go for high-performance concurrent request handling
• HTTP Framework: Standard net/http library for minimal dependencies
• Real-time Protocols: golang.org/x/net/websocket for WebSocket support
• Configuration: YAML-based configuration with multi-layer priority system
• Documentation: Auto-generated OpenAPI/Swagger specifications
• Deployment: Container-first design with Kubernetes deployment manifests
• Dependencies: Minimal external dependencies for security and maintainability

Context and Scope

Business Context

Business Context Description:

The [dummy-responder] Service operates as a essential testing infrastructure component within development and QA workflows. It serves multiple user types with distinct testing requirements:

• Development Teams leverage HTTP handlers for API mocking during development, interactive testing pages for manual verification, and comprehensive documentation for integration guidance
• QA Engineers utilize WebSocket and SSE handlers for real-time communication testing, failure simulation capabilities for edge case validation, and repeatable test scenarios for regression testing
• DevOps Teams rely on the configuration system for deployment flexibility, container integration for orchestration, and operational monitoring for production-like testing environments
• Automation Tools integrate with HTTP endpoints for automated testing pipelines, configuration APIs for dynamic test setup, and health checks for service validation

The service integrates with testing infrastructure including Load Testing Tools for performance validation, API Testing Clients for functional testing, CI/CD Pipelines for continuous integration, and Monitoring Systems for operational insights. Documentation components provide comprehensive support through Swagger/OpenAPI interactive documentation, Configuration Reference for setup guidance, User Guides for implementation patterns, and Code Examples for rapid adoption.

Technical Context

Technical Context Description:

The [dummy-responder] Service operates as a multi-protocol Go service providing comprehensive testing capabilities through distinct protocol handlers. It runs as a containerized microservice with flexible deployment options for local development, CI/CD pipelines, and Kubernetes environments.

External clients interact through multiple protocols: Testing Clients (Postman, curl, automated tools) communicate via HTTP/HTTPS for REST API simulation and testing, Web Browsers connect through WebSocket protocols for real-time communication testing and access interactive documentation interfaces, and Load Testing Tools utilize Server-Sent Events for streaming connection validation and performance testing.

The service implements a sophisticated multi-layer configuration system with clear priority ordering: CLI Flags provide highest priority for deployment-specific overrides, Environment Variables offer second priority for container and orchestration integration, YAML Configuration files enable third priority for complex, persistent settings, and Built-in Defaults ensure lowest priority fallback values for all scenarios.

Internal architecture centers on protocol-specific servers: HTTP Server handles REST endpoints with custom response simulation, WebSocket Server manages real-time bidirectional communication, and SSE Server provides unidirectional event streaming. The Configuration Management system coordinates all settings and provides runtime introspection through dedicated endpoints.

Documentation and testing integration occurs through Swagger UI for interactive API exploration, Test Pages for WebSocket and SSE validation, Health Endpoints for service monitoring, and Config Endpoint for runtime configuration visibility and debugging support.

Solution Strategy

Architecture Patterns

Multi-Protocol Service Pattern

• Single service handling HTTP, WebSocket, and SSE protocols
• Protocol-specific handlers with shared configuration system
• Consistent behavior and configuration across all protocols

Layered Configuration Pattern

• CLI flags override environment variables
• Environment variables override configuration files
• Configuration files override built-in defaults
• Runtime introspection for debugging and automation

Self-Documenting Service Pattern

• Auto-generated API documentation with Swagger/OpenAPI
• Interactive testing interfaces for manual validation
• Comprehensive configuration reference and examples

Building Block View

Level 1: System Overview

Level 1 Building Block Description:

The [dummy-responder] Service follows a modular architecture with clear separation of concerns across specialized packages:

• cmd/dummy-responder/main.go serves as the application bootstrap, handling startup sequence, graceful shutdown, route registration, and HTTP server initialization
• internal/config manages the multi-layer configuration hierarchy (CLI → Environment → YAML → Defaults) and provides runtime configuration introspection capabilities
• internal/handlers implements REST API endpoints with configurable response simulation including status codes, delays, failure rates, and content types, plus the interactive test page
• internal/websocket manages real-time bidirectional communication with connection lifecycle management, message streaming, and client management capabilities
• internal/sse provides server-sent event streaming for unidirectional real-time data flow with configurable event intervals and client management
• internal/types defines shared constants and type definitions used across the application for consistency and maintainability
• internal/utils implements utility functions for CORS handling, response delays, random generation, and IP address detection

Limited Logging Implementation

The current implementation provides minimal console output for essential operations only. Extensive structured logging is not implemented. For production environments requiring detailed observability, consider integrating a comprehensive logging framework.

Level 2: Component Details

Level 2 Component Description:

Each building block contains specialized components with distinct responsibilities:

HTTP Handler Components implement a request processing pipeline: Request Router matches incoming URLs to appropriate handlers, Parameter Parser extracts and validates query parameters with type checking, Response Builder constructs HTTP responses based on configuration and parameters, Delay Simulator introduces configurable latency for realistic testing, and Failure Simulator provides probabilistic error injection for resilience testing.

WebSocket Handler Components manage real-time communication: WS Router handles WebSocket upgrade requests and endpoint routing, Connection Manager tracks client connections with proper lifecycle management, Broadcast Manager distributes messages to multiple connected clients, and Echo Handler processes incoming messages with configurable response patterns.

SSE Handler Components provide streaming capabilities: SSE Router manages server-sent event endpoint routing, SSE Connection Manager maintains client streaming connections, Event Generator produces automated events with configurable intervals, and Event Formatter ensures SSE protocol compliance with proper headers and formatting.

Configuration Components implement the multi-layer configuration system: CLI Parser processes command-line arguments with validation, Environment Reader loads configuration from environment variables, YAML Loader parses configuration files with schema validation, Config Merger combines all sources with proper priority handling, and Config Validator ensures configuration consistency with sensible defaults.

Runtime View

Scenario 1: HTTP Request Processing with Configuration

Scenario 2: WebSocket Real-time Communication

Scenario 3: Server-Sent Events Streaming

Scenario 4: Configuration Management Lifecycle

Deployment View

Container Infrastructure

Kubernetes Deployment Architecture

Kubernetes Deployment Description:

The [dummy-responder] deploys as a highly available service across multiple Kubernetes pods with automatic scaling and health monitoring. The deployment follows cloud-native patterns:

Pod Architecture: Each pod runs a single dummy-responder container with minimal resource requirements, enabling dense packing and efficient resource utilization across the cluster.

Service Layer: A ClusterIP service provides internal load balancing across all healthy pods, while an Ingress controller manages external traffic routing with SSL termination and path-based routing.

Configuration Management: ConfigMaps store non-sensitive configuration including default response settings and protocol configurations, while Secrets manage sensitive data like TLS certificates and authentication tokens.

Monitoring Integration: ServiceMonitor resources enable Prometheus to automatically discover and scrape metrics from all service instances, providing comprehensive observability.

Multi-Environment Deployment Strategy

Multi-Environment Strategy Description:

The deployment pipeline progresses through four distinct environments with increasing production-readiness:

Development Environment supports rapid iteration with local binary execution for immediate feedback and Docker Compose for container behavior validation.

Testing Environment runs on a dedicated Kubernetes cluster for feature validation with comprehensive integration test suites covering all protocols and configuration scenarios.

Staging Environment provides production simulation with identical infrastructure configuration, enabling load testing and performance validation under realistic conditions.

Production Environment delivers the live service with comprehensive monitoring, alerting, and operational dashboards for service reliability and performance tracking.

Cross-cutting Concepts

Configuration Management Strategy

Observability and Debugging Strategy

Limited Logging Implementation

The current implementation provides minimal console output for essential operations only. The service focuses on simplicity and lightweight operation. For production environments requiring detailed observability, consider integrating structured logging frameworks.

Current Output Capabilities:

• Basic startup and shutdown messages
• Configuration loading status
• Critical error reporting
• Service health indicators

Debugging Support:

• /config endpoint for runtime configuration introspection
• Interactive test pages for manual validation
• Configuration file generation for troubleshooting
• Health check endpoints for monitoring

Future Enhancement Opportunities:

• Structured JSON logging for request/response details
• Metrics collection for performance monitoring
• Distributed tracing for complex scenarios
• Log aggregation integration for production deployments

Error Handling Strategy

Architecture Decisions

ADR-001: Configuration Priority System

Status: Accepted
Date: August 2025

Context: Multiple configuration sources needed (CLI, environment, files) with clear precedence rules.

Decision: Implement layered configuration with priority order: CLI flags > Environment variables > YAML files > Built-in defaults.

Consequences:

• ✅ Flexible deployment across all environments
• ✅ Clear override behavior for operators
• ✅ Backwards compatible with simple usage
• ⚠️ Requires careful documentation of priority rules

ADR-002: Multi-Protocol Support in Single Service

Status: Accepted
Date: August 2025

Context: Need to test HTTP, WebSocket, and SSE protocols without deploying multiple services.

Decision: Implement all protocols in single Go service with shared configuration and state.

Consequences:

• ✅ Simplified deployment and management
• ✅ Consistent configuration across protocols
• ✅ Reduced resource overhead
• ⚠️ Increased complexity in single binary

ADR-003: Swagger/OpenAPI Documentation

Status: Accepted
Date: August 2025

Context: Need interactive API documentation for development and testing teams.

Decision: Integrate swaggo/swag for automatic OpenAPI specification generation from code annotations.

Consequences:

• ✅ Self-documenting API with code changes
• ✅ Interactive testing interface
• ✅ Industry-standard documentation format
• ⚠️ Additional build step and dependencies

Quality Requirements

Performance Requirements

Requirement	Target	Measurement Method
Request Latency	< 10ms baseline (excluding simulated delays)	HTTP request timing
Concurrent Connections	Support 1000+ concurrent HTTP connections	Load testing with k6
WebSocket Throughput	Handle 100+ concurrent WebSocket connections	Connection stress testing
Memory Usage	< 50MB baseline memory footprint	Resource monitoring
CPU Usage	< 10% CPU under normal load	Performance profiling

Reliability Requirements

Requirement	Target	Measurement Method
Uptime	99.9% availability during testing periods	Health check monitoring
Graceful Shutdown	< 5 seconds for clean shutdown	Termination testing
Error Recovery	Automatic recovery from transient failures	Failure injection testing
Configuration Validation	100% of invalid configs rejected with clear messages	Configuration testing

Security Requirements

Requirement	Implementation	Validation Method
Input Validation	Sanitize all query parameters and WebSocket messages	Security testing
Resource Limits	Implement connection limits and rate limiting	Abuse testing
No Sensitive Data	No storage or logging of sensitive information	Code review
Container Security	Minimal attack surface, non-root execution	Security scanning

Error Handling

Configuration Management

Parameter	Source	Default	Description
PORT	Environment	8080	HTTP server port
status	Query Parameter	200	HTTP response status
delay	Query Parameter	0	Response delay
content-type	Query Parameter	text/plain	Response content type
failure-rate	Query Parameter	0	Failure simulation percentage

Design Decisions

ADR-001: Use Standard Library HTTP Server

Status: Accepted

Context: Need performant, reliable HTTP server with minimal dependencies.

Decision: Use Go's standard net/http library.

Consequences:

• ✅ Zero external dependencies for HTTP
• ✅ Battle-tested, well-documented
• ✅ Excellent performance characteristics
• ❌ More verbose than some frameworks

ADR-002: Parameter-Based Configuration

Status: Accepted

Context: Need flexible configuration without complex setup files.

Decision: Use query parameters and environment variables for configuration.

Consequences:

• ✅ Zero-configuration startup
• ✅ Easy to use in tests and scripts
• ✅ Self-documenting through URL structure
• ❌ Limited nested configuration support

ADR-003: Single Binary Distribution

Status: Accepted

Context: Need easy deployment across different environments.

Decision: Compile to single, self-contained binary.

Consequences:

• ✅ Simple deployment and distribution
• ✅ No runtime dependencies
• ✅ Fast startup times
• ❌ Larger binary size

Quality Requirements

Performance

Requirement	Target	Measurement
Response Time	< 10ms (without delay)	p95 latency
Throughput	> 1000 req/s	Concurrent connections
Memory Usage	< 50MB	Steady state
CPU Usage	< 5%	Idle state

Reliability

Requirement	Target	Strategy
Uptime	99.9%	Graceful error handling
Error Rate	< 0.1%	Comprehensive testing
Recovery Time	< 30s	Health checks

Security

Aspect	Implementation
Input Validation	Parameter sanitization
Resource Limits	Connection limits, timeouts
Information Disclosure	Minimal error responses
DoS Protection	Rate limiting considerations

Risks and Technical Debt

Known Risks

Risk	Probability	Impact	Mitigation
Memory Leaks	Low	High	Connection cleanup, testing
DoS Attacks	Medium	Medium	Rate limiting, monitoring
Protocol Upgrades	Low	Low	Versioned API, backward compatibility

Technical Debt

Item	Priority	Effort	Plan
Metrics Endpoint	Medium	Small	Add Prometheus metrics
Configuration File	Low	Medium	YAML/JSON config support
Rate Limiting	Medium	Medium	Token bucket implementation

Glossary

Term	Definition
[dummy-responder]	The main service providing configurable mock responses
SSE	Server-Sent Events - HTTP-based event streaming
Failure Rate	Percentage of requests that should return error responses
WebSocket	Full-duplex communication protocol over HTTP
Mock Service	A service that simulates real service behavior for testing

---

Document Information:

• Architecture Framework: arc42 Template
• Version: 1.0
• Authors: [bjoernbartels.earth]
• Review Status: Current