constella 0.1.0

package/skills/engineering/architecture/api-design-rest-graphql/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: api-design-rest-graphql
+description: REST design grounded in HTTP semantics (methods, status, idempotency) and GraphQL schema/query design; read when designing or reviewing an API.
+domain: engineering
+category: architecture
+tags: [api-design, rest, graphql, http, schema]
+official_sources:
+  - https://www.rfc-editor.org/rfc/rfc9110.html
+  - https://graphql.org/learn/
+verified: 2026-06-16
+---
+
+# API Design: REST & GraphQL
+
+## Overview
+This skill covers two dominant API styles: REST, which builds on the standardized semantics of HTTP (methods, status codes, idempotency), and GraphQL, where clients request exactly the data they need against a typed schema. Read it when designing endpoints, choosing between the styles, or reviewing API contracts for correctness and consistency.
+
+## Official sources
+- RFC 9110 — HTTP Semantics (methods, status codes, safe/idempotent): https://www.rfc-editor.org/rfc/rfc9110.html
+- GraphQL — official Learn guide: https://graphql.org/learn/
+
+## Core concepts
+- **HTTP methods (RFC 9110 §9)**: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE — each with defined semantics; map resource operations onto them rather than inventing verbs.
+- **Safe and idempotent methods**: safe methods (e.g. GET, HEAD) are not expected to change server state; idempotent methods (GET, HEAD, PUT, DELETE, etc.) produce the same effect whether sent once or many times — essential for safe retries.
+- **Status codes (RFC 9110 §15)**: five classes — 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error — communicate outcome semantically.
+- **GraphQL schema and types**: the schema's type system describes exactly what data can be queried; the schema is the contract between client and server.
+- **GraphQL operations**: queries read data, mutations modify data, and subscriptions stream updates; clients select precisely the fields they need.
+- **GraphQL resolvers**: each field is backed by a resolver function that produces its value during execution.
+
+## Best practices
+- Honor HTTP semantics: use idempotent methods (PUT/DELETE) where clients may retry, and return status codes that match the actual outcome (per RFC 9110).
+- Use GET only for safe, side-effect-free reads so caches and crawlers can call it without changing state.
+- In GraphQL, design the schema around domain types and let clients select fields; avoid one-off endpoints — the schema is the single contract.
+- Version and evolve deliberately: REST via URL/media-type versioning; GraphQL by adding fields and deprecating rather than breaking existing ones.
+
+## Common pitfalls
+- Using POST (or GET) for everything in REST → breaks idempotency and caching; pick the method that matches the operation's semantics.
+- Returning 200 OK with an error body → clients and proxies cannot react correctly; use the appropriate 4xx/5xx status.
+- Exposing unbounded GraphQL queries → deep/nested queries can overload the server; add depth/complexity limits and pagination.
+
+## Examples
+```http
+# REST — idempotent update via PUT
+PUT /users/42 HTTP/1.1
+Content-Type: application/json
+
+{ "name": "Ada", "email": "ada@example.com" }
+# -> 200 OK (updated) or 201 Created; repeating yields the same result
+```
+```graphql
+# GraphQL — client selects exactly the fields it needs
+query {
+  user(id: "42") {
+    name
+    email
+  }
+}
+```
+
+## Further reading
+- GraphQL best practices (pagination, versioning, nullability): https://graphql.org/learn/best-practices/
+- RFC 9110 method definitions (Section 9): https://www.rfc-editor.org/rfc/rfc9110.html#name-methods
+
+## Related skills
+- ../software-architecture-patterns — where APIs sit in service boundaries
+- ../caching-strategies — HTTP caching and cache-aside for API responses
+- ../data-modeling — shaping resources and types behind the API

package/skills/engineering/architecture/caching-strategies/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: caching-strategies
+description: Cache layers, cache-aside, TTLs, and invalidation to cut latency and load; read before adding a cache or debugging stale data.
+domain: engineering
+category: architecture
+tags: [caching, cache-aside, ttl, invalidation, redis]
+official_sources:
+  - https://aws.amazon.com/caching/
+  - https://redis.io/docs/latest/develop/
+verified: 2026-06-16
+---
+
+# Caching Strategies
+
+## Overview
+A cache is a high-speed storage layer that holds a subset of data so future reads are served from fast memory (often sub-millisecond) instead of a slower origin. Caching reduces latency and offloads databases and services, but introduces the hard problems of staleness and invalidation. Read this before adding a cache layer or diagnosing stale/inconsistent reads.
+
+## Official sources
+- AWS — Caching Overview (layers, TTLs, CDN, in-memory): https://aws.amazon.com/caching/
+- Redis — Develop documentation (data types, clients, pub/sub): https://redis.io/docs/latest/develop/
+
+## Core concepts
+- **What a cache is**: a high-speed layer storing a subset of data; reading from an in-memory cache is extremely fast (sub-millisecond) compared with the origin store.
+- **Cache layers**: caching happens at multiple tiers — CDN/edge for static content, application/in-memory caches (e.g. Redis) for data and sessions, and database/query caches.
+- **Cache-aside (lazy loading)**: the application checks the cache first; on a miss it loads from the origin, populates the cache, and returns — only requested data is ever cached.
+- **TTL (time to live)**: an expiry applied to cached entries so stale data is automatically evicted after a bounded window.
+- **CDN / edge caching**: a CDN serves cached copies of content (pages, images, video) from a global network of edge locations near users.
+- **Eviction**: when memory is full, caches evict entries by policy (e.g. LRU) to make room for new data.
+
+## Best practices
+- Set a TTL on cached entries so staleness is bounded even when explicit invalidation is missed (AWS recommends TTLs to expire data appropriately).
+- Use cache-aside as the default for read-heavy data: load on demand and cache only what is actually requested.
+- Cache at the right layer: CDN for static assets, in-memory (Redis) for hot data and sessions, closest to where the read happens.
+- Invalidate or update the cache on writes (write-through or explicit delete) to limit how long stale data can be served.
+
+## Common pitfalls
+- Caching with no TTL and no invalidation → data silently goes stale forever; always bound freshness.
+- Cache stampede: many concurrent misses hit the origin at once when a hot key expires → use locking/single-flight or staggered/jittered TTLs.
+- Caching user-specific or sensitive data in a shared/edge cache → leaks across users; scope cache keys and mark private responses appropriately.
+
+## Examples
+```text
+Cache-aside read path:
+  1. value = cache.get(key)
+  2. if hit: return value
+  3. value = db.query(...)        # miss
+  4. cache.set(key, value, TTL)   # populate with expiry
+  5. return value
+# On write: db.update(...); cache.del(key)  (or update in place)
+```
+
+## Further reading
+- Redis develop docs (clients, data types, pub/sub): https://redis.io/docs/latest/develop/
+- AWS caching overview (database, session, API caching): https://aws.amazon.com/caching/
+
+## Related skills
+- ../system-design-fundamentals — latency/throughput trade-offs caching addresses
+- ../api-design-rest-graphql — HTTP caching of API responses
+- ../scalability-reliability — caching to offload origins under load

package/skills/engineering/architecture/data-modeling/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: data-modeling
+description: Relational and document data modeling — tables, keys, constraints, normalization, and when to denormalize; read before designing a schema.
+domain: engineering
+category: architecture
+tags: [data-modeling, relational, normalization, constraints, schema-design]
+official_sources:
+  - https://www.postgresql.org/docs/current/ddl.html
+verified: 2026-06-16
+---
+
+# Data Modeling
+
+## Overview
+Data modeling is the design of how data is structured, related, and constrained so it stays correct and queryable as the system grows. Relational modeling emphasizes normalization and referential integrity enforced by the database; document modeling embeds related data for read locality. Read this before creating a schema, adding a table, or choosing between relational and document storage.
+
+## Official sources
+- PostgreSQL — Data Definition (tables, constraints, keys, schemas, partitioning): https://www.postgresql.org/docs/current/ddl.html
+
+## Core concepts
+- **Tables, columns, and types**: a relational model defines entities as tables with typed columns; choosing correct types and defaults is the first integrity control.
+- **Constraints**: PostgreSQL supports NOT NULL, UNIQUE, CHECK, PRIMARY KEY, FOREIGN KEY, and EXCLUSION constraints — push invariants into the database so invalid data cannot be stored.
+- **Primary and foreign keys**: primary keys uniquely identify rows; foreign keys enforce referential integrity between related tables.
+- **Normalization**: organize data to eliminate redundancy and update anomalies (1NF/2NF/3NF) so each fact lives in exactly one place.
+- **Schemas and namespacing**: schemas group related objects and provide logical organization and access boundaries within a database.
+- **Document vs relational**: document models embed/denormalize related data for single-read access and flexible shape, trading integrity guarantees and join flexibility for read performance.
+
+## Best practices
+- Enforce invariants with database constraints (NOT NULL, UNIQUE, FOREIGN KEY, CHECK) rather than relying only on application code — the DB is the last line of defense.
+- Normalize to remove redundancy first; denormalize deliberately and only when measured read patterns justify it.
+- Always define primary keys and back foreign-key columns with indexes to keep referential checks and joins fast.
+- Choose data types tightly (e.g. proper numeric/timestamp types, generated/identity columns where appropriate) so the database validates and stores values efficiently.
+
+## Common pitfalls
+- Modeling everything as nullable text → loses validation and indexing benefits; use precise types and NOT NULL where the value is required.
+- Skipping foreign keys "for speed" → orphaned and inconsistent rows accumulate; let referential integrity be enforced by the engine.
+- Premature denormalization → duplicated facts drift out of sync; normalize first, denormalize only with evidence.
+
+## Examples
+```sql
+-- Relational schema with keys and constraints (PostgreSQL DDL)
+CREATE TABLE author (
+  id    bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email text NOT NULL UNIQUE
+);
+
+CREATE TABLE post (
+  id        bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  author_id bigint NOT NULL REFERENCES author(id),
+  title     text   NOT NULL CHECK (length(title) > 0),
+  published boolean NOT NULL DEFAULT false
+);
+
+CREATE INDEX ON post (author_id);
+```
+
+## Further reading
+- PostgreSQL constraints reference: https://www.postgresql.org/docs/current/ddl-constraints.html
+- PostgreSQL table partitioning: https://www.postgresql.org/docs/current/ddl-partitioning.html
+
+## Related skills
+- ../system-design-fundamentals — partitioning and sharding at scale
+- ../caching-strategies — caching query results
+- ../api-design-rest-graphql — mapping the model to resources/types

package/skills/engineering/architecture/message-queues-async/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: message-queues-async
+description: Async messaging with queues and logs — delivery guarantees, ordering, and idempotency (Kafka, RabbitMQ); read before decoupling services.
+domain: engineering
+category: architecture
+tags: [messaging, queues, kafka, rabbitmq, idempotency]
+official_sources:
+  - https://kafka.apache.org/documentation/
+  - https://www.rabbitmq.com/tutorials
+verified: 2026-06-16
+---
+
+# Message Queues & Async Messaging
+
+## Overview
+Asynchronous messaging decouples producers from consumers in time and identity, smoothing load spikes and improving resilience. Apache Kafka is a partitioned, replayable log; RabbitMQ is a broker built around queues and exchanges. Both force you to reason about delivery guarantees, ordering, and idempotency. Read this before introducing a queue or event bus between services.
+
+## Official sources
+- Apache Kafka — Documentation (concepts, design, delivery semantics): https://kafka.apache.org/documentation/
+- RabbitMQ — Tutorials (queues, exchanges, work queues, pub/sub): https://www.rabbitmq.com/tutorials
+
+## Core concepts
+- **Kafka topics and partitions**: messages are published to topics split into partitions; ordering is guaranteed only within a single partition, and consumers track position via offsets.
+- **Kafka consumer groups**: a consumer group acts as one logical subscriber across multiple processes; any number of groups can consume the same topic without duplicating data.
+- **Delivery semantics**: systems offer at-most-once (may lose, never redelivers), at-least-once (never loses, may redeliver), or exactly-once. Kafka guarantees at-least-once by default.
+- **Kafka exactly-once**: from Kafka 0.11 the idempotent producer prevents retry-induced duplicates, and transactions with read-committed consumers enable exactly-once across read-process-write.
+- **RabbitMQ exchanges and routing**: producers publish to exchanges that route to queues by binding/routing keys, enabling work queues, publish/subscribe, routing, and topic patterns.
+- **Acknowledgements and confirms**: consumer acks and publisher confirms underpin reliable delivery — a message is only considered handled once acknowledged.
+
+## Best practices
+- Make consumers idempotent: because at-least-once delivery can redeliver messages, design handlers so processing the same message twice has no extra effect.
+- Use Kafka partition keys deliberately when you need per-key ordering, since ordering holds only within a partition.
+- Acknowledge after successful processing (manual acks / publisher confirms), not on receipt, so failures lead to redelivery rather than loss.
+- Reserve exactly-once for when you truly need it (Kafka transactions/idempotent producer); it adds overhead and is not always necessary if consumers are idempotent.
+
+## Common pitfalls
+- Assuming global ordering across a Kafka topic → ordering is per-partition only; key related messages to the same partition if order matters.
+- Acking a message before the work succeeds → message is lost on crash; ack only after the side effects are durable.
+- Ignoring duplicate delivery under at-least-once → double charges/sends; dedupe with idempotency keys or upserts.
+
+## Examples
+```text
+Idempotent consumer under at-least-once delivery:
+  on message m with key m.id:
+    if processed_ids.contains(m.id): ack(m); return   # dedupe
+    do_work(m)
+    processed_ids.add(m.id)
+    ack(m)                                             # ack after success
+```
+
+## Further reading
+- Kafka design — message delivery semantics: https://kafka.apache.org/documentation/#semantics
+- RabbitMQ publisher confirms tutorial: https://www.rabbitmq.com/tutorials/tutorial-seven-java
+
+## Related skills
+- ../software-architecture-patterns — event-driven architecture and queue patterns
+- ../scalability-reliability — queues for load leveling and resilience
+- ../system-design-fundamentals — throughput and partitioning trade-offs

package/skills/engineering/architecture/scalability-reliability/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: scalability-reliability
+description: Scaling, SLIs/SLOs, error budgets, and resilience tactics (timeouts, retries with backoff/jitter, load shedding); read before hardening a service.
+domain: engineering
+category: architecture
+tags: [scalability, reliability, slo, resilience, retries]
+official_sources:
+  - https://sre.google/books/
+  - https://aws.amazon.com/builders-library/
+verified: 2026-06-16
+---
+
+# Scalability & Reliability
+
+## Overview
+Scalability is the ability to handle growing load without proportional cost or latency blowups; reliability is delivering the intended function and recovering quickly from failure. Google's SRE practice frames reliability with SLIs, SLOs, and error budgets; the Amazon Builders' Library documents the concrete tactics — timeouts, retries with backoff and jitter, and load shedding. Read this before hardening a service or setting reliability targets.
+
+## Official sources
+- Google SRE books (SRE, the Workbook, Building Secure & Reliable Systems): https://sre.google/books/
+- Amazon Builders' Library (resilience and operations practices): https://aws.amazon.com/builders-library/
+
+## Core concepts
+- **SLI**: a Service Level Indicator is a quantitative measure of a service quality aspect — common examples are request latency, error rate, and availability.
+- **SLO**: a Service Level Objective is a target value or range for an SLI; it is the goal you operate against.
+- **SLA vs SLO**: an SLA adds explicit consequences (e.g. penalties) for missing targets; without consequences you are looking at an SLO, not an SLA.
+- **Error budget**: rather than demanding perfection, allow a rate at which the SLO may be missed and track it over time to inform release decisions.
+- **Timeouts, retries, backoff, jitter**: timeouts bound how long calls hang; retries mask transient faults; exponential backoff with jitter spreads retries to avoid synchronized spikes and congestion.
+- **Load shedding**: as a server approaches overload it should reject excess requests so it can keep latency low for the requests it does accept.
+
+## Best practices
+- Define a few meaningful SLOs from user-centric SLIs and manage to an error budget; keep aggregations simple and avoid unrealistic absolutes (per the SRE book).
+- Always set timeouts on remote calls so a slow dependency cannot tie up resources indefinitely.
+- Use exponential backoff with jitter for retries to avoid retry storms; consider adaptive retries with a token-bucket retry quota to cap amplification.
+- Be cautious with retries against an overloaded dependency — retrying a struggling system amplifies load; retry only when the dependency appears healthy, and shed load when overloaded.
+
+## Common pitfalls
+- Retrying without backoff/jitter → synchronized retry storms amplify an outage; add exponential backoff plus jitter.
+- Targeting 100% reliability → unsustainable and pointless past user perception; set an SLO with an error budget instead.
+- No timeouts on dependency calls → one slow dependency exhausts threads/connections and cascades the failure.
+
+## Examples
+```text
+Resilient remote call:
+  deadline = now + timeout
+  for attempt in 0..maxRetries:
+    try: return call(deadline)
+    except transient:
+      if dependencyUnhealthy(): break        # don't amplify overload
+      sleep( random(0, base * 2**attempt) )   # exponential backoff + jitter
+  raise Unavailable
+# Server side: if nearOverload(): reject(503)  # load shedding
+```
+
+## Further reading
+- SRE book — Service Level Objectives chapter: https://sre.google/sre-book/service-level-objectives/
+- Amazon Builders' Library — Timeouts, retries, and backoff with jitter: https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
+- Amazon Builders' Library — Using load shedding to avoid overload: https://aws.amazon.com/builders-library/using-load-shedding-to-avoid-overload/
+
+## Related skills
+- ../system-design-fundamentals — latency, throughput, and scaling trade-offs
+- ../message-queues-async — queues for load leveling and decoupling
+- ../caching-strategies — offloading origins to absorb load

package/skills/engineering/architecture/software-architecture-patterns/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: software-architecture-patterns
+description: Layered, hexagonal, event-driven, and microservices patterns plus cloud design patterns; read when choosing or structuring application architecture.
+domain: engineering
+category: architecture
+tags: [architecture-patterns, microservices, event-driven, layered, cloud-patterns]
+official_sources:
+  - https://martinfowler.com/architecture/
+  - https://learn.microsoft.com/azure/architecture/patterns/
+verified: 2026-06-16
+---
+
+# Software Architecture Patterns
+
+## Overview
+Architecture patterns are reusable, named solutions to recurring structural problems — how to separate concerns, communicate between components, and contain failure. Each pattern solves one problem and introduces trade-offs, so choose by the problem you face, not the technology you want. Read this when structuring a new service or evaluating a refactor.
+
+## Official sources
+- Martin Fowler's Software Architecture Guide: https://martinfowler.com/architecture/
+- Azure Architecture Center — Cloud Design Patterns catalog: https://learn.microsoft.com/azure/architecture/patterns/
+
+## Core concepts
+- **Layered (Presentation–Domain–Data)**: separate the UI, business logic, and data-access concerns so each can change independently; the dominant default for most applications.
+- **Hexagonal / Ports & Adapters**: isolate the domain core behind explicit ports, with adapters for UI, persistence, and external systems, so infrastructure is swappable and the core is testable.
+- **Event-driven architecture**: components communicate by emitting and reacting to events (often via Publisher-Subscriber), decoupling producers from consumers in time and identity.
+- **Microservices**: develop a single application as a suite of small services, each in its own process, communicating over lightweight mechanisms — independently deployable but distributed.
+- **Cloud design patterns**: technology-agnostic solutions (Circuit Breaker, Retry, Cache-Aside, CQRS, Saga, Bulkhead, Strangler Fig) that address reliability, scale, and integration in distributed systems.
+- **Patterns are composable**: real workloads apply several together (e.g. Retry + Circuit Breaker; Queue-Based Load Leveling + Competing Consumers).
+
+## Best practices
+- Choose a pattern from the problem and acceptable trade-offs, not from the technology — the Azure catalog explicitly advises starting from a constraint or risk in the workload.
+- Default to a well-structured monolith with clear layering; adopt microservices only when team/scale boundaries justify the distributed-systems cost.
+- Pair resilience patterns: combine Retry with Circuit Breaker so transient faults are retried but persistent faults stop hammering a failing dependency.
+- Use the Strangler Fig pattern to migrate legacy systems incrementally instead of a risky big-bang rewrite.
+
+## Common pitfalls
+- Adopting microservices for a small team or early product → you inherit network, consistency, and ops overhead without the scale benefit; keep a modular monolith until boundaries are clear.
+- Believing distributed systems are reliable, low-latency, and infinitely scalable (the fallacies of distributed computing) → design compensations (timeouts, retries, idempotency) for each fallacy.
+- Treating an antipattern as a pattern because it works at low load → re-evaluate designs that degrade as traffic grows.
+
+## Examples
+```text
+Resilient remote call (Azure pattern combo):
+  client -> [Retry with backoff] -> [Circuit Breaker] -> remote service
+  - Retry handles transient faults.
+  - Circuit Breaker opens after repeated failures, failing fast and shedding load.
+```
+
+## Further reading
+- Azure pattern catalog with per-pattern problem/trade-off pages: https://learn.microsoft.com/azure/architecture/patterns/
+- Fowler on microservices: https://martinfowler.com/articles/microservices.html
+
+## Related skills
+- ../message-queues-async — event-driven and async messaging foundations
+- ../scalability-reliability — resilience patterns under load
+- ../api-design-rest-graphql — designing the interfaces between services

package/skills/engineering/architecture/system-design-fundamentals/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: system-design-fundamentals
+description: Latency, throughput, partitioning, replication, CAP and consistency trade-offs for designing large-scale systems; read before sizing or scaling.
+domain: engineering
+category: architecture
+tags: [system-design, scalability, cap-theorem, distributed-systems, trade-offs]
+official_sources:
+  - https://github.com/donnemartin/system-design-primer
+  - https://aws.amazon.com/architecture/well-architected/
+verified: 2026-06-16
+---
+
+# System Design Fundamentals
+
+## Overview
+System design is the practice of reasoning about how a large-scale system meets functional and non-functional requirements (latency, throughput, availability, cost) under failure. Every choice is a trade-off: there is no single "correct" design, only one that is appropriate for the constraints. Read this before sizing a component, choosing a datastore, or proposing a scaling strategy.
+
+## Official sources
+- The System Design Primer (concepts, trade-offs, interview material): https://github.com/donnemartin/system-design-primer
+- AWS Well-Architected Framework (pillars and review methodology): https://aws.amazon.com/architecture/well-architected/
+
+## Core concepts
+- **Latency vs throughput**: latency is the time to perform one action; throughput is the number of actions per unit of time. Aim for maximal throughput within an acceptable latency budget — they are not the same dial.
+- **CAP theorem**: in a distributed system that may experience network partitions you must trade off between consistency and availability; you cannot fully guarantee all three of consistency, availability, and partition tolerance at once.
+- **Partitioning / sharding**: split data across nodes so each holds only a subset, improving capacity and performance, at the cost of cross-shard queries, rebalancing, and possible hotspots/skew.
+- **Replication and availability patterns**: copy data across nodes for read scaling and fault tolerance; fail-over comes in active-passive and active-active flavors, each trading complexity for recovery speed.
+- **Consistency models**: strong, eventual, and causal consistency offer different guarantees; eventual consistency buys availability and scale but requires the application to tolerate stale reads.
+- **Well-Architected pillars**: AWS frames sound design around Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, and Sustainability — use them as a review checklist.
+
+## Best practices
+- Quantify requirements first (expected QPS, data size, read/write ratio, latency SLO) before choosing technology — the numbers drive the design, per the System Design Primer's estimation approach.
+- Make trade-offs explicit and document them; the Well-Architected method is a structured review against the six pillars, not a single answer.
+- Design for failure: assume nodes, networks, and dependencies will fail and add replication, retries, and graceful degradation accordingly.
+- Prefer horizontal scaling and statelessness for the request path so you can add commodity capacity rather than relying on a single large machine.
+
+## Common pitfalls
+- Treating CAP as "pick any two freely" → during a partition you are really choosing between consistency and availability; partition tolerance is mandatory in real distributed systems.
+- Sharding on a key with skewed access → creates hotspots; choose a partition key with even distribution and plan for resharding.
+- Optimizing latency while ignoring throughput (or vice versa) → measure both and set explicit targets.
+
+## Examples
+```text
+Back-of-envelope sizing (per System Design Primer estimation):
+  10M daily active users x 10 requests/day = 100M req/day
+  100M / 86,400 s  ≈ 1,160 req/s average, ~3-5x peak ≈ ~5,000 req/s
+  Plan capacity, caching, and partitions against peak, not average.
+```
+
+## Further reading
+- AWS Well-Architected pillars overview: https://aws.amazon.com/architecture/well-architected/
+- System Design Primer index of topics: https://github.com/donnemartin/system-design-primer#index-of-system-design-topics
+
+## Related skills
+- ../scalability-reliability — SLOs, resilience, and failure handling at scale
+- ../caching-strategies — reduce latency and load with cache layers
+- ../data-modeling — how data shape interacts with partitioning

package/skills/engineering/backend/auth-and-authorization/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: backend/auth-and-authorization
+description: Authentication vs authorization, OAuth 2.0 roles and tokens, and access-control models (RBAC/ABAC) with OWASP enforcement guidance.
+domain: engineering
+category: engineering
+tags: [auth, authentication, authorization, oauth2, rbac, abac, security]
+official_sources:
+  - https://oauth.net/2/
+  - https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+verified: 2026-06-16
+---
+
+# Authentication and Authorization
+
+## Overview
+Authentication (AuthN) verifies *who* a caller is; authorization (AuthZ) decides *what* they are allowed to do. This skill covers that distinction, the OAuth 2.0 authorization framework and its tokens, the RBAC/ABAC access-control models, and OWASP's rules for enforcing authorization safely. Read it when designing login, API access control, or permission checks.
+
+## Official sources
+- OAuth 2.0: https://oauth.net/2/
+- OWASP Authorization Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
+- OAuth 2.0 spec (RFC 6749): https://www.rfc-editor.org/rfc/rfc6749
+
+## Core concepts
+- **AuthN vs AuthZ.** Authentication confirms identity; authorization, per OWASP, "verif[ies] that a requested action or service is approved for a specific entity." An authenticated user may still lack authorization for a given resource.
+- **OAuth 2.0 is an authorization framework, not authentication.** It is "the industry-standard protocol for authorization," defining flows for web, mobile, desktop, and device clients (RFC 6749).
+- **OAuth roles.** Resource owner, client, authorization server, and resource server cooperate; the client obtains an **access token** to call the resource server on the owner's behalf.
+- **Tokens.** Access tokens (often Bearer tokens, RFC 6750) authorize API calls; refresh tokens obtain new access tokens. PKCE protects public clients, and OAuth 2.1 is an in-progress consolidation of OAuth 2.0 plus common extensions.
+- **RBAC.** Role-based access control ties permissions to roles assigned to users — simple to start, but can grow unwieldy as roles multiply.
+- **ABAC / ReBAC.** Attribute-based (subject/object/environment attributes + policies) and relationship-based access control support fine-grained, multi-tenant logic that RBAC handles poorly.
+
+## Best practices
+- Enforce authorization **server-side** on every request — never trust client-side checks alone (OWASP).
+- **Deny by default:** grant access only when a rule explicitly permits it, so logic gaps fail closed (OWASP).
+- Apply **least privilege:** give each entity the minimum permissions for its role, and audit periodically to prevent privilege creep (OWASP).
+- Check authorization on the **specific resource**, not just the route, and avoid exposing predictable object identifiers to prevent IDOR-style access (OWASP).
+
+## Common pitfalls
+- Treating authentication as if it grants authorization → always run a separate AuthZ check after identifying the user.
+- Relying on hidden fields or client-side role checks → enforce every decision on the server (OWASP).
+- Using OAuth 2.0 access tokens as proof of identity → use OpenID Connect for authentication; OAuth alone is for authorization.
+- Direct object references without a per-resource access check → verify the caller may act on *that* object (OWASP, IDOR).
+
+## Examples
+```http
+# Calling a protected API with an OAuth 2.0 Bearer access token (RFC 6750)
+GET /api/orders/1001 HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+```text
+Deny-by-default authorization check (pseudocode):
+  if not policy.permits(subject, action, resource): return 403
+  proceed
+```
+
+## Further reading
+- OAuth 2.0 Bearer Token Usage (RFC 6750): https://www.rfc-editor.org/rfc/rfc6750
+- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
+
+## Related skills
+- ./backend-fundamentals — the HTTP layer these checks protect
+- ./observability-logging — logging authorization failures for audit

package/skills/engineering/backend/backend-fundamentals/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: backend/backend-fundamentals
+description: Core backend ideas — HTTP request/response, statelessness, layered architecture, and the twelve-factor app methodology for cloud services.
+domain: engineering
+category: engineering
+tags: [backend, http, stateless, twelve-factor, architecture, web]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/HTTP
+  - https://12factor.net/
+verified: 2026-06-16
+---
+
+# Backend Fundamentals
+
+## Overview
+This skill covers the foundations every backend service rests on: how HTTP works as a stateless request/response protocol, why statelessness matters for scaling, how to layer an application, and the twelve-factor methodology for building portable cloud services. Read it before designing an API or deployment, and as a checklist when a service is hard to scale or configure across environments.
+
+## Official sources
+- HTTP (MDN): https://developer.mozilla.org/en-US/docs/Web/HTTP
+- The Twelve-Factor App: https://12factor.net/
+- Repo (twelve-factor): https://github.com/heroku/12factor
+
+## Core concepts
+- **HTTP is a stateless, application-layer protocol.** Per MDN, the server "does not keep any session data between two requests"; state is layered on top via cookies, tokens, or external stores.
+- **Request/response, client-server model.** A client opens a connection, sends a request (method + path + headers + optional body), and waits for a single response.
+- **Methods and status codes carry semantics.** Methods (GET, POST, PUT, PATCH, DELETE, …) express intent; status codes group as 1xx informational, 2xx success, 3xx redirect, 4xx client error, 5xx server error.
+- **Statelessness enables horizontal scale.** Twelve-factor says to "execute the app as one or more stateless processes" so any instance can serve any request and you scale by adding processes.
+- **Config lives in the environment.** Store deploy-specific config (URLs, credentials, flags) in environment variables, not in code, keeping the codebase portable and secrets out of version control.
+- **Layering.** Separate concerns into transport/routing, application/service logic, and data-access layers so each can change and be tested independently.
+- **Twelve factors at a glance.** Codebase, dependencies, config, backing services, build/release/run, processes, port binding, concurrency, disposability, dev/prod parity, logs, admin processes.
+
+## Best practices
+- Keep request handling stateless; persist session/state in a backing service (DB, cache) rather than in process memory (twelve-factor: processes, backing services).
+- Treat backing services (databases, queues, caches) as attached resources swappable via config, with no code change.
+- Build, release, and run as distinct stages so a release is an immutable artifact + config you can roll back.
+- Use the correct HTTP method and status code for each operation so caches, clients, and proxies behave correctly (MDN).
+
+## Common pitfalls
+- Storing session state in process memory → breaks under multiple instances; move it to a shared backing service.
+- Hardcoding environment-specific config or secrets in code → read them from the environment (twelve-factor: config).
+- Returning 200 for errors or overloading GET to mutate data → honor HTTP method and status-code semantics (MDN).
+
+## Examples
+```http
+GET /api/users/42 HTTP/1.1
+Host: api.example.com
+Accept: application/json
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{ "id": 42, "name": "Ada" }
+```
+```bash
+# Twelve-factor: config from the environment, not the code
+export DATABASE_URL="postgres://user:pass@host:5432/app"
+```
+
+## Further reading
+- MDN HTTP overview: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview
+- Twelve-factor — full factor list: https://12factor.net/
+
+## Related skills
+- ./auth-and-authorization — securing the requests these services receive
+- ./observability-logging — the "logs" factor and operating the service in production

package/skills/engineering/backend/observability-logging/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: backend/observability-logging
+description: Observability via the three signals (logs, metrics, traces) with OpenTelemetry, plus SRE practices like SLOs and the four golden signals.
+domain: engineering
+category: engineering
+tags: [observability, logging, metrics, tracing, opentelemetry, sre, slo]
+official_sources:
+  - https://opentelemetry.io/docs/
+  - https://sre.google/books/
+verified: 2026-06-16
+---
+
+# Observability and Logging
+
+## Overview
+Observability is the ability to understand a system's internal state from its outputs. This skill covers the three telemetry signals — logs, metrics, and traces — instrumented in a vendor-neutral way with OpenTelemetry, and the operational practices Google SRE uses to act on that data (SLIs/SLOs, error budgets, the four golden signals). Read it when adding instrumentation, choosing what to log, or defining what "healthy" means for a service.
+
+## Official sources
+- OpenTelemetry docs: https://opentelemetry.io/docs/
+- Repo (OpenTelemetry org): https://github.com/open-telemetry
+- Google SRE books (free online): https://sre.google/books/
+
+## Core concepts
+- **Three signals.** OpenTelemetry standardizes **traces** (the path of a request across services), **metrics** (numeric measurements over time), and **logs** (timestamped records of discrete events).
+- **OpenTelemetry is instrumentation, not a backend.** It is "a vendor-neutral open source Observability framework for instrumenting, generating, collecting, and exporting telemetry data" — it does not store or visualize data; you send it to a backend.
+- **The Collector.** A vendor-agnostic process to receive, process, and export telemetry, decoupling your app from any specific backend.
+- **OTLP and vendor neutrality.** A common wire protocol and broad vendor support (90+ observability vendors) let you switch tools without re-instrumenting, avoiding lock-in.
+- **SLIs and SLOs.** A Service Level Indicator is a measured quality (e.g. request latency); a Service Level Objective is a target for it. Error budgets quantify allowable unreliability against the SLO (Google SRE).
+- **The four golden signals.** Google SRE recommends monitoring **latency, traffic, errors, and saturation** as the primary health signals of a user-facing system.
+
+## Best practices
+- Emit structured logs (e.g. JSON with consistent fields) and correlate them with traces via trace/span IDs so you can pivot between signals.
+- Instrument with OpenTelemetry rather than vendor-specific SDKs so the backend stays swappable.
+- Define SLOs for the user-facing behaviors that matter and alert on SLO burn / the four golden signals, not on every raw metric (Google SRE).
+- Run the OpenTelemetry Collector to centralize processing (batching, attribute scrubbing, routing) instead of exporting directly from every service.
+
+## Common pitfalls
+- Treating OpenTelemetry as a storage/visualization product → it only generates and ships telemetry; pair it with a backend.
+- Logging unstructured free text → emit structured, queryable fields and avoid logging secrets/PII.
+- Alerting on raw resource metrics with no SLO → alert on user-impacting symptoms (golden signals / SLO burn) to cut noise (Google SRE).
+
+## Examples
+```text
+A single user request, observed across the three signals:
+  trace : frontend → orders-api → payments-api (spans with timing)
+  metric: http.server.duration, error.rate, queue.saturation
+  log   : {"level":"error","trace_id":"abc123","msg":"payment declined"}
+```
+```text
+Four golden signals to dashboard/alert on:
+  latency · traffic · errors · saturation
+```
+
+## Further reading
+- OpenTelemetry — what is observability: https://opentelemetry.io/docs/concepts/observability-primer/
+- SRE Book, Monitoring Distributed Systems (golden signals): https://sre.google/sre-book/monitoring-distributed-systems/
+
+## Related skills
+- ./backend-fundamentals — the "logs" twelve-factor concern and service operation
+- ./auth-and-authorization — logging authorization failures for audit