06 Infrastructure Design

Infrastructure Design Skill

Use When

• Non-trivial infrastructure quality attributes require topology, capacity, observability, continuity and operating ownership.

Do Not Use When

• Do not use by default for a simple system that fails the score gate, or to name cloud services without verified constraints.

Required Inputs

Workflow

1. Read the named inputs and confirm their approval, version and unresolved decisions.
2. Apply the decision rules below before drafting; stop on a missing authority, unsafe assumption or unresolved scope driver.
3. Produce the Infrastructure Design and decision-gate evidence through the existing domain procedure and load only the references needed for the chosen branch.
4. Trace each material statement in the Infrastructure Design and decision-gate evidence to an input, decision or explicitly qualified assumption.
5. Verify the observable acceptance conditions, record unassessed checks, and hand the artefacts to their named consumers.
6. If validation fails, recover by correcting the source decision or artefact and rerun the affected check; do not weaken the acceptance condition.

Outputs

Evidence Produced

Capability and permission boundaries

Read-only is the default for analysis, review, evaluation and planning. Read and search access to authorised project artefacts are required. Editing is limited to an explicitly requested project deliverable. Execution may run document, syntax or validation checks. Network access is used only for facts that require current verification. Do not publish, spend, change production, approve policy, or claim certification without explicit authority.

Degraded mode

If any required capability is unavailable, return the narrowest useful qualified Infrastructure Design and decision-gate evidence draft plus a gap register showing the missing item, affected sections, risk and owner. Never convert an unassessed check into a pass.

Decision Rules

Quality Standards

• Preserve repository terminology and trace every material choice to project context.
• Use deterministic acceptance conditions; replace vague quality claims with an observable check, threshold or named approval.
• Cover error, empty, edge, recovery and operational cases relevant to this skill.
• Verify standards, citations, APIs and package names before relying on them; qualify what cannot be checked.
• Stop release for a failed safety, security, legal, financial, accessibility or data-integrity gate.

Anti-Patterns

• Copying a reference cloud diagram. Fix: derive topology from workload and failure targets.
• Claiming high availability with one failure domain. Fix: map redundancy and failover tests.
• Sizing from peak guesses. Fix: state workload assumptions and headroom rule.
• Omitting recovery exercises. Fix: define restore and failover evidence.
• Naming alerts without owners. Fix: tie every actionable alert to a runbook and response owner.

References

• Reliability patterns
• Monitoring and observability
• Scalability patterns

Overview

This is the sixth skill in Phase 03 (Design Documentation). It produces an Infrastructure Design document covering scalability, caching, messaging, load balancing, database scaling, reliability patterns, monitoring, and disaster recovery. The skill is optional and gated by a score-based evaluation that determines whether the project's non-functional requirements warrant a dedicated infrastructure document. When the gate score falls below the threshold, infrastructure concerns shall be noted in HLD.md instead.

When to Use

• After 01-high-level-design completes and projects/<ProjectName>/<phase>/<document>/HLD.md exists.
• When projects/<ProjectName>/<phase>/<document>/SRS_Draft.md contains non-functional requirements with measurable availability, scalability, or performance targets.
• When projects/<ProjectName>/_context/tech_stack.md specifies cloud or distributed deployment targets.
• Optionally when projects/<ProjectName>/_context/quality_standards.md defines SLA or compliance constraints.

Quick Reference

Input Files

Output Files

Core Instructions

Follow these steps in order. Halt and notify the user if a required input file is missing.

Step 0: Decision Gate -- Infrastructure Necessity Scoring

Before generating the document, evaluate six criteria against the input files to determine whether a full infrastructure design is warranted.

Scoring Criteria

Scoring Formula

$$Score = \sum_{i=1}^{6} (Weight_i \times YesFlag_i)$$

Where $YesFlag_i = 1$ if the criterion is met, $0$ otherwise.

Maximum possible score: 14 (all criteria met) Minimum possible score: 0 (no criteria met)

Decision Thresholds

Tag all auto-assessed criteria with [AUTO-ASSESSED] and present to the user for confirmation before calculating the final score.

Override Protocol

• Overriding "Not Recommended" to proceed: Log the override. Include a note in the Document Header: "Note: Decision gate score of [X] did not meet the threshold of 4. Generated at user request."
• Overriding "Recommended" to skip: Log the override. Note the skip decision in HLD.md.

Step 1: Read Context Files

Read HLD.md and SRS_Draft.md from projects/<ProjectName>/<phase>/<document>/. Read tech_stack.md from projects/<ProjectName>/_context/. Optionally read quality_standards.md from projects/<ProjectName>/_context/. Log the absolute path of each file read. If any required file is missing, halt execution and report the gap.

Step 2: Scalability Strategy

Analyze the SRS performance requirements and HLD deployment topology to determine the scalability approach.

The system shall document:

• Scaling Direction: Horizontal vs. vertical analysis with rationale citing SRS constraints.
• Auto-Scaling Rules: Define scaling policies using target-tracking, step, or scheduled strategies.
• Scaling Triggers: Specify measurable thresholds:
  • CPU utilization > 70%
  • Memory utilization > 80%
  • Request queue depth > 1,000
  • Response latency p95 > target SLA
• Scaling Limits: Define minimum and maximum instance counts with cost justification.
• Statelessness Requirements: Identify components that shall be stateless for horizontal scaling. Reference references/scalability-patterns.md.

Step 3: Caching Architecture

The system shall define a multi-layer caching strategy aligned with the data flow paths in HLD.md.

Document each cache layer:

The system shall specify:

• Cache invalidation strategy (TTL-based, event-driven, or hybrid)
• Write-through vs. write-behind trade-offs for each layer
• Cache warming procedures for cold-start scenarios
• Thundering herd prevention (locking, probabilistic early expiration)
• Reference references/caching-strategies.md

Step 4: Message Queue / Event Architecture

The system shall define asynchronous processing patterns for decoupled communication.

Document:

• Queue Selection: Criteria for choosing between technologies (RabbitMQ, Apache Kafka, Amazon SQS, Redis Streams) based on ordering guarantees, throughput, and durability requirements.
• Messaging Patterns: Pub/sub, point-to-point, fan-out, or request-reply with rationale.
• Dead Letter Queues (DLQ): Configuration for messages that fail processing after maximum retry attempts.
• Retry Policies: Define retry count, backoff strategy (exponential with jitter), and maximum delay.
• Ordering Guarantees: FIFO vs. best-effort with partition key strategy.
• Event Schema: Versioning strategy (schema registry, backward compatibility).
• Reference references/distributed-systems.md

Step 5: Load Balancing

The system shall define load balancing configuration for each entry point identified in HLD.md.

Document:

• Algorithm Selection: Round-robin, least-connections, IP-hash, or weighted -- with rationale tied to SRS requirements.
• Health Checks: Liveness, readiness, and startup probe definitions with intervals and thresholds.
• Session Persistence: Sticky sessions (when required) with cookie-based or IP-based affinity.
• SSL/TLS Termination: Termination point, certificate management, cipher suite policy.
• Rate Limiting: Request rate limits per client, per endpoint, and global thresholds.

Step 6: Database Scaling

The system shall define database scaling strategy aligned with data models from 04-database-design.

Document:

• Read Replicas: Replica count, replication lag tolerance, read routing strategy.
• Write Scaling: Sharding strategy selection with trade-off analysis:
  • Range-based sharding: ordered access, potential hotspots
  • Hash-based sharding: even distribution, no range queries
  • Directory-based sharding: flexible mapping, single point of failure
• Connection Pooling: Pool size, timeout, idle connection management.
• Query Routing: Read/write splitting logic, consistency requirements for read-after-write.
• Reference references/scalability-patterns.md

Step 7: Reliability Patterns

The system shall define fault tolerance and resilience patterns per ISO 25010 reliability characteristics.

Document each pattern with configuration parameters:

• Circuit Breaker: Open, half-open, and closed states. Define failure threshold (e.g., 5 failures in 30 seconds), reset timeout, and half-open probe count.
• Retry with Exponential Backoff: Base delay, multiplier, jitter range, maximum retries. Formula: $Delay = BaseDelay \times 2^{attempt} + Random(0, Jitter)$
• Idempotency Keys: Key generation strategy, storage TTL, duplicate detection window.
• Bulkhead Isolation: Thread pool or semaphore isolation per downstream dependency. Define pool size and queue capacity.
• Graceful Degradation: Define degradation tiers (full service, reduced features, maintenance mode) with trigger conditions.
• Timeout Strategy: Connect timeout, read timeout, and overall request timeout per dependency.
• Reference references/reliability-patterns.md

Step 8: Monitoring and Observability

The system shall define a comprehensive observability strategy covering metrics, logging, tracing, and alerting.

Metrics

• RED Method (for services): Rate of requests, Error rate, Duration of requests.
• USE Method (for resources): Utilization, Saturation, Errors.
• Define metric collection interval, retention period, and aggregation strategy.

Logging

• Format: Structured JSON with mandatory fields: timestamp, level, service, correlation_id, message, context.
• Levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL with production defaults.
• Correlation IDs: Propagation mechanism across service boundaries.

Distributed Tracing

• Span context propagation (W3C Trace Context or B3).
• Sampling strategy (head-based or tail-based) with sampling rate.

Alerting

Reference references/monitoring-observability.md

Step 9: Disaster Recovery

The system shall define disaster recovery targets and procedures aligned with SRS availability requirements.

Document:

• RPO (Recovery Point Objective): Maximum acceptable data loss measured in time. Derive from SRS Section 3.5.
• RTO (Recovery Time Objective): Maximum acceptable downtime. Derive from SRS Section 3.5.
• Backup Strategy: Frequency, retention, storage location, encryption, restoration testing cadence.
• Failover Procedures: Automatic vs. manual failover, DNS failover TTL, database failover (promote replica).
• Data Replication Topology: Synchronous vs. asynchronous replication, cross-region strategy, conflict resolution for multi-primary.
• DR Testing: Tabletop exercise frequency, failover drill schedule, chaos engineering integration.

Step 10: Generate Traceability Table

Produce a traceability table linking every infrastructure design decision to its originating SRS requirement and HLD component:

| Infrastructure Component | SRS Requirement | HLD Component | Rationale |

Every section from Steps 2-9 shall have at least one entry in this table.

Output Format

The generated Infrastructure_Design.md shall contain these sections in order:

1. Document Header (project name, date, version, standards, decision gate score)
2. Decision Gate Results (scoring worksheet, decision, any overrides)
3. Scalability Strategy
4. Caching Architecture
5. Message Queue / Event Architecture
6. Load Balancing
7. Database Scaling
8. Reliability Patterns
9. Monitoring and Observability (9.1 Metrics, 9.2 Logging, 9.3 Distributed Tracing, 9.4 Alerting)
10. Disaster Recovery
11. Traceability Matrix
12. Appendix A: Glossary

Common Pitfalls

Verification Checklist

• Decision gate evaluation is completed and documented with score.
• Infrastructure_Design.md exists in projects/<ProjectName>/<phase>/<document>/ with all sections populated (if gate passed).
• Scalability strategy specifies measurable auto-scaling triggers and limits.
• Caching architecture covers at least three layers with invalidation strategies.
• Reliability patterns include circuit breaker state definitions and retry formulas.
• Monitoring section defines RED and USE metrics with alerting thresholds.
• DR section specifies RPO/RTO with numeric targets derived from SRS.
• Traceability table maps every infrastructure component to an SRS requirement.

Integration

Standards

• IEEE 1016-2009 Sec 5 -- Architectural design viewpoints and infrastructure design rationale
• ISO/IEC 25010 -- Quality model: reliability, performance efficiency, security characteristics
• ISO/IEC 22237 -- Data centre facilities and infrastructures
• "System Design - The Big Archive" (ByteByteGo 2024) -- Scalability, caching, and distributed systems patterns

Resources

• references/scalability-patterns.md -- Horizontal/vertical scaling, auto-scaling policies, database scaling patterns
• references/distributed-systems.md -- CAP theorem, consistency models, event-driven architecture, message queue patterns
• references/reliability-patterns.md -- Circuit breaker, retry, bulkhead, timeout, health check, graceful degradation
• references/caching-strategies.md -- Cache-aside, read/write-through, multi-layer caching, invalidation strategies
• references/monitoring-observability.md -- RED/USE methods, structured logging, distributed tracing, alerting practices
• README.md -- Quick-start guide for this skill