system-design-primer-skill 1.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +106 -60
  2. package/SKILL.md +417 -93
  3. package/VERSION +1 -1
  4. package/package.json +44 -3
  5. package/references/10-workflows-and-checklists.md +1 -1
  6. package/references/13-architecture-intelligence.md +91 -0
  7. package/references/14-api-and-data-contracts.md +80 -0
  8. package/references/15-failure-analysis.md +84 -0
  9. package/references/16-multi-agent-architecture.md +76 -0
  10. package/references/17-agent-harness-and-runtime.md +87 -0
  11. package/references/18-mcp-architecture.md +67 -0
  12. package/references/19-agent-security-and-permissions.md +74 -0
  13. package/references/20-agent-state-and-memory.md +72 -0
  14. package/references/21-agent-evaluation-and-observability.md +90 -0
  15. package/references/22-kubernetes-and-container-platforms.md +29 -0
  16. package/references/23-service-mesh-and-traffic-management.md +21 -0
  17. package/references/24-multi-region-and-disaster-recovery.md +24 -0
  18. package/references/25-platform-engineering-and-developer-experience.md +26 -0
  19. package/references/26-finops-and-cloud-cost.md +29 -0
  20. package/references/27-production-observability-and-slo.md +29 -0
  21. package/references/28-event-streaming-and-kafka-pulsar.md +27 -0
  22. package/references/29-event-sourcing-and-cqrs.md +23 -0
  23. package/references/30-change-data-capture-and-debezium.md +27 -0
  24. package/references/31-data-lakehouse-and-stream-batch.md +24 -0
  25. package/references/32-workflow-orchestration-and-temporal.md +24 -0
  26. package/references/33-schema-registry-and-event-governance.md +22 -0
  27. package/references/34-postgresql-internals-and-performance.md +43 -0
  28. package/references/35-mysql-innodb-and-performance.md +27 -0
  29. package/references/36-sharding-and-distributed-sql.md +22 -0
  30. package/references/37-consensus-and-distributed-transactions.md +25 -0
  31. package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
  32. package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
  33. package/references/40-zero-downtime-database-migrations.md +27 -0
  34. package/references/41-api-gateway-and-edge-architecture.md +23 -0
  35. package/references/42-rest-api-design-and-lifecycle.md +23 -0
  36. package/references/43-graphql-architecture-and-governance.md +16 -0
  37. package/references/44-grpc-and-service-contracts.md +16 -0
  38. package/references/45-websocket-sse-and-realtime-systems.md +16 -0
  39. package/references/46-realtime-collaboration-ot-crdt.md +16 -0
  40. package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
  41. package/references/48-oauth-oidc-and-passkeys.md +20 -0
  42. package/references/49-iam-rbac-abac-rebac.md +16 -0
  43. package/references/50-zero-trust-and-workload-identity.md +16 -0
  44. package/references/51-secrets-kms-pki-and-key-management.md +16 -0
  45. package/references/52-supply-chain-security-sbom-slsa.md +16 -0
  46. package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
  47. package/references/54-privacy-engineering-and-data-governance.md +16 -0
  48. package/references/55-opentelemetry-and-instrumentation.md +50 -0
  49. package/references/56-distributed-tracing-and-context-propagation.md +43 -0
  50. package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
  51. package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
  52. package/references/59-capacity-planning-and-performance-modeling.md +34 -0
  53. package/references/60-chaos-engineering-and-resilience-experiments.md +41 -0
  54. package/references/61-incident-management-and-postmortems.md +34 -0
  55. package/references/62-dns-and-service-discovery.md +35 -0
  56. package/references/63-load-balancing-and-global-traffic-management.md +31 -0
  57. package/references/64-cdn-and-edge-caching.md +34 -0
  58. package/references/65-cloud-networking-and-connectivity.md +34 -0
  59. package/references/66-edge-computing-architecture.md +33 -0
  60. package/references/67-storage-infrastructure-and-storage-systems.md +30 -0
  61. package/references/68-tcp-quic-and-network-performance.md +27 -0
  62. package/references/69-task-routing-and-evidence.md +58 -0
  63. package/scripts/install.ps1 +10 -1
  64. package/scripts/install.sh +13 -6
  65. package/scripts/validate.py +133 -0
  66. package/templates/agent-evaluation-plan-template.md +57 -0
  67. package/templates/agent-security-review-template.md +46 -0
  68. package/templates/agent-system-design-template.md +74 -0
  69. package/templates/api-architecture-design-template.md +33 -0
  70. package/templates/api-security-and-rate-limit-review-template.md +29 -0
  71. package/templates/architecture-decision-matrix-template.md +48 -0
  72. package/templates/architecture-review-scorecard-template.md +36 -0
  73. package/templates/cdc-data-pipeline-template.md +41 -0
  74. package/templates/cdn-and-edge-strategy-template.md +36 -0
  75. package/templates/chaos-experiment-template.md +39 -0
  76. package/templates/cloud-cost-model-template.md +37 -0
  77. package/templates/database-architecture-review-template.md +33 -0
  78. package/templates/edge-computing-readiness-template.md +36 -0
  79. package/templates/event-sourcing-cqrs-template.md +41 -0
  80. package/templates/event-streaming-design-template.md +47 -0
  81. package/templates/failure-analysis-template.md +36 -0
  82. package/templates/identity-and-access-architecture-template.md +29 -0
  83. package/templates/incident-postmortem-template.md +39 -0
  84. package/templates/multi-region-disaster-recovery-template.md +43 -0
  85. package/templates/network-architecture-design-template.md +38 -0
  86. package/templates/observability-architecture-template.md +52 -0
  87. package/templates/performance-test-plan-template.md +52 -0
  88. package/templates/privacy-data-governance-template.md +24 -0
  89. package/templates/production-readiness-checklist-template.md +52 -0
  90. package/templates/realtime-system-design-template.md +28 -0
  91. package/templates/security-threat-model-template.md +26 -0
  92. package/templates/sharding-distributed-sql-design-template.md +34 -0
  93. package/templates/storage-architecture-design-template.md +35 -0
  94. package/templates/supply-chain-security-review-template.md +20 -0
  95. package/templates/zero-downtime-database-migration-template.md +32 -0
@@ -0,0 +1,34 @@
1
+ # Capacity Planning and Performance Modeling
2
+
3
+ ## Planning inputs
4
+ Use measured traffic and growth where available. Record average/peak arrival rates, concurrency, request mix, payload sizes, CPU time/request, memory/request, database queries/request, connection occupancy, queue arrival/service rates, storage growth, replication, retention, and failure scenarios. Mark forecasts and assumptions explicitly.
5
+
6
+ ## Capacity model
7
+ - Little's Law: L = λW, where L is average in-system work, λ is throughput, and W is average time in the system. Apply only to a stable observation window with consistent boundaries.
8
+ - CPU demand: approximate cores required as throughput × CPU-seconds/request; add measured headroom and account for throttling and burst behavior.
9
+ - Connection demand: estimate concurrency from arrival rate × connection occupancy time; validate pool limits and downstream capacity.
10
+ - Queue stability: sustained arrival rate must remain below sustainable service rate. Model burst recovery and backlog drain time.
11
+ - Storage: model logical growth, indexes, replicas, WAL/binlogs, backups, retention, compaction, and migration headroom separately.
12
+ - Network: include payload, protocol/TLS overhead, retries, replication, telemetry, and cross-zone/region traffic.
13
+
14
+ ## Bottleneck and headroom
15
+ - Find the first constrained resource across the full dependency chain; scaling stateless application replicas may simply move the bottleneck to the database or a shared service.
16
+ - Define safe operating envelopes using SLOs, not theoretical maximum throughput.
17
+ - Include N+1 failure capacity, rolling deployments, zone loss, and maintenance events where required.
18
+ - Model autoscaling detection and provisioning delay; reactive scaling cannot prevent every burst.
19
+ - Evaluate vertical, horizontal, queue-based, and workload-shaping options before introducing partitioning or sharding.
20
+
21
+ ## Sensitivity and uncertainty
22
+ Build low/base/high scenarios for growth, peak factors, request mix, retry amplification, payload size, and dependency latency.
23
+ Show which assumptions dominate the result and which measurements would reduce uncertainty.
24
+ Do not convert benchmark throughput into production capacity without accounting for workload differences, failure headroom, and SLO limits.
25
+
26
+ ## Operational planning
27
+ Define thresholds and owners for scaling, load shedding, admission control, queue limits, and capacity procurement. Review forecasts after major launches, architectural changes, and observed growth deviations.
28
+
29
+ ## Checklist
30
+ - [ ] Inputs are measured or explicitly labeled assumptions.
31
+ - [ ] End-to-end dependency constraints and failure headroom are modeled.
32
+ - [ ] Queue stability and burst recovery are included.
33
+ - [ ] Low/base/high sensitivity analysis is available.
34
+ - [ ] Scaling and load-shedding actions have owners and triggers.
@@ -0,0 +1,41 @@
1
+ # Chaos Engineering and Resilience Experiments
2
+
3
+ ## Principles
4
+ Chaos engineering is a controlled method for testing a falsifiable resilience hypothesis. It is not random disruption in production. Begin with steady-state signals that represent user-visible behavior, then introduce the smallest fault that can test the hypothesis.
5
+
6
+ ## Experiment design
7
+ 1. State the hypothesis and expected steady state.
8
+ 2. Identify target service, dependency, cohort, environment, and blast-radius boundary.
9
+ 3. Enumerate hazards, prerequisites, and possible data-integrity consequences.
10
+ 4. Define measurable abort conditions, owner, observer, and communication channel.
11
+ 5. Start in a safe environment with a small cohort; increase scope only after evidence supports it.
12
+ 6. Inject one fault class at a time and observe detection, containment, degradation, recovery, and reconciliation.
13
+ 7. Remove the fault, verify recovery, and document findings and follow-up actions.
14
+
15
+ ## Fault classes
16
+ - Network: latency, packet loss, partitions, DNS failures, connection resets.
17
+ - Dependency: slow/unavailable database, cache, queue, identity provider, or third-party API.
18
+ - Compute: process termination, CPU pressure, memory pressure, node/zone loss.
19
+ - Control plane: configuration errors, certificate expiry, deployment failure, autoscaler or scheduler disruption.
20
+ - Data path: delayed/out-of-order/duplicate messages, partial writes, replay, and stale replicas. Use non-destructive synthetic data and strict invariants.
21
+
22
+ ## Safety controls
23
+ - Explicit authorization and change window for production experiments.
24
+ - Hard scope allowlists, tenant/test cohort boundaries, concurrency and duration caps.
25
+ - Automated kill switch and independent abort monitoring.
26
+ - Exclude critical systems and irreversible operations unless separately approved and safely simulated.
27
+ - Verify backups, restore paths, and data reconciliation before experiments that can affect persistence.
28
+ - Coordinate on-call, security, platform, and vendor stakeholders.
29
+
30
+ ## What to measure
31
+ User journey success, SLO burn, latency percentiles, error rate, queue age/depth, saturation, failover time, data correctness, alert detection time, mitigation time, and recovery time. A system that remains available but corrupts state has not passed.
32
+
33
+ ## Learning loop
34
+ Convert findings into engineering work: missing timeout, unbounded retry, weak isolation, inadequate capacity, poor alerting, unsafe failover, or incomplete runbooks. Assign owners and deadlines; repeat the experiment after remediation. Track experiment coverage and validated hypotheses, not a vanity count of injected faults.
35
+
36
+ ## Checklist
37
+ - [ ] Hypothesis and steady-state metrics are defined.
38
+ - [ ] Scope, authorization, blast radius, and abort criteria are explicit.
39
+ - [ ] Data integrity and recovery are included.
40
+ - [ ] On-call owners can observe and stop the experiment.
41
+ - [ ] Findings become tracked remediation and retested controls.
@@ -0,0 +1,34 @@
1
+ # Incident Management, On-call, and Postmortems
2
+
3
+ ## Operational model
4
+ Define severity levels by user/business impact, not by component count or internal effort. Establish incident command, technical lead, communications lead, and scribe roles appropriate to incident scale. Publish escalation paths, service ownership, dependency contacts, and decision authority.
5
+
6
+ ## Detection and response
7
+ - Alert on user-visible symptoms and SLO error-budget burn; use metrics, logs, traces, and synthetic checks as complementary evidence.
8
+ - Make alerts actionable: condition, impact, owner, runbook, and escalation. Avoid paging on every transient threshold breach.
9
+ - Triage scope, affected cohorts, start time, recent changes, dependencies, and data-integrity risk.
10
+ - Stabilize first: rollback, traffic shift, disable a feature, shed load, isolate a dependency, or invoke a tested degraded mode.
11
+ - Preserve evidence and timeline. Communicate known facts, uncertainty, impact, and next update time.
12
+ - Verify recovery using user-facing signals and reconciliation, not merely healthy processes.
13
+
14
+ ## On-call sustainability
15
+ - Define primary/secondary coverage, escalation timeout, handoff, compensation/rest, and backup ownership.
16
+ - Track page volume, actionable-page ratio, toil, after-hours load, and recurring incidents.
17
+ - Runbooks should include symptoms, diagnostic queries, safe mitigations, rollback, verification, and escalation. Keep commands environment-specific and reviewed.
18
+ - Automate repetitive safe actions with guardrails and audit; do not automate irreversible actions without explicit controls.
19
+
20
+ ## Postmortems
21
+ Use blameless, evidence-based analysis. Capture impact, timeline, detection, contributing conditions, response effectiveness, what went well, where response struggled, and prioritized corrective actions with owners and due dates. Distinguish trigger from systemic contributors; avoid assigning root cause to the last person or deploy.
22
+ - Corrective actions should address prevention, detection, containment, and recovery.
23
+ - Rank actions by risk reduction and recurrence likelihood; verify completion and effectiveness.
24
+ - Share learnings across teams without exposing secrets or sensitive customer data.
25
+
26
+ ## Operational metrics
27
+ Track MTTD, time to acknowledge, time to mitigate, time to recover, recurrence, SLO impact, customer impact, and action completion. These metrics diagnose process friction; do not use them as simplistic individual performance scores.
28
+
29
+ ## Checklist
30
+ - [ ] Severity, roles, escalation, and communications are defined.
31
+ - [ ] Alerts are actionable and tied to user impact.
32
+ - [ ] Runbooks contain safe, tested mitigation and verification steps.
33
+ - [ ] Recovery includes data correctness and backlog reconciliation.
34
+ - [ ] Postmortem actions have owners, due dates, and effectiveness checks.
@@ -0,0 +1,35 @@
1
+ # DNS and Service Discovery Architecture
2
+
3
+ ## Responsibilities and boundaries
4
+ DNS resolves names to records; service discovery identifies healthy, eligible service instances and their metadata. Decide whether discovery is client-side, server-side, DNS-based, registry-backed, or provided by a platform control plane. Do not assume DNS alone provides immediate health-aware routing.
5
+
6
+ ## Naming and record design
7
+ - Define stable service names independently of ephemeral instance addresses.
8
+ - Choose A/AAAA, CNAME, SRV, TXT, and HTTPS/SVCB records according to client and protocol support.
9
+ - Document authoritative zones, delegation, split-horizon behavior, private/public namespaces, and ownership.
10
+ - Set TTLs based on change frequency, resolver behavior, failover objectives, and cache layers. TTL is not a hard upper bound on propagation because clients and resolvers may cache differently.
11
+ - Plan negative caching, NXDOMAIN behavior, stale answers, and resolver failure modes.
12
+
13
+ ## Service discovery
14
+ - Model registration, health state, metadata, endpoint eligibility, deregistration, and stale-instance cleanup.
15
+ - Prefer platform-native discovery when it meets requirements; add a registry only for a demonstrated cross-platform or control-plane need.
16
+ - Define client-side versus server-side load balancing, endpoint refresh cadence, connection reuse, and behavior when no healthy endpoint exists.
17
+ - Avoid synchronized refresh storms; use jitter, bounded caching, and backoff.
18
+ - Treat discovery data as routing input, not authorization. Enforce identity and policy at the connection and request layers.
19
+
20
+ ## Failure and security
21
+ - Consider authoritative DNS outage, resolver saturation, stale cache, split-brain registration, control-plane partition, and partial network reachability.
22
+ - Use redundant resolvers and authoritative services; test recursive resolver dependencies and local caching behavior.
23
+ - Protect zone administration with least privilege, MFA, audit, DNSSEC where appropriate, and controlled change processes.
24
+ - Defend against cache poisoning, dangling records/subdomain takeover, unauthorized zone transfer, and SSRF through attacker-controlled DNS answers. Revalidate resolved destinations where threat models require it.
25
+ - Do not use DNS as a substitute for service identity, mTLS, or application authorization.
26
+
27
+ ## Operations
28
+ Track query volume, latency, SERVFAIL/NXDOMAIN, cache hit ratio, registration churn, stale endpoint rate, and resolution failures by resolver and zone. Test failover and record changes from real client resolver paths.
29
+
30
+ ## Checklist
31
+ - [ ] Namespaces, zones, ownership, and record lifecycle are documented.
32
+ - [ ] TTL and negative-cache behavior match failover objectives.
33
+ - [ ] Discovery freshness, health, and empty-endpoint behavior are defined.
34
+ - [ ] Resolver and control-plane failure modes are tested.
35
+ - [ ] DNS administration and destination validation are secured.
@@ -0,0 +1,31 @@
1
+ # Load Balancing and Global Traffic Management
2
+
3
+ ## Traffic layers
4
+ Separate global traffic steering (DNS, anycast, or global load balancer), regional ingress, application load balancing, and service-to-service balancing. Document which layer owns health decisions, retries, TLS termination, affinity, and routing policy.
5
+
6
+ ## Algorithms and selection
7
+ - Compare round robin, weighted round robin, least connections, least response time, consistent hashing, and locality-aware routing against workload characteristics.
8
+ - Account for long-lived connections, uneven request cost, HTTP/2 and HTTP/3 multiplexing, connection pools, and slow-start behavior.
9
+ - Use weights for controlled rollout and capacity-aware distribution; avoid assuming equal request counts imply equal resource cost.
10
+ - Define session affinity only when required; explain failover and rebalancing behavior when affinity breaks.
11
+ - Prevent retry amplification by assigning retry ownership, deadlines, retry budgets, and idempotency requirements.
12
+
13
+ ## Health and failover
14
+ - Distinguish liveness, readiness, synthetic user-journey checks, and dependency health. A process responding to a health endpoint may still be unable to serve traffic correctly.
15
+ - Use passive health signals with active probes carefully; define thresholds, hysteresis, and recovery slow start to avoid flapping.
16
+ - Specify zone and region failure policy, drain behavior, connection termination, and failback criteria.
17
+ - Avoid removing every instance simultaneously due to a shared dependency failure; use dependency-aware and failure-domain-aware policies.
18
+ - Define behavior when health state is unavailable or inconsistent.
19
+
20
+ ## Global traffic management
21
+ Compare DNS-based steering, anycast, and proxy-based global load balancing. Consider resolver caching, client location accuracy, BGP convergence, TLS, data residency, active-active data consistency, and regional control-plane dependencies. Route users to a region that can actually serve their data and authorization context.
22
+
23
+ ## Security and operations
24
+ Define trusted proxy boundaries, forwarded-header normalization, source IP preservation, DDoS controls, TLS policy, certificate lifecycle, and administrative access. Monitor distribution skew, queueing, connection saturation, health transitions, failover time, rejected traffic, and per-region SLOs.
25
+
26
+ ## Checklist
27
+ - [ ] Each routing layer has explicit ownership and policy.
28
+ - [ ] Algorithms match connection and request-cost patterns.
29
+ - [ ] Health checks reflect serving ability without causing correlated ejection.
30
+ - [ ] Retry, drain, failover, and failback behavior are bounded and tested.
31
+ - [ ] Global routing accounts for data locality, consistency, and resolver behavior.
@@ -0,0 +1,34 @@
1
+ # CDN and Edge Caching Architecture
2
+
3
+ ## Cache placement
4
+ Choose browser, application, reverse-proxy, CDN point-of-presence, and regional cache layers based on content ownership, latency objectives, freshness, privacy, and invalidation needs. A cache is a derived copy, not automatically a source of truth.
5
+
6
+ ## Cache key and policy
7
+ - Define cache keys from normalized scheme, host, path, query parameters, selected headers, content encoding, and tenant context.
8
+ - Avoid accidental variation explosion and cache poisoning caused by inconsistent normalization.
9
+ - Set Cache-Control, s-maxage, stale-while-revalidate, stale-if-error, and Vary policies deliberately; verify CDN-specific semantics.
10
+ - Separate public immutable assets from personalized, authenticated, and sensitive responses. Never share-cache user-specific content without a proven safe key and authorization model.
11
+ - Use versioned asset URLs for immutable content and explicit TTL/invalidation for mutable content.
12
+
13
+ ## Invalidation and consistency
14
+ - Prefer versioned keys or bounded TTLs where possible; use purge APIs for urgent invalidation with documented propagation guarantees.
15
+ - Define invalidation fan-out, retry, ordering, and observability. Purge success at the control plane does not prove every edge has evicted an object.
16
+ - Use surrogate keys/tags where supported to invalidate related content groups.
17
+ - Decide whether stale content is acceptable during origin failure; encode this per content class.
18
+ - Prevent stampedes with request coalescing, stale-while-revalidate, jittered refresh, and origin shielding.
19
+
20
+ ## Dynamic and API traffic
21
+ Evaluate edge compute for authentication prechecks, redirects, routing, lightweight personalization, and request normalization only when data locality, runtime limits, and debugging support are acceptable. Keep authorization and sensitive business invariants at trusted services unless the edge has equivalent policy and identity guarantees.
22
+
23
+ ## Security
24
+ Protect origins from direct access and bypass; authenticate origin pulls; validate host and forwarding headers; defend against cache deception, poisoning, request smuggling, and cross-tenant cache leakage. Define WAF, bot management, rate limits, TLS, and DDoS responsibilities across provider and origin.
25
+
26
+ ## Economics and observability
27
+ Model cache hit ratio by bytes and requests, origin offload, egress, purge volume, request fees, shield traffic, and regional distribution. Monitor hit/miss, stale responses, origin latency, revalidation, purge lag, cache-key cardinality, and origin errors.
28
+
29
+ ## Checklist
30
+ - [ ] Cacheability and privacy classes are explicit.
31
+ - [ ] Cache keys include every representation/tenant dimension and exclude unsafe noise.
32
+ - [ ] Freshness, invalidation, and stale-serving policies are documented.
33
+ - [ ] Origin protection and cache-bypass paths are secured.
34
+ - [ ] Hit ratio, origin offload, purge lag, and cost are measured.
@@ -0,0 +1,34 @@
1
+ # Cloud Networking and Connectivity Architecture
2
+
3
+ ## Network model
4
+ Document accounts/projects, regions, availability zones, VPC/VNet boundaries, subnets, route tables, gateways, firewalls, DNS, private endpoints, and shared network services. Distinguish control-plane configuration from packet data paths.
5
+
6
+ ## Addressing and segmentation
7
+ - Establish non-overlapping CIDR plans across environments, regions, acquisitions, and partner networks.
8
+ - Segment by trust, workload, environment, and operational ownership; avoid relying on subnet boundaries as the only authorization control.
9
+ - Define ingress, egress, east-west, and management planes with explicit default-deny policies where practical.
10
+ - Plan IPv4 exhaustion, IPv6 dual-stack support, NAT port capacity, ephemeral ports, and overlapping-address translation.
11
+ - Document route propagation, longest-prefix matching, asymmetric paths, and blackhole behavior.
12
+
13
+ ## Connectivity patterns
14
+ Compare public endpoints, NAT, VPN, dedicated private connectivity, peering, transit hubs, private service endpoints, and service-mesh connectivity. Evaluate bandwidth, latency, resiliency, routing limits, encryption, DNS integration, and cost. Peering is not transitive unless the platform explicitly provides a transit design.
15
+
16
+ ## Availability and scale
17
+ - Design redundant gateways and paths across failure domains; define failover convergence and route ownership.
18
+ - Model throughput, packets per second, connection tracking, NAT port exhaustion, MTU, fragmentation, and cross-zone/region egress.
19
+ - Avoid central inspection bottlenecks and single-region transit dependencies.
20
+ - Test asymmetric routing, failover, DNS resolution, and effective policy from workload subnets.
21
+ - Treat network policy and firewall changes as versioned infrastructure with review, staged rollout, and rollback.
22
+
23
+ ## Security and governance
24
+ Apply least privilege to network administration, log flow decisions, restrict management access, and use workload identity and encryption in addition to network location. Review broad CIDRs, unrestricted egress, exposed control planes, stale rules, and shadow connectivity. Keep segmentation aligned with data classification and threat models.
25
+
26
+ ## Operations
27
+ Monitor flow logs, route changes, drops, retransmits, latency, connection tracking, NAT utilization, gateway saturation, and cross-zone/region transfer. Maintain diagrams generated from deployed state and reconcile drift.
28
+
29
+ ## Checklist
30
+ - [ ] Address plan avoids overlap and includes IPv6/NAT capacity.
31
+ - [ ] Trust zones and ingress/egress policies are explicit.
32
+ - [ ] Routing, DNS, MTU, and asymmetric paths are validated.
33
+ - [ ] Redundancy and failover are tested across independent failure domains.
34
+ - [ ] Flow visibility, change control, and cost allocation are available.
@@ -0,0 +1,33 @@
1
+ # Edge Computing Architecture
2
+
3
+ ## When edge is justified
4
+ Use edge computing when latency, intermittent connectivity, data locality, bandwidth reduction, physical proximity, or local autonomy materially changes the solution. Compare with regional cloud deployment and client-side execution before adding distributed edge operations.
5
+
6
+ ## Placement and topology
7
+ Define device, site, metro, regional, and cloud tiers. Assign workloads to tiers based on latency budgets, data gravity, compute limits, connectivity, and failure domains. Document which tier is authoritative for identity, configuration, state, and policy.
8
+
9
+ ## Workload lifecycle
10
+ - Package immutable, signed workloads with reproducible builds and versioned configuration.
11
+ - Define enrollment, attestation, provisioning, staged rollout, health, rollback, decommissioning, and secure recovery.
12
+ - Support offline operation with bounded local queues, durable state, clock uncertainty, and explicit conflict/reconciliation rules.
13
+ - Design for intermittent links, bandwidth caps, delayed updates, duplicate delivery, and long periods without control-plane contact.
14
+ - Keep secrets short-lived where possible; support rotation and revocation during disconnection with a documented risk window.
15
+
16
+ ## Data and consistency
17
+ Classify data as local ephemeral, locally durable, replicated, or cloud-authoritative. Define write ownership, synchronization direction, conflict resolution, retention, deletion propagation, and behavior after device replacement. Do not assume eventual connectivity guarantees automatic convergence.
18
+
19
+ ## Security and fleet management
20
+ Use hardware-backed identity/secure boot where available, signed artifacts, least-privilege workload identities, encrypted storage, tamper-aware logs, secure update channels, and remote revocation. Treat physical access and device compromise as realistic threats. Bound local privileges and lateral movement.
21
+
22
+ ## Reliability and observability
23
+ Define local degraded modes and safe shutdown behavior. Buffer telemetry during disconnection with bounded storage and priority; avoid unbounded replay storms after reconnect. Monitor fleet version skew, last-seen time, update success, resource pressure, synchronization lag, and policy compliance.
24
+
25
+ ## Economics
26
+ Include edge hardware, replacement, connectivity, field support, remote hands, energy, local storage, fleet management, and lifecycle costs—not only cloud compute savings.
27
+
28
+ ## Checklist
29
+ - [ ] Edge placement solves a measured latency, locality, or connectivity constraint.
30
+ - [ ] Offline behavior, local authority, and reconciliation are explicit.
31
+ - [ ] Artifact signing, device identity, updates, and revocation are designed.
32
+ - [ ] Fleet observability and bounded telemetry replay are available.
33
+ - [ ] Full lifecycle and field-support costs are modeled.
@@ -0,0 +1,30 @@
1
+ # Storage Infrastructure and Storage Systems
2
+
3
+ ## Workload characterization
4
+ Classify data by access pattern, durability, latency, throughput, IOPS, block size, concurrency, growth, retention, sharing, locality, and recovery objectives. Separate application database semantics from underlying block, file, and object storage guarantees.
5
+
6
+ ## Storage types
7
+ - Block storage: low-level volumes for databases and filesystems; evaluate IOPS, throughput, latency, queue depth, burst credits, multi-attach semantics, snapshots, and resize behavior.
8
+ - File storage: shared hierarchical namespace; evaluate metadata operations, locking, consistency, throughput, client caching, and concurrent writers.
9
+ - Object storage: API-addressed objects; evaluate durability, consistency model, multipart uploads, lifecycle tiers, versioning, retention lock, event notifications, and request cost.
10
+ - Ephemeral/local NVMe: high performance with host or instance lifecycle coupling; define replication and rebuild behavior.
11
+ - Distributed storage: understand replication/erasure coding, quorum, failure domains, repair bandwidth, rebalancing, and correlated failure risks.
12
+
13
+ ## Durability and recovery
14
+ Distinguish durability from availability and backup. Define replication scope, versioning, immutable backups, retention, encryption keys, restore testing, point-in-time recovery, and deletion protection. Validate recovery time and data integrity, not only snapshot creation. Understand consistency and atomicity boundaries across objects, files, and volumes.
15
+
16
+ ## Performance and capacity
17
+ Model IOPS, throughput, queue depth, request size, latency percentiles, metadata hot spots, cache hit ratio, compaction, garbage collection, and rebuild overhead. Include burst limits, throttling, noisy neighbors, and performance degradation during repair or snapshots. Benchmark with production-like data and concurrency.
18
+
19
+ ## Cost and lifecycle
20
+ Include provisioned capacity, provisioned performance, operations/requests, snapshots, replication, retrieval, egress, minimum retention, and early deletion fees. Define tiering, lifecycle transitions, orphan detection, capacity alerts, and ownership.
21
+
22
+ ## Security
23
+ Use encryption at rest and in transit, scoped identities, private endpoints, least-privilege access, access logging, key lifecycle, tenant isolation, and secure deletion. For object storage, explicitly review public access, bucket policies, presigned URL expiry, and cross-account access.
24
+
25
+ ## Checklist
26
+ - [ ] Storage class matches access pattern and latency/throughput needs.
27
+ - [ ] Durability, availability, replication, backup, and restore are distinguished.
28
+ - [ ] IOPS, throughput, queue depth, burst, and rebuild behavior are modeled.
29
+ - [ ] Lifecycle, retention, encryption, and tenant access policies are explicit.
30
+ - [ ] Restore and failure-domain recovery are tested.
@@ -0,0 +1,27 @@
1
+ # TCP, QUIC, and Network Performance Engineering
2
+
3
+ ## Transport selection
4
+ Understand TCP connection setup, congestion control, retransmission, flow control, head-of-line blocking, keepalive, and connection reuse. Evaluate QUIC/HTTP/3 for connection migration, stream multiplexing, handshake behavior, and deployment compatibility; do not assume it improves every workload.
5
+
6
+ ## Latency budget
7
+ Decompose DNS lookup, connection establishment, TLS handshake, network RTT, congestion/window growth, server queueing, application processing, and response transfer. Separate cold and warm connections, client and server time, and network from application delay.
8
+
9
+ ## Throughput and congestion
10
+ - Estimate bandwidth-delay product (BDP = bandwidth × RTT) to understand in-flight data requirements.
11
+ - Investigate packet loss, retransmissions, congestion window, receive window, pacing, and path MTU.
12
+ - Avoid increasing socket buffers or concurrency without evidence; buffers can increase queueing and memory pressure.
13
+ - Account for NAT, firewalls, proxies, load balancers, and middleboxes that alter idle timeout, connection reuse, or protocol support.
14
+ - Test realistic RTT, loss, jitter, bandwidth constraints, and asymmetric paths.
15
+
16
+ ## Connection management
17
+ Define pool sizing, reuse, idle timeout, keepalive, maximum lifetime, DNS refresh, connection draining, and retry behavior. Avoid synchronized reconnect storms after deploys or network restoration. For streaming and long-lived connections, define heartbeat, backpressure, reconnect jitter, and resume semantics.
18
+
19
+ ## Diagnostics
20
+ Use packet captures, flow logs, socket metrics, retransmission counters, DNS/TLS timing, and distributed traces together. Packet captures can contain sensitive payloads and identifiers; restrict capture scope, access, and retention. eBPF tools can improve visibility but require kernel compatibility, privilege controls, and overhead evaluation.
21
+
22
+ ## Checklist
23
+ - [ ] Transport and protocol behavior are verified for clients and intermediaries.
24
+ - [ ] Cold/warm connection and end-to-end latency are measured separately.
25
+ - [ ] RTT, loss, MTU, retransmissions, and BDP inform tuning.
26
+ - [ ] Pools, keepalive, timeouts, draining, and reconnect jitter are bounded.
27
+ - [ ] Packet and kernel-level diagnostics follow privacy and privilege controls.
@@ -0,0 +1,58 @@
1
+ # Task routing and evidence discipline
2
+
3
+ ## Purpose
4
+
5
+ Use this guide as the first-pass index for selecting knowledge. Route by the user's decision or observed failure, not by attempting to load the entire reference library. Start with one primary reference and add only the adjacent material needed to answer the concrete question.
6
+
7
+ ## Task-to-reference routing
8
+
9
+ | Task signal | Start here | Add when relevant |
10
+ |---|---|---|
11
+ | Requirements, workload, sizing, latency or cost envelope | `01-requirements-and-capacity.md` | `59-capacity-planning-and-performance-modeling.md`, `26-finops-and-cloud-cost.md` |
12
+ | High-level architecture, boundaries, synchronous flows | `02-architecture-and-networking.md` | `13-architecture-intelligence.md`, `14-api-and-data-contracts.md` |
13
+ | Repository architecture review | `13-architecture-intelligence.md` | `15-failure-analysis.md`, then domain-specific references identified from code |
14
+ | Database schema, query, consistency or transaction issue | `03-data-and-storage.md` | Select the matching database, sharding, search, vector, or migration reference |
15
+ | Cache behavior or invalidation | `04-caching.md` | `07-reliability-and-resilience.md`, `64-cdn-and-edge-caching.md` |
16
+ | Queue, event, CDC or workflow issue | `05-async-and-messaging.md` | Select Kafka/Pulsar, CQRS, CDC, workflow orchestration, or schema governance |
17
+ | Reliability, incident, recovery or failover | `07-reliability-and-resilience.md` | `15-failure-analysis.md`, `24-multi-region-and-disaster-recovery.md`, `61-incident-management-and-postmortems.md` |
18
+ | API design, compatibility or real-time transport | `14-api-and-data-contracts.md` | REST, GraphQL, gRPC, WebSocket/SSE, gateway, and API security references |
19
+ | Identity, authorization, threat or privacy | `08-api-security-observability.md` | OAuth/OIDC, IAM, workload identity, secrets, STRIDE, supply chain, and privacy references |
20
+ | AI agents, harness, MCP, memory or evaluation | `12-ai-systems-architecture.md` | Select only the relevant agent, harness, MCP, security, state, or evaluation reference |
21
+ | Kubernetes, platform, network, CDN, storage or edge | `09-modern-engineering.md` | Select the matching infrastructure reference |
22
+ | Performance optimization | `57-continuous-profiling-and-performance-diagnostics.md` | `58-load-stress-soak-testing-and-workload-modeling.md`, `59-capacity-planning-and-performance-modeling.md` |
23
+ | Architecture choice or ADR | `13-architecture-intelligence.md` | Relevant domain reference plus `templates/architecture-decision-matrix-template.md` |
24
+ | Interview practice | `10-workflows-and-checklists.md` | `01-requirements-and-capacity.md`, `11-case-studies.md` |
25
+
26
+ ## Evidence protocol for repository reviews
27
+
28
+ 1. **Declare scope.** List inspected directories, entry points, configuration, tests, deployment files, and known exclusions. State whether the review is static-only.
29
+ 2. **Trace critical paths.** Follow at least one important request or event from entry point through authorization, domain logic, persistence/external calls, and response/event publication.
30
+ 3. **Map dependencies.** Record caller/callee, data ownership, sync/async boundaries, and trust boundaries. Draw only edges supported by inspected code or configuration.
31
+ 4. **Classify evidence.** Use Confirmed for directly observed code/configuration, Likely for a reasoned inference, and Unknown when runtime or repository visibility is insufficient.
32
+ 5. **Prioritize by impact.** Rank data loss/corruption, security exposure, unavailability, and uncontrolled cost above style or speculative scale concerns.
33
+ 6. **Make findings reproducible.** Include file path and symbol/config key, trigger conditions, impact, recommended change, and a validation method.
34
+ 7. **State limitations.** Static inspection does not establish production traffic, deployed topology, live configuration, incident history, or actual performance. Request runtime metrics or traces when those facts affect the conclusion.
35
+
36
+ ## Reference-loading rules
37
+
38
+ - Read the routing index first, then the smallest relevant reference set.
39
+ - Prefer the exact technology or failure-domain reference over loading all adjacent topics.
40
+ - Load templates only when producing that deliverable; do not force a template into a short answer.
41
+ - If a task spans domains, explain why each additional reference is needed.
42
+ - Verify fast-changing vendor and protocol details against current official documentation.
43
+ - Do not treat a reference's presence as evidence that a repository implements the described mechanism.
44
+
45
+ ## Confidence and estimate labels
46
+
47
+ Use these labels consistently:
48
+
49
+ - **Observed:** directly visible in source, configuration, tests, or supplied measurements.
50
+ - **Inferred:** plausible conclusion from observed evidence; state the reasoning and alternatives.
51
+ - **Assumed:** temporary input used to make progress; identify the owner or question that can confirm it.
52
+ - **Unknown:** unavailable from current inspection; name the evidence needed to resolve it.
53
+
54
+ For capacity and cost estimates, show the formula, units, input provenance, and sensitivity range. Never convert an assumed peak factor or average record size into a measured fact.
55
+
56
+ ## Regression cases
57
+
58
+ The machine-readable cases in `evals/system-design-cases.json` cover representative routing and output expectations. They are prompt fixtures for human or model-assisted evaluation, not deterministic proof of answer quality. Evaluate both the selected mode/references and whether the response respects evidence, safety, and scope guardrails.
@@ -1,6 +1,6 @@
1
1
  [CmdletBinding()]
2
2
  param(
3
- [ValidateSet('all','codex','claude','cursor','copilot')]
3
+ [ValidateSet('all','dsh','codex','claude','cursor','copilot')]
4
4
  [string]$Agent = 'all',
5
5
  [ValidateSet('project','user')]
6
6
  [string]$Scope = 'project',
@@ -16,19 +16,28 @@ if (-not (Test-Path -LiteralPath (Join-Path $Source 'SKILL.md') -PathType Leaf))
16
16
  }
17
17
  $Base = (Get-Location).Path
18
18
  if ($Scope -eq 'user') { $Base = $HOME }
19
+ $DshRoot = Join-Path $Base '.dsh'
20
+ if ($Scope -eq 'user') {
21
+ if ([string]::IsNullOrWhiteSpace($env:DSH_HOME)) { $DshRoot = Join-Path $HOME '.dsh' }
22
+ else { $DshRoot = $env:DSH_HOME }
23
+ }
19
24
 
20
25
  $Parents = @()
21
26
  switch ($Agent + ':' + $Scope) {
22
27
  'all:project' {
28
+ $Parents += (Join-Path $Base '.dsh/skills')
23
29
  $Parents += (Join-Path $Base '.agents/skills')
24
30
  $Parents += (Join-Path $Base '.claude/skills')
25
31
  $Parents += (Join-Path $Base '.github/skills')
26
32
  }
27
33
  'all:user' {
34
+ $Parents += (Join-Path $DshRoot 'skills')
28
35
  $Parents += (Join-Path $Base '.agents/skills')
29
36
  $Parents += (Join-Path $Base '.claude/skills')
30
37
  $Parents += (Join-Path $Base '.copilot/skills')
31
38
  }
39
+ 'dsh:project' { $Parents += (Join-Path $DshRoot 'skills') }
40
+ 'dsh:user' { $Parents += (Join-Path $DshRoot 'skills') }
32
41
  'codex:project' { $Parents += (Join-Path $Base '.agents/skills') }
33
42
  'codex:user' { $Parents += (Join-Path $Base '.agents/skills') }
34
43
  'claude:project' { $Parents += (Join-Path $Base '.claude/skills') }
@@ -8,10 +8,12 @@ FORCE=0
8
8
  usage() {
9
9
  cat <<'EOF'
10
10
  Install the system-design-primer Agent Skill.
11
- Usage: bash scripts/install.sh [--agent all|codex|claude|cursor|copilot] [--scope project|user] [--dry-run] [--force]
12
- Targets: all -> .agents/skills + .claude/skills + .github/skills (project)
13
- .agents/skills + .claude/skills + .copilot/skills (user)
11
+ Usage: bash scripts/install.sh [--agent all|dsh|codex|claude|cursor|copilot] [--scope project|user] [--dry-run] [--force]
12
+ Targets: all -> .dsh/skills + .agents/skills + .claude/skills + .github/skills (project)
13
+ $DSH_HOME/skills + .agents/skills + .claude/skills + .copilot/skills (user)
14
14
  Run from the target project's root for --scope project.
15
+ For user-level DSH installs, DSH_HOME overrides the default $HOME/.dsh root.
16
+ DeepSeek Harness discovers project Skills under .dsh/skills and user Skills under $DSH_HOME/skills.
15
17
  Only distributable Skill files are copied; .git, CI, and tests are excluded.
16
18
  Existing installs are never replaced unless --force is supplied.
17
19
  EOF
@@ -27,7 +29,7 @@ while (($#)); do
27
29
  *) usage >&2; fail "unknown argument: $1" ;;
28
30
  esac
29
31
  done
30
- case "$AGENT" in all|codex|claude|cursor|copilot) ;; *) fail "invalid agent: $AGENT" ;; esac
32
+ case "$AGENT" in all|dsh|codex|claude|cursor|copilot) ;; *) fail "invalid agent: $AGENT" ;; esac
31
33
  case "$SCOPE" in project|user) ;; *) fail "invalid scope: $SCOPE" ;; esac
32
34
  SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd -P)"
33
35
  SOURCE="$(cd -- "$SCRIPT_DIR/.." && pwd -P)"
@@ -35,10 +37,15 @@ SOURCE="$(cd -- "$SCRIPT_DIR/.." && pwd -P)"
35
37
  BASE="$PWD"
36
38
  [[ "$SCOPE" == "user" ]] && BASE="$HOME"
37
39
  [[ -n "$BASE" && -d "$BASE" ]] || fail "target root does not exist: $BASE"
40
+ DSH_ROOT="$BASE/.dsh"
41
+ if [[ "$SCOPE" == "user" ]]; then
42
+ DSH_ROOT="${DSH_HOME:-$HOME/.dsh}"
43
+ fi
38
44
  declare -a PARENTS=()
39
45
  case "$AGENT:$SCOPE" in
40
- all:project) PARENTS=("$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.github/skills") ;;
41
- all:user) PARENTS=("$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.copilot/skills") ;;
46
+ all:project) PARENTS=("$BASE/.dsh/skills" "$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.github/skills") ;;
47
+ all:user) PARENTS=("$DSH_ROOT/skills" "$BASE/.agents/skills" "$BASE/.claude/skills" "$BASE/.copilot/skills") ;;
48
+ dsh:*) PARENTS=("$DSH_ROOT/skills") ;;
42
49
  codex:*) PARENTS=("$BASE/.agents/skills") ;;
43
50
  claude:*) PARENTS=("$BASE/.claude/skills") ;;
44
51
  cursor:*) PARENTS=("$BASE/.cursor/skills") ;;