codecall 1.3.0 → 1.5.0

package/plugins/codecall/skills/codecall/references/backend-map/caching.md

@@ -0,0 +1,65 @@
+# Caching
+
+## cache-aside
+
+- **Name:** Cache-aside pattern
+- **Requires:** none
+- **Signals:** `redis.get(` then `redis.set(`, `cache.get_or_set(`, `@Cacheable`, `SETEX`, `if cached == nil`
+- **Idea:** The application checks the cache first, and on a miss reads the database and stores the result, so repeated reads skip the slow store while the database stays the source of truth.
+- **Misconceptions:**
+  - A cache miss is harmless; when a hot key expires, many requests miss together and stampede the database unless one request refills it.
+  - The cache is always available; if it is down or slow, your code should fall back to the database rather than fail the request.
+- **Checks:**
+  - If the cached key for this endpoint expires during peak traffic, how many requests in your code hit the database at once to rebuild it?
+  - What does your handler do when the cache call times out, and does that turn a cache outage into a full outage?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 1:17:35](https://www.youtube.com/watch?v=z7kt_p44rjs&t=4655s)
+  - [Microsoft Learn: Cache-Aside pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside)
+
+## cache-invalidation
+
+- **Name:** Cache invalidation
+- **Requires:** `cache-aside`
+- **Signals:** `redis.del(`, `cache.delete(`, `@CacheEvict`, `revalidateTag(`, `user:${id}` cache keys, `PUBLISH` invalidation event
+- **Idea:** When the underlying data changes, cached copies must be deleted or updated, otherwise readers keep getting the old value until it happens to expire.
+- **Misconceptions:**
+  - Deleting the key before the database write is safe; a concurrent reader can refill the old value in between, so update first, then delete.
+  - Invalidating one key is enough; lists, counts and aggregates that include the changed row are cached under other keys too.
+- **Checks:**
+  - After your code updates this record, which cached keys still contain the old value, including lists or summaries that embed it?
+  - If the database write succeeds but your cache delete fails, how long does stale data survive, and what bounds it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 1:17:35](https://www.youtube.com/watch?v=z7kt_p44rjs&t=4655s)
+  - [Microsoft Learn: Caching guidance](https://learn.microsoft.com/en-us/azure/architecture/best-practices/caching)
+
+## cache-eviction-ttl
+
+- **Name:** Eviction policies and TTLs
+- **Requires:** `cache-aside`
+- **Signals:** `EX 300`, `EXPIRE`, `maxmemory-policy`, `allkeys-lru`, `ttl=`, `lru-cache`
+- **Idea:** A TTL bounds how stale an entry can get, while an eviction policy decides what to drop when memory fills, together keeping the cache fresh and within its size.
+- **Misconceptions:**
+  - A longer TTL is always better; it raises the hit rate but also how long users see outdated data after a change.
+  - Unbounded in-process caches are fine; without a size limit they grow until the process runs out of memory.
+- **Checks:**
+  - How stale can the data your code caches safely be, and does the TTL you chose match that rather than a round number?
+  - If many keys in your code share one TTL and were written together, what happens to the database when they all expire at once?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #13 · 42:48](https://www.youtube.com/watch?v=estH64OkwxU&t=2568s)
+  - [Redis docs: Key eviction](https://redis.io/docs/latest/develop/reference/eviction/)
+
+## cdn-edge-caching
+
+- **Name:** CDNs and edge caching
+- **Requires:** `http-caching-headers`
+- **Signals:** `Cache-Control: public, s-maxage=`, `Surrogate-Key`, `CDN-Cache-Control`, `Vary`, `CF-Cache-Status`, purge API call
+- **Idea:** A CDN keeps copies of responses at servers near users, cutting latency and origin load, with your cache headers deciding what is shared and for how long.
+- **Misconceptions:**
+  - Only static files belong on a CDN; public API responses can be edge-cached too with short `s-maxage` and stale-while-revalidate.
+  - Marking a response `public` is harmless; if it is personalized and the cache key ignores the cookie, the CDN serves one user's data to others.
+- **Checks:**
+  - Does any response your code marks cacheable depend on the cookie, auth header or language, and how does the CDN key keep users apart?
+  - After your code updates content, how does the edge copy get refreshed: by TTL expiry, a purge call or a versioned URL?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.2 · 51:22](https://www.youtube.com/watch?v=sOhAopEwjH4&t=3082s)
+  - [Cloudflare docs: Origin Cache Control](https://developers.cloudflare.com/cache/concepts/cache-control/)

package/plugins/codecall/skills/codecall/references/backend-map/data.md

@@ -0,0 +1,144 @@
+# Databases
+
+## schema-design-constraints
+
+- **Name:** Schema design and constraints
+- **Requires:** none
+- **Signals:** `NOT NULL`, `UNIQUE`, `REFERENCES`, `CHECK (`, `ON DELETE CASCADE`, `unique=True`
+- **Idea:** Types and constraints encode rules your data must always obey, so the database rejects bad rows even when a code path forgets to validate.
+- **Misconceptions:**
+  - App validation makes constraints redundant; scripts, races and other services bypass it, and only the database sees every write.
+  - Foreign keys are just slow; they prevent orphaned rows, and their cost is usually an index on the referencing column.
+- **Checks:**
+  - Which rule in your change lives only in application code, and what bad row could a concurrent request or script insert?
+  - What should happen to child rows when the parent is deleted, and does your `ON DELETE` choice match?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #12 · 1:01:37](https://www.youtube.com/watch?v=F7Vwp2Xo5Do&t=3697s)
+  - [PostgreSQL docs: Constraints](https://www.postgresql.org/docs/current/ddl-constraints.html)
+
+## database-migrations
+
+- **Name:** Database migrations
+- **Requires:** `schema-design-constraints`
+- **Signals:** `migrations/`, `ALTER TABLE`, `knex migrate`, `alembic upgrade`, `manage.py migrate`, `CREATE INDEX CONCURRENTLY`
+- **Idea:** Versioned, ordered scripts change the schema the same way in every environment, and must stay compatible with the code version still running during deploys.
+- **Misconceptions:**
+  - Migrations are instant; adding a constraint or rewriting a big table can block writes for minutes.
+  - Renaming or dropping a column in one step is fine; old instances still query it mid-deploy, so expand first and contract later.
+- **Checks:**
+  - On a large production table, what locks does your migration take, and which requests wait behind it?
+  - If this deploy rolls back after your migration ran, can the previous code still use the new schema?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #12 · 53:33](https://www.youtube.com/watch?v=F7Vwp2Xo5Do&t=3213s)
+  - [Martin Fowler: Evolutionary Database Design](https://martinfowler.com/articles/evodb.html)
+
+## database-indexes
+
+- **Name:** Database indexes
+- **Requires:** `schema-design-constraints`
+- **Signals:** `CREATE INDEX`, `EXPLAIN ANALYZE`, `Seq Scan`, `@@index([`, `db_index=True`, composite `(user_id, created_at)`
+- **Idea:** An index is a sorted lookup structure that finds matching rows without scanning the table, trading write cost and storage for fast reads.
+- **Misconceptions:**
+  - More indexes are always better; every insert and update must maintain each one, and unused indexes only cost writes.
+  - A composite index helps any query on its columns; it serves filters on its leading columns, so column order matters.
+- **Checks:**
+  - Does `EXPLAIN` show an index scan for your main query, and which column order serves both its filter and `ORDER BY`?
+  - Which new index in your code slows a write-heavy table, and is the read it speeds up worth it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 53:55](https://www.youtube.com/watch?v=z7kt_p44rjs&t=3235s)
+  - [PostgreSQL docs: Indexes](https://www.postgresql.org/docs/current/indexes.html)
+
+## n-plus-one-queries
+
+- **Name:** The N+1 query problem
+- **Requires:** none
+- **Signals:** `await` inside a `for` loop, `select_related(`, `prefetch_related(`, `.includes(`, `DataLoader`
+- **Idea:** Loading a list then querying once per item turns one page into N+1 round trips, so fetch related data in a join or one batched query.
+- **Misconceptions:**
+  - Each query is fast, so it is fine; round-trip latency multiplies with N and grows silently as data grows.
+  - The ORM handles it; lazy-loaded relations accessed in templates or serializers are exactly what triggers it.
+- **Checks:**
+  - If your endpoint returns 100 items, how many queries does your code send, and where does each extra one start?
+  - Would a join or one `WHERE id IN (...)` batch suit your code better, given how many related rows each item has?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 42:55](https://www.youtube.com/watch?v=z7kt_p44rjs&t=2575s)
+  - [Microsoft Learn: Efficient Querying in EF Core](https://learn.microsoft.com/en-us/ef/core/performance/efficient-querying)
+
+## connection-pooling
+
+- **Name:** Connection pooling
+- **Requires:** none
+- **Signals:** `new Pool(`, `pool.connect()`, `SetMaxOpenConns`, `pool_size=`, `maximumPoolSize`, `PgBouncer`
+- **Idea:** Opening a database connection is slow and servers allow few of them, so a pool keeps a bounded set open and lends them to requests.
+- **Misconceptions:**
+  - A bigger pool means more throughput; past the database's capacity, extra connections add contention, and replicas multiply the total.
+  - Connections return themselves; a client not released on an error path leaks until the pool is empty.
+- **Checks:**
+  - Given your pool size and maximum instance count, how many connections could hit the database at peak, versus its `max_connections`?
+  - On the error path in your handler, what guarantees the connection or transaction is released back to the pool?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 1:07:20](https://www.youtube.com/watch?v=z7kt_p44rjs&t=4040s)
+  - [Go docs: Managing connections](https://go.dev/doc/database/manage-connections)
+
+## transactions-isolation
+
+- **Name:** Transactions and isolation levels
+- **Requires:** `schema-design-constraints`
+- **Signals:** `BEGIN` / `COMMIT`, `SERIALIZABLE`, `SELECT ... FOR UPDATE`, `@Transactional`, `transaction.atomic`
+- **Idea:** A transaction makes statements succeed or fail together, and its isolation level decides which concurrency anomalies, like lost updates, your code can still see.
+- **Misconceptions:**
+  - A transaction alone prevents races; at the default Read Committed, read-then-write logic still loses updates without row locks or stronger isolation.
+  - Serializable needs no code changes; it aborts conflicting transactions with serialization errors your code must retry.
+- **Checks:**
+  - If two requests run your read-then-update code at the same moment, what isolation level or lock stops one from overwriting the other?
+  - Does your transaction stay open across a network call, and how long could it hold locks?
+- **Go deeper:**
+  - [PostgreSQL docs: Transaction Isolation](https://www.postgresql.org/docs/current/transaction-iso.html)
+
+## optimistic-concurrency
+
+- **Name:** Optimistic concurrency and conditional writes
+- **Requires:** `transactions-isolation`
+- **Signals:** `version` column, `WHERE id = $1 AND version = $2`, `If-Match`, `@Version`, `ConditionExpression`, `rowCount === 0`
+- **Idea:** Instead of locking, a write succeeds only if the row still matches the version you read, so concurrent edits are detected rather than silently overwritten.
+- **Misconceptions:**
+  - The update succeeded because no error was thrown; zero affected rows is the conflict signal, and code must check it.
+  - Optimistic always beats locking; under heavy contention most writes fail and retry, so pessimistic locks can be cheaper.
+- **Checks:**
+  - When your update affects zero rows because the version changed, what does your code return, and is the user's edit lost?
+  - How often do two writers touch the same row in your feature, and does that favor version checks or `SELECT ... FOR UPDATE`?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #23 · 1:03:09](https://www.youtube.com/watch?v=Ie0TjKI9cDI&t=3789s)
+  - [Martin Fowler: Optimistic Offline Lock](https://martinfowler.com/eaaCatalog/optimisticOfflineLock.html)
+
+## read-replicas-sharding
+
+- **Name:** Read replicas and sharding
+- **Requires:** `database-indexes`
+- **Signals:** `DATABASE_REPLICA_URL`, `readReplicas(`, `using('replica')`, `shard_key`, `tenant_id` routing, `replication lag`
+- **Idea:** Replicas copy the primary to spread reads, while sharding splits data across databases by key to spread writes, each adding consistency and routing costs.
+- **Misconceptions:**
+  - A replica read right after a write returns that write; asynchronous replication lags, so read-your-writes needs the primary.
+  - Sharding is the first fix for a slow database; indexes, caching and replicas come first, since cross-shard queries are hard.
+- **Checks:**
+  - After your code writes a row, which following read could hit a lagging replica, and what would the user see?
+  - If your table were sharded by the key your code uses, which query would need to touch every shard?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.2 · 27:47](https://www.youtube.com/watch?v=sOhAopEwjH4&t=1667s)
+  - [Microsoft Learn: Sharding pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/sharding)
+
+## full-text-search
+
+- **Name:** Full-text search and inverted indexes
+- **Requires:** `database-indexes`
+- **Signals:** `to_tsvector(`, `@@ to_tsquery`, `USING GIN`, `ILIKE '%`, `_search` (Elasticsearch), `pg_trgm`
+- **Idea:** An inverted index maps each normalized word to the documents containing it, giving ranked, stemmed search that `LIKE` scans cannot match at scale.
+- **Misconceptions:**
+  - `ILIKE '%term%'` with a B-tree index is fast; a leading wildcard cannot use it, so every row is scanned.
+  - The search engine is the source of truth; it is an eventually consistent copy needing reindexing on change.
+- **Checks:**
+  - On a million rows, does your search query use an index that supports word matching and ranking?
+  - When a record changes, how does your code update the search index, and how stale can results get?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #15 · 8:48](https://www.youtube.com/watch?v=7_sovzAhRSM&t=528s)
+  - [PostgreSQL docs: Full Text Search Introduction](https://www.postgresql.org/docs/current/textsearch-intro.html)

package/plugins/codecall/skills/codecall/references/backend-map/http.md

@@ -0,0 +1,97 @@
+# HTTP
+
+## http-messages
+
+- **Name:** HTTP request and response anatomy
+- **Requires:** none
+- **Signals:** `req.headers`, `Content-Type`, `res.status(`, `request.body`, `http.ResponseWriter`, `w.Header().Set(`
+- **Idea:** Every HTTP exchange is a request (method, path, headers, optional body) answered by a response (status, headers, optional body), and handlers only work when they read and write each part deliberately.
+- **Misconceptions:**
+  - The body explains itself; servers parse it according to the `Content-Type` header, so a missing or wrong header gives you an empty or garbled body.
+  - Header names are case-sensitive; HTTP treats them case-insensitively, and HTTP/2 and HTTP/3 send them lowercased on the wire.
+- **Checks:**
+  - If a client sends this endpoint form-encoded data instead of JSON, what does your handler receive, and where would you see the mismatch?
+  - Which headers does your handler set on the response, and what would a client do differently if one were missing?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 7:29](https://www.youtube.com/watch?v=a3C1DMswClQ&t=449s)
+  - [MDN: HTTP messages](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Messages)
+
+## http-methods-idempotency
+
+- **Name:** HTTP methods and idempotency
+- **Requires:** `http-messages`
+- **Signals:** `app.get(`, `router.post(`, `@PutMapping`, `@app.delete`, `PATCH`, `http.MethodPost`
+- **Idea:** The method declares intent: GET reads safely, PUT and DELETE are idempotent so repeating them leaves the same state, and POST and PATCH may not be, which decides what clients and proxies can safely retry.
+- **Misconceptions:**
+  - Idempotent means the response is identical every time; it means the server state ends the same, so a second DELETE may return 404 and still be idempotent.
+  - A GET that changes data is fine if the UI only calls it on click; crawlers, prefetchers and retrying proxies will call it too.
+- **Checks:**
+  - If a network timeout makes the client resend this request, what does your handler do to the data the second time?
+  - Your code updates a record with this method; would a client sending only changed fields expect PUT or PATCH semantics, and which does it actually implement?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 18:03](https://www.youtube.com/watch?v=a3C1DMswClQ&t=1083s)
+  - [RFC 9110: HTTP Semantics, Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.2)
+
+## http-status-codes
+
+- **Name:** Status codes as a contract
+- **Requires:** `http-messages`
+- **Signals:** `res.status(404)`, `HttpStatus.CREATED`, `status.HTTP_422_UNPROCESSABLE_ENTITY`, `http.StatusConflict`, `raise HTTPException(`
+- **Idea:** The status code is the machine-readable outcome clients, retries, caches and monitoring act on, so choosing between 2xx, 4xx and 5xx correctly matters more than the message text.
+- **Misconceptions:**
+  - Returning 200 with `{"error": ...}` is harmless; clients, caches and alerting treat it as success and never react to the failure.
+  - 401 and 403 are interchangeable; 401 means not authenticated, 403 means authenticated but not allowed.
+- **Checks:**
+  - When validation fails versus when the database is down, which status does your handler return for each, and would a retrying client behave correctly?
+  - If your handler throws an unexpected error, does the client get a 500 with a safe message, or a 200 or a leaked stack trace?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 38:51](https://www.youtube.com/watch?v=a3C1DMswClQ&t=2331s)
+  - [MDN: HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status)
+
+## cors
+
+- **Name:** CORS and preflight requests
+- **Requires:** `http-messages`
+- **Signals:** `Access-Control-Allow-Origin`, `cors()`, `CORSMiddleware`, `@CrossOrigin`, `OPTIONS` preflight
+- **Idea:** Browsers block scripts from reading cross-origin responses unless the server opts in with CORS headers, and non-simple requests first send an OPTIONS preflight the server must answer.
+- **Misconceptions:**
+  - CORS protects your API from attackers; it only restricts browsers, so curl, scripts and other servers call your endpoints regardless.
+  - `Access-Control-Allow-Origin: *` works with cookies; browsers reject a wildcard on credentialed requests, so the exact origin must be echoed back.
+- **Checks:**
+  - Your frontend sends JSON with an `Authorization` header; which preflight response headers must your server return, and what breaks if OPTIONS hits auth middleware first?
+  - If your code reflects any request `Origin` while allowing credentials, what could a malicious site do with a logged-in user's browser?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 20:07](https://www.youtube.com/watch?v=a3C1DMswClQ&t=1207s)
+  - [MDN: Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS)
+
+## http-caching-headers
+
+- **Name:** HTTP caching headers
+- **Requires:** `http-messages`
+- **Signals:** `Cache-Control`, `ETag`, `If-None-Match`, `304 Not Modified`, `Last-Modified`, `Vary`
+- **Idea:** Response headers tell browsers and CDNs whether and how long they may reuse a response, and validators like ETag let them revalidate cheaply instead of downloading it again.
+- **Misconceptions:**
+  - `no-cache` means never store; it means store but revalidate before each use, while `no-store` forbids storing.
+  - Per-user responses can share a CDN cache safely; without `private` or a correct `Vary`, one user's data can be served to another.
+- **Checks:**
+  - Your endpoint returns user-specific data; which `Cache-Control` value does your code send, and could a shared cache ever serve it to someone else?
+  - After you deploy a change to this response, how long might clients keep seeing the old version, and what in your headers decides that?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 55:20](https://www.youtube.com/watch?v=a3C1DMswClQ&t=3320s)
+  - [MDN: HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching)
+
+## tls-https
+
+- **Name:** TLS and HTTPS
+- **Requires:** `http-messages`
+- **Signals:** `Strict-Transport-Security`, `https.createServer(`, `ListenAndServeTLS`, `ssl_certificate`, `X-Forwarded-Proto`, `rejectUnauthorized`
+- **Idea:** TLS encrypts and authenticates the connection using certificates, so tokens, cookies and data cannot be read or altered in transit and clients know they reached the real server.
+- **Misconceptions:**
+  - Turning off certificate verification in a client is fine for internal calls; it removes the authentication and lets anyone in the path impersonate the server.
+  - HTTPS at the load balancer means the app sees HTTPS; behind a TLS-terminating proxy the app must trust `X-Forwarded-Proto` to know.
+- **Checks:**
+  - Your app sits behind a proxy that terminates TLS; how does your code decide to set `Secure` cookies or build https redirect URLs?
+  - Does any outbound call in your code disable certificate verification, and what would an attacker on that network path gain?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #5 · 1:15:18](https://www.youtube.com/watch?v=a3C1DMswClQ&t=4518s)
+  - [OWASP Cheat Sheet: Transport Layer Security](https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Security_Cheat_Sheet.html)

package/plugins/codecall/skills/codecall/references/backend-map/index.md

@@ -0,0 +1,165 @@
+# Backend concept map: index
+
+Generated by `scripts/backend-map.mjs`; edit the cluster files, not this one.
+
+Use only when the change touches server-side code. Match concepts by what the
+change actually does; signals are hints, not proof. Pick at most four, never
+force a match, and fall back to free-form concepts when nothing fits. Then read
+only the cluster files that hold the chosen ids.
+
+## api.md: API design
+
+| id | requires | signals |
+| --- | --- | --- |
+| routing-params | http-messages | `/users/:id`, `req.params`, `req.query`, `r.PathValue(` |
+| api-versioning | routing-params | `/api/v1/`, `/v2/`, `Deprecation`, `Sunset` |
+| serialization-json | http-messages | `JSON.stringify(`, `json.Marshal(`, `express.json()`, `@JsonProperty` |
+| input-validation | serialization-json | `z.object(`, `pydantic.BaseModel`, `@Valid`, `Joi.object(` |
+| rest-resource-design | routing-params, http-methods-idempotency | `GET /orders/{id}`, `POST /orders`, `/users/{id}/orders`, `Location` |
+| pagination-filtering | rest-resource-design | `LIMIT`, `OFFSET`, `?cursor=`, `starting_after` |
+| openapi-contract | rest-resource-design | `openapi.yaml`, `openapi: 3.1`, `swagger-ui`, `@ApiOperation` |
+
+## architecture.md: Request flow and layering
+
+| id | requires | signals |
+| --- | --- | --- |
+| middleware-pipeline | http-messages | `app.use(`, `next()`, `MIDDLEWARE = [`, `func(next http.Handler)` |
+| request-context | middleware-pipeline | `context.Context`, `r.Context()`, `res.locals`, `req.user` |
+| handler-service-repository | routing-params | `controllers/`, `services/`, `repositories/`, `@Service` |
+| dependency-injection | handler-service-repository | `constructor(private readonly`, `Depends(`, `@Autowired`, `@Injectable()` |
+
+## async.md: Background work and webhooks
+
+| id | requires | signals |
+| --- | --- | --- |
+| background-jobs | - | `BullMQ`, `@shared_task`, `perform_later`, `@Async` |
+| idempotency-keys | http-methods-idempotency | `Idempotency-Key`, `ON CONFLICT DO NOTHING`, `processed_events` |
+| transactional-outbox | transactions-isolation, background-jobs | `outbox_events`, `INSERT INTO outbox`, `FOR UPDATE SKIP LOCKED`, `published_at IS NULL` |
+| webhook-receiver | idempotency-keys | `/webhooks/stripe`, `express.raw(`, `@csrf_exempt`, `switch (event.type)` |
+| webhook-signatures | webhook-receiver | `Stripe-Signature`, `X-Hub-Signature-256`, `crypto.timingSafeEqual`, `hmac.compare_digest` |
+
+## auth.md: Authentication and authorization
+
+| id | requires | signals |
+| --- | --- | --- |
+| session-auth | http-messages | `express-session`, `req.session`, `SESSION_ENGINE`, `connect-redis` |
+| cookie-security | session-auth | `HttpOnly`, `Secure`, `SameSite=Lax`, `__Host-` |
+| jwt-auth | http-messages | `Authorization: Bearer`, `jwt.verify(`, `jsonwebtoken`, `PyJWT` |
+| oauth2-oidc | jwt-auth | `/oauth/authorize`, `code_challenge`, `redirect_uri`, `id_token` |
+| password-hashing | - | `argon2id`, `bcrypt.hash(`, `scrypt`, `PBKDF2` |
+| rbac-authorization | session-auth | `@PreAuthorize`, `hasRole(`, `requireRole(`, `user.role ===` |
+
+## caching.md: Caching
+
+| id | requires | signals |
+| --- | --- | --- |
+| cache-aside | - | `redis.get(`, `redis.set(`, `cache.get_or_set(`, `@Cacheable` |
+| cache-invalidation | cache-aside | `redis.del(`, `cache.delete(`, `@CacheEvict`, `revalidateTag(` |
+| cache-eviction-ttl | cache-aside | `EX 300`, `EXPIRE`, `maxmemory-policy`, `allkeys-lru` |
+| cdn-edge-caching | http-caching-headers | `Cache-Control: public, s-maxage=`, `Surrogate-Key`, `CDN-Cache-Control`, `Vary` |
+
+## data.md: Databases
+
+| id | requires | signals |
+| --- | --- | --- |
+| schema-design-constraints | - | `NOT NULL`, `UNIQUE`, `REFERENCES`, `CHECK (` |
+| database-migrations | schema-design-constraints | `migrations/`, `ALTER TABLE`, `knex migrate`, `alembic upgrade` |
+| database-indexes | schema-design-constraints | `CREATE INDEX`, `EXPLAIN ANALYZE`, `Seq Scan`, `@@index([` |
+| n-plus-one-queries | - | `await`, `for`, `select_related(`, `prefetch_related(` |
+| connection-pooling | - | `new Pool(`, `pool.connect()`, `SetMaxOpenConns`, `pool_size=` |
+| transactions-isolation | schema-design-constraints | `BEGIN`, `COMMIT`, `SERIALIZABLE`, `SELECT ... FOR UPDATE` |
+| optimistic-concurrency | transactions-isolation | `version`, `WHERE id = $1 AND version = $2`, `If-Match`, `@Version` |
+| read-replicas-sharding | database-indexes | `DATABASE_REPLICA_URL`, `readReplicas(`, `using('replica')`, `shard_key` |
+| full-text-search | database-indexes | `to_tsvector(`, `@@ to_tsquery`, `USING GIN`, `ILIKE '%` |
+
+## http.md: HTTP
+
+| id | requires | signals |
+| --- | --- | --- |
+| http-messages | - | `req.headers`, `Content-Type`, `res.status(`, `request.body` |
+| http-methods-idempotency | http-messages | `app.get(`, `router.post(`, `@PutMapping`, `@app.delete` |
+| http-status-codes | http-messages | `res.status(404)`, `HttpStatus.CREATED`, `status.HTTP_422_UNPROCESSABLE_ENTITY`, `http.StatusConflict` |
+| cors | http-messages | `Access-Control-Allow-Origin`, `cors()`, `CORSMiddleware`, `@CrossOrigin` |
+| http-caching-headers | http-messages | `Cache-Control`, `ETag`, `If-None-Match`, `304 Not Modified` |
+| tls-https | http-messages | `Strict-Transport-Security`, `https.createServer(`, `ListenAndServeTLS`, `ssl_certificate` |
+
+## observability.md: Observability
+
+| id | requires | signals |
+| --- | --- | --- |
+| structured-logging | - | `pino`, `structlog`, `log/slog`, `logger.info({` |
+| metrics-monitoring | - | `prom-client`, `prometheus_client`, `/metrics`, `http_requests_total` |
+| distributed-tracing | request-context | `traceparent`, `@opentelemetry/api`, `tracer.start_as_current_span`, `otelhttp.NewHandler` |
+| latency-percentiles | metrics-monitoring | `histogram_quantile(0.99`, `http_request_duration_seconds`, `_bucket{le=`, `p99` |
+
+## ops.md: Configuration and delivery
+
+| id | requires | signals |
+| --- | --- | --- |
+| config-management | - | `process.env`, `os.environ`, `os.Getenv(`, `BaseSettings` |
+| secrets-management | config-management | `.env.example`, `aws secretsmanager`, `vault kv get`, `secretKeyRef` |
+| disposable-processes | stateless-services, graceful-shutdown | `SIGTERM`, `terminationGracePeriodSeconds`, `process.on("SIGTERM"`, `signal.NotifyContext` |
+| ci-pipeline | - | `.github/workflows/`, `.gitlab-ci.yml`, `on: pull_request`, `actions/cache` |
+| container-images | - | `Dockerfile`, `FROM node:22-alpine AS build`, `COPY package*.json ./`, `.dockerignore` |
+| deployment-strategies | load-balancing | `strategy: RollingUpdate`, `maxUnavailable`, `maxSurge`, `canary` |
+| infrastructure-as-code | - | `resource "aws_`, `terraform plan`, `.tfstate`, `pulumi up` |
+| slos-incidents | metrics-monitoring | `slo:`, `error_budget`, `histogram_quantile(`, `burn rate` |
+
+## quality.md: Testing
+
+| id | requires | signals |
+| --- | --- | --- |
+| test-pyramid | - | `describe(`, `pytest`, `func TestX(t *testing.T)`, `@SpringBootTest` |
+| test-doubles | dependency-injection | `jest.mock(`, `vi.fn()`, `unittest.mock.patch`, `@MockBean` |
+| integration-tests-real-deps | test-pyramid | `testcontainers`, `PostgreSqlContainer`, `docker-compose.test.yml`, `services: postgres` |
+| flaky-tests | test-pyramid | `jest.useFakeTimers`, `freezegun`, `setTimeout(`, `Date.now()` |
+| code-coverage | test-pyramid | `--coverage`, `coverageThreshold`, `pytest-cov`, `go test -cover` |
+
+## realtime.md: Real-time
+
+| id | requires | signals |
+| --- | --- | --- |
+| polling-long-polling | http-messages | `setInterval(`, `refetchInterval`, `?since=`, `WaitTimeSeconds` |
+| server-sent-events | polling-long-polling | `text/event-stream`, `EventSource`, `Last-Event-ID`, `StreamingResponse` |
+| websockets | polling-long-polling | `new WebSocket(`, `Upgrade: websocket`, `socket.io`, `ws.on('message'` |
+| pub-sub-fanout | websockets, stateless-services | `redis.publish(`, `@socket.io/redis-adapter`, `CHANNEL_LAYERS`, `pg_notify(` |
+
+## reliability.md: Errors and reliability
+
+| id | requires | signals |
+| --- | --- | --- |
+| error-handling-global | middleware-pipeline | `app.use((err, req, res, next)`, `setErrorHandler`, `@ControllerAdvice`, `@app.exception_handler` |
+| timeouts-external-calls | - | `AbortSignal.timeout(`, `requests.get(url, timeout=`, `context.WithTimeout`, `http.Client{Timeout:` |
+| retries-backoff-jitter | timeouts-external-calls, idempotency-keys | `Retry-After`, `p-retry`, `tenacity`, `@Retryable` |
+| graceful-shutdown | - | `SIGTERM`, `server.close(`, `srv.Shutdown(ctx)`, `terminationGracePeriodSeconds` |
+
+## scaling.md: Scaling and concurrency
+
+| id | requires | signals |
+| --- | --- | --- |
+| stateless-services | - | `MemoryStore`, `connect-redis`, `SESSION_ENGINE`, `sticky sessions` |
+| load-balancing | stateless-services | `upstream backend {`, `proxy_pass`, `least_conn`, `X-Forwarded-For` |
+| io-vs-cpu-bound | - | `worker_threads`, `ProcessPoolExecutor`, `asyncio.to_thread(`, `bcrypt.hashSync` |
+| event-loop-async | io-vs-cpu-bound | `async def`, `Promise.all(`, `asyncio.gather(`, `setImmediate` |
+| race-conditions | - | `SELECT ... FOR UPDATE`, `pg_advisory_xact_lock`, `sync.Mutex`, `SET stock = stock - 1` |
+
+## security.md: Security
+
+| id | requires | signals |
+| --- | --- | --- |
+| sql-injection | - | `WHERE id = $1`, `cursor.execute(sql, params)`, `PreparedStatement`, `$queryRawUnsafe` |
+| object-level-authorization | rbac-authorization | `req.params.id`, `findById(id)`, `WHERE id = $1 AND owner_id = $2`, `get_object_or_404(` |
+| rate-limiting | http-status-codes | `429 Too Many Requests`, `Retry-After`, `express-rate-limit`, `golang.org/x/time/rate` |
+| xss | - | `innerHTML`, `dangerouslySetInnerHTML`, `v-html`, `mark_safe(` |
+| csrf | cookie-security | `SameSite=Lax`, `X-CSRF-Token`, `@csrf_exempt`, `csrf().disable()` |
+| ssrf | - | `fetch(req.body.url)`, `requests.get(url)`, `http.Get(userURL)`, `169.254.169.254` |
+
+## storage.md: Files and object storage
+
+| id | requires | signals |
+| --- | --- | --- |
+| object-storage | stateless-services | `PutObjectCommand`, `boto3.client("s3")`, `@google-cloud/storage`, `S3_BUCKET` |
+| presigned-urls | object-storage | `getSignedUrl`, `generate_presigned_url`, `PresignPutObject`, `X-Amz-Signature` |
+| streaming-uploads | - | `stream.pipeline`, `req.pipe(`, `busboy`, `multer.memoryStorage` |
+| multipart-upload | object-storage | `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortIncompleteMultipartUpload` |
+| range-requests | http-messages | `Range: bytes=`, `Accept-Ranges: bytes`, `206 Partial Content`, `Content-Range` |

package/plugins/codecall/skills/codecall/references/backend-map/observability.md

@@ -0,0 +1,65 @@
+# Observability
+
+## structured-logging
+
+- **Name:** Structured logging and log levels
+- **Requires:** none
+- **Signals:** `pino`, `structlog`, `log/slog`, `logger.info({`, `LOG_LEVEL`, `logstash-logback-encoder`
+- **Idea:** Logs emitted as key-value JSON with a level, timestamp and request id can be filtered and queried in production, unlike free-text lines that someone must grep and guess at.
+- **Misconceptions:**
+  - More logging is always safer; logging every request body at info level costs money, buries the signal and often leaks passwords, tokens or personal data.
+  - Interpolating values into the message string is structured logging; put variables in separate fields so queries can filter on `user_id` or `order_id`.
+- **Checks:**
+  - If this request fails in production, which fields in your log lines would let you find every line from that one request?
+  - Which values logged by your code could contain secrets or personal data, and where are they redacted?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #18 · 18:12](https://www.youtube.com/watch?v=5PEuwgLOQQM&t=1092s)
+  - [OpenTelemetry: Logs](https://opentelemetry.io/docs/concepts/signals/logs/)
+
+## metrics-monitoring
+
+- **Name:** Metrics and monitoring
+- **Requires:** none
+- **Signals:** `prom-client`, `prometheus_client`, `/metrics`, `http_requests_total`, `Micrometer`, `histogram_quantile(`
+- **Idea:** Metrics are cheap numeric time series such as request rate, error rate, latency and saturation that you aggregate, graph and alert on, so you learn a service is unhealthy before users report it.
+- **Misconceptions:**
+  - Adding user id or full URL as a metric label is harmless; each unique value creates a new series, and high cardinality can overwhelm the metrics backend.
+  - Alerting on CPU and memory covers you; alert on symptoms users feel, such as error rate and latency, and use resource metrics for diagnosis.
+- **Checks:**
+  - Which metric would move first if the code you just changed started failing, and is there an alert on it?
+  - What labels does your code attach to this metric, and how many distinct values could each one take?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #18 · 3:57](https://www.youtube.com/watch?v=5PEuwgLOQQM&t=237s)
+  - [Google SRE book: Monitoring distributed systems](https://sre.google/sre-book/monitoring-distributed-systems/)
+
+## distributed-tracing
+
+- **Name:** Distributed tracing
+- **Requires:** `request-context`
+- **Signals:** `traceparent`, `@opentelemetry/api`, `tracer.start_as_current_span`, `otelhttp.NewHandler`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `span.setAttribute(`
+- **Idea:** Tracing gives each request a trace id that travels across services and queues, recording timed spans for every hop so you can see where a slow or failing request spent its time.
+- **Misconceptions:**
+  - Installing the tracing SDK traces everything; context is lost across queues, hand-rolled HTTP clients and thread pools unless `traceparent` is propagated explicitly.
+  - Tracing every request in production is free; most systems sample, so a missing trace for one request does not mean the request never happened.
+- **Checks:**
+  - When your code enqueues a job or calls another service here, how does the current trace context get passed along?
+  - If this endpoint becomes slow, which spans in your code would show whether the time goes to the database, an external API or your own logic?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #18 · 28:10](https://www.youtube.com/watch?v=5PEuwgLOQQM&t=1690s)
+  - [OpenTelemetry: Traces](https://opentelemetry.io/docs/concepts/signals/traces/)
+
+## latency-percentiles
+
+- **Name:** Latency percentiles
+- **Requires:** `metrics-monitoring`
+- **Signals:** `histogram_quantile(0.99`, `http_request_duration_seconds`, `_bucket{le=`, `p99`, `buckets:`
+- **Idea:** Percentiles like p50, p95 and p99 show how slow requests are for typical users and for the unlucky tail, which averages hide even though busy users hit that tail constantly.
+- **Misconceptions:**
+  - Average latency is a fine health signal; a few very slow requests barely move the mean while a real slice of users waits seconds.
+  - You can average p99 values across instances; percentiles do not combine that way, so compute them from merged histogram buckets instead.
+- **Checks:**
+  - When your code fans out to several services per request, how does the slowest call's tail latency shape the latency of the whole request?
+  - Do the histogram buckets in your code have enough resolution around your latency target to tell 300 ms from 900 ms?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.1 · 8:00](https://www.youtube.com/watch?v=z7kt_p44rjs&t=480s)
+  - [Prometheus: Histograms and summaries](https://prometheus.io/docs/practices/histograms/)