Solutions Architecture: End-to-End Capability Delivery

Solutions architecture designs the complete system that solves a business problem — how multiple systems connect, how users interact, how data flows, how security is enforced, and how the solution is observed and operated. It bridges business requirements and technical implementation. [EXPLICIT]

Principio Rector

Una solución es más que la suma de sus sistemas. La arquitectura de solución diseña cómo múltiples componentes — APIs, canales, identidad, datos, observabilidad — se integran para resolver un problema de negocio completo. Cada integración es un contrato. Cada contrato es un punto de fallo. Cada punto de fallo necesita un plan B.

Filosofía de Solución End-to-End

1. Integration-first thinking. Los sistemas individuales funcionan solos; la solución falla en las costuras. El foco está en los puntos de conexión. [EXPLICIT]
2. Zero Trust by default. Cada servicio verifica, cada canal autentica, cada dato se cifra en tránsito y reposo. La seguridad no es un layer — es una propiedad. [EXPLICIT]
3. Observable antes que operacional. Si no se puede observar, no se puede operar. Logging, tracing, y metrics se diseñan junto con la funcionalidad, no después. [EXPLICIT]

Inputs

The user provides a system or project name as $ARGUMENTS. Parse $1 as the solution/project name used throughout all output artifacts. [EXPLICIT]

Parameters:

• {MODO}: piloto-auto (default) | desatendido | supervisado | paso-a-paso
  • piloto-auto: Auto para solution view y integration patterns, HITL para security model y transition plan. [EXPLICIT]
  • desatendido: Cero interrupciones. Arquitectura de solución documentada automáticamente. Supuestos documentados. [EXPLICIT]
  • supervisado: Autónomo con checkpoint en integration architecture y identity model. [EXPLICIT]
  • paso-a-paso: Confirma cada container, integration pattern, security decision, y observability config. [EXPLICIT]
• {FORMATO}: markdown (default) | html | dual
• {VARIANTE}: ejecutiva (~40% — S1 solution view + S2 integration + S4 security) | técnica (full 7 sections, default)

Before generating architecture, detect the codebase context:

!find . -name "*.ts" -o -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.yaml" | head -30

If reference materials exist, load them:

Read ${CLAUDE_SKILL_DIR}/references/solutions-arch-patterns.md

When to Use

• Designing complete solutions spanning multiple systems, services, or platforms
• Defining integration architecture between legacy and new systems
• Designing channel strategy (web, mobile, API, omnichannel)
• Planning identity and access management across the solution
• Establishing observability (logging, metrics, tracing)
• Addressing cross-cutting concerns (caching, rate limiting, retry, timeouts, feature flags)
• Planning migration from current state to target state
• Supporting RFP responses with architecture justification

When NOT to Use

• Internal software structure only → software-architecture
• Enterprise portfolio alignment and capability mapping → enterprise-architecture
• Infrastructure, compute, and platform design → infrastructure-architecture
• Build pipelines and security controls → devsecops-architecture

Delivery Structure: 7 Sections

S1: Solution View (C4 Containers)

High-level diagram showing all systems, boundaries, external dependencies, and integration points. [EXPLICIT]

Includes:

• C4 Container diagram: independent deployable components
• External systems: upstream sources, downstream consumers, third-party services
• User actors: internal staff, customers, integrations, admins
• Data stores: databases, caches, file storage
• Communication: APIs, message queues, event streams, sync/async patterns

Key decisions:

• System boundary: what's inside solution, what's external
• Container granularity: right size for independent deployment
• Communication protocol: REST, gRPC, message queues, webhooks
• Synchronous vs. asynchronous: latency and coupling trade-offs

S2: Integration Architecture

How systems connect, exchange data, and coordinate. [EXPLICIT]

Includes:

• API Gateway: entry point, routing, rate limiting, request transformation
• Message Broker / Event Bus: async communication, event publishing, subscriptions
• Synchronous Patterns: REST, gRPC, direct DB access, service-to-service
• Asynchronous Patterns: event sourcing, saga, eventual consistency, event streams
• Data Consistency: strong vs. eventual, CAP theorem, distributed transactions
• Protocols: HTTP/REST, gRPC, AMQP, Kafka, webhooks, polling, CDC

Trade-offs:

• REST (simple) vs. gRPC (high performance, streaming)
• Synchronous (immediate consistency) vs. async (decoupling)
• Message broker (reliability, ordering) vs. event stream (replay, temporal)
• Point-to-point (simple, tight coupling) vs. pub-sub (decoupling, broadcast)

S3: Channel & BFF Architecture

How end-users and external systems interact with the solution. [EXPLICIT]

Includes:

• Web Channel: SPA, PWA, browser-based
• Mobile Channel: native, cross-platform, offline capability
• API Channel: REST, GraphQL, gRPC for programmatic access
• Backend for Frontend (BFF): separate API layer per channel
• Omnichannel: session state, user identity, consistent experience
• Legacy Integration: existing channels remain supported

Key decisions:

• Single API for all channels vs. BFF per channel (simplicity vs. optimization)
• Thin client vs. fat client (consistency vs. responsiveness)
• Stateful vs. stateless (session management, scalability)
• Offline support (PWA, mobile sync)

S4: Identity & Security (Zero Trust)

How users are authenticated, authorized, and how data is protected. [EXPLICIT]

Authentication (AuthN):

• OAuth2/OIDC (industry standard, delegated), SAML (enterprise federation)
• MFA, passwordless (biometric, hardware keys)

Authorization (AuthZ):

• RBAC (coarse-grained), ABAC (fine-grained, context-aware), Policy-as-Code

Zero Trust:

• Every request authenticated and authorized
• Encryption in transit (TLS 1.2+) and at rest
• Minimal privilege, segmentation (network, data, application)

API Security:

• OAuth2 client credentials (recommended), mTLS (zero trust), JWT verification

Data Protection:

• Tokenization/masking of PII, data classification (public/internal/confidential/restricted)
• Compliance mapping: GDPR, PCI-DSS, HIPAA, SOX, local regulations
• Data residency, retention, deletion, audit trails

S5: Observability (SLI/SLO)

How the solution is monitored, debugged, and operated in production. [EXPLICIT]

Logging: Structured, centralized, correlation IDs, retention policy Metrics: Application (RPS, error rate, latency p50/p95/p99), infrastructure (CPU, memory), business (transactions, revenue) Tracing: OpenTelemetry, trace spans, sampling strategy Alerting: Conditions, on-call escalation, alert fatigue management Dashboards: Executive (business), operational (latency, errors), debugging (traces, slow queries)

SLI/SLO/SLA:

• SLI: measured metric (e.g., 99.9% uptime)
• SLO: target for SLI (commit to 99.95%)
• SLA: contractual consequence if SLO missed

S6: Cross-Cutting Concerns

Technical patterns applied across multiple components. [EXPLICIT]

• Caching: HTTP cache, application (Redis), database; invalidation (TTL, event-based); stampede/penetration risks
• Rate Limiting: Per-user/IP/API-key; token bucket, leaky bucket; graceful degradation vs. rejection
• Circuit Breaker: Closed/Open/Half-Open states; trip conditions; reset timeout
• Retry & Timeout: Exponential backoff + jitter; max retries; idempotency for safe retry
• Bulkhead/Isolation: Thread pools per component; separate DB connections; request timeout per subsystem
• Feature Flags: Environment-based, user/cohort-based, time-based; remote configuration
• Configuration Management: Secrets (encrypted, rotated, least privilege); non-secrets (version-controlled); tools (Vault, AWS Secrets Manager)

S7: Transition Plan

How to move from current state to target state without disrupting operations. [EXPLICIT]

Migration Strategy: Strangler fig, parallel running, cutover (flag day vs. phased), rollback plan Data Migration: Schema evolution, dual-write, verification (checksums, counts), rollback Phased Rollout: Dark launch -> canary 5% -> 25% -> 50% -> 100%; rollback criteria Team Readiness: Documentation, training, on-call, capacity planning Risk Management: Data loss (backup, RTO), service unavailability, performance degradation, security exposure, compliance approval

Trade-off Matrix

Assumptions

• Business requirements gathered and prioritized (from discovery)
• User journeys and personas understood
• Quality attributes (performance, availability, security) defined
• Technology choices roughly scoped (cloud provider, languages, databases)
• Team has infrastructure and tooling access (or migration path)
• Regulatory constraints known (GDPR, PCI, HIPAA, local laws)

Limits

• Does not design internal software structure of individual systems (see software-architecture)
• Does not design enterprise governance or capability mapping (see enterprise-architecture)
• Does not detail infrastructure topology or cloud landing zones (see infrastructure-architecture)
• Does not design CI/CD pipelines or supply chain security (see devsecops-architecture)
• Assumes systems being integrated are brownfield or have architecture designed separately

Edge Cases

Greenfield Multi-System Solution: No existing integration patterns. Risk: over-designing for scale that doesn't exist. Start simple (sync APIs), add async/caching when metrics show need. [EXPLICIT]

Legacy Mainframe Integration: Impedance mismatch (batch vs. real-time, EBCDIC vs. UTF-8, CICS vs. REST). Solution: integration layer (adapter, translator), strangler fig, eventual retirement timeline. [EXPLICIT]

High-Latency or Unreliable Networks: Offline-first architecture required: local cache, sync when connected. Conflict resolution for eventual consistency. [EXPLICIT]

Real-Time, Low-Latency Requirements: Financial trading, gaming, autonomous systems. Synchronous preferred; async trade-offs documented. Infrastructure must support global distribution and failover. [EXPLICIT]

Highly Regulated System: GDPR, HIPAA, PCI-DSS, SOX: compliance non-negotiable. Every decision maps to compliance requirement. Audit trails, encryption, data residency, consent management built-in from start. [EXPLICIT]

Validation Gate

Before finalizing delivery, verify:

• All systems in scope identified and mapped
• Integration patterns explicit (sync, async, polling, CDC)
• Security model covers authentication, authorization, encryption, compliance
• Observability stack designed (logging, metrics, tracing, alerting)
• Cross-cutting concerns addressed (caching, rate limiting, circuit breakers)
• Multi-channel strategy clear (web, mobile, API, consistency)
• Data flow documented (what moves where, consistency model)
• Migration path phased, low-risk, with rollback options
• Assumptions explicit; risks identified and mitigated
• Technical teams can implement; operations can run and debug

Cross-References

• software-architecture: Each system has internal architecture; decisions here constrain that
• infrastructure-architecture: Infrastructure must support integration patterns, security, observability
• devsecops-architecture: Pipeline validates integration contracts, security gates, compliance
• enterprise-architecture: Solution must fit enterprise capability map and technology radar

Output Format Protocol

Default output is Markdown with embedded Mermaid diagrams. HTML generation requires explicit {FORMATO}=html parameter. [EXPLICIT]

Output Artifact

Primary: A-02_Solutions_Architecture_Deep.html — Executive summary, solution view, integration architecture, channel architecture, identity/security, observability, cross-cutting concerns, transition plan.

Secondary: C4 diagram (PNG/SVG), integration contract specs, observability config templates, security checklist, transition runbooks.

Author: toolkit contributors | Last updated: 2026-03-18