codecall 1.3.0 → 1.4.0

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/)

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

@@ -0,0 +1,129 @@
+# Configuration and delivery
+
+## config-management
+
+- **Name:** Configuration from the environment
+- **Requires:** none
+- **Signals:** `process.env`, `os.environ`, `os.Getenv(`, `BaseSettings`, `dotenv`, `@ConfigurationProperties`
+- **Idea:** Values that differ between deploys, like database URLs, ports and feature flags, are read from the environment at startup, so one build runs unchanged in dev, staging and production.
+- **Misconceptions:**
+  - Reading `process.env.X` wherever it is needed is fine; parse and validate once at startup so a missing value fails the boot, not a request later.
+  - Config and code constants are the same; values that never change between deploys belong in code, not an ever-growing list of variables.
+- **Checks:**
+  - If a required variable is missing in production, does your code fail at startup or on the first request that needs it?
+  - Which value hardcoded in your code would have to change between staging and production, and how would you move it to config?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #17 · 26:41](https://www.youtube.com/watch?v=GR9NtirPXyc&t=1601s)
+  - [The Twelve-Factor App: Config](https://12factor.net/config)
+
+## secrets-management
+
+- **Name:** Secrets management
+- **Requires:** `config-management`
+- **Signals:** `.env.example`, `aws secretsmanager`, `vault kv get`, `secretKeyRef`, `${{ secrets.`, `SecretStr`
+- **Idea:** Credentials are kept out of code and images, injected at runtime from a secret store with access control, auditing and rotation, so a leaked repo or log does not leak them.
+- **Misconceptions:**
+  - Deleting a committed secret in a later commit fixes the leak; it stays in history and forks, so it must be rotated.
+  - Environment variables are secure storage; they leak through crash dumps, debug endpoints, child processes and logs that print the config.
+- **Checks:**
+  - If the API key in your code leaked today, how would you rotate it, and would your service need a redeploy to pick it up?
+  - Where could your code accidentally print a secret, such as an error message, request log or config dump, and how would you redact it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #17 · 31:03](https://www.youtube.com/watch?v=GR9NtirPXyc&t=1863s)
+  - [OWASP Cheat Sheet: Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
+
+## disposable-processes
+
+- **Name:** Disposable, stateless processes (12-factor)
+- **Requires:** `stateless-services`, `graceful-shutdown`
+- **Signals:** `SIGTERM`, `terminationGracePeriodSeconds`, `process.on("SIGTERM"`, `signal.NotifyContext`, `replicas:`, `readinessProbe`
+- **Idea:** Each process starts fast, keeps no state it cannot lose and shuts down cleanly on a signal, so the platform can kill, restart or scale it at any moment safely.
+- **Misconceptions:**
+  - A process only stops on deploys; autoscalers, node drains and crashes kill it anytime, so in-memory sessions and queues get lost.
+  - Shutting down means exiting immediately; in-flight requests and jobs should finish or be handed back before the process exits.
+- **Checks:**
+  - If the platform sends your process SIGTERM mid-request, what happens to that request and to any job your code is running?
+  - What state does your code keep in memory or on local disk that would vanish if this instance were replaced right now?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #27 · 50:16](https://www.youtube.com/watch?v=2_fcv3-XfN4&t=3016s)
+  - [The Twelve-Factor App: Disposability](https://12factor.net/disposability)
+
+## ci-pipeline
+
+- **Name:** Continuous integration pipelines
+- **Requires:** none
+- **Signals:** `.github/workflows/`, `.gitlab-ci.yml`, `on: pull_request`, `actions/cache`, `Jenkinsfile`, `npm ci`
+- **Idea:** Every push is built and tested automatically in a clean environment, so integration problems surface within minutes on the change that caused them instead of at release time.
+- **Misconceptions:**
+  - Passing locally means CI will pass; CI starts clean, so missing lockfile entries, env vars and machine-specific state show up there.
+  - A red build can wait; once main stays broken, every later failure hides behind it and people stop trusting the pipeline.
+- **Checks:**
+  - Which checks run on your change before merge, and which bug class in your code would still reach main untested?
+  - If your pipeline takes 25 minutes, which steps would you cache, parallelize or move later, and what feedback would that delay?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #30 · 15:50](https://www.youtube.com/watch?v=_E8X5RIJfQ4&t=950s)
+  - [martinfowler.com: Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html)
+
+## container-images
+
+- **Name:** Containers and image layers
+- **Requires:** none
+- **Signals:** `Dockerfile`, `FROM node:22-alpine AS build`, `COPY package*.json ./`, `.dockerignore`, `USER node`, `docker build`
+- **Idea:** An image is a stack of cached, read-only layers built from Dockerfile steps, so ordering steps from least to most often changed keeps rebuilds fast and images small.
+- **Misconceptions:**
+  - Deleting a file in a later layer removes it from the image; it still ships in the earlier layer, including any secret copied in.
+  - Copying the whole project before installing dependencies is harmless; any source change invalidates the cache and reinstalls everything.
+- **Checks:**
+  - In your Dockerfile, which line invalidates the cache on every code change, and how would reordering steps speed up rebuilds?
+  - What ends up in your final image that production does not need, such as compilers, tests or `.git`, and how would a multi-stage build drop it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #30 · 38:18](https://www.youtube.com/watch?v=_E8X5RIJfQ4&t=2298s)
+  - [Docker docs: Understanding the image layers](https://docs.docker.com/get-started/docker-concepts/building-images/understanding-image-layers/)
+
+## deployment-strategies
+
+- **Name:** Rolling, blue-green and canary deploys
+- **Requires:** `load-balancing`
+- **Signals:** `strategy: RollingUpdate`, `maxUnavailable`, `maxSurge`, `canary`, `blue-green`, `trafficRouting`
+- **Idea:** Rolling, blue-green and canary deploys shift traffic to a new version gradually or switchably, so a bad release reaches few users and can be rolled back without downtime.
+- **Misconceptions:**
+  - Blue-green makes rollback free; if the new version already migrated the schema or wrote new data, switching back can break the old version.
+  - During a rolling deploy only one version runs; old and new serve traffic together, so APIs and schema must work with both.
+- **Checks:**
+  - While your deploy is half rolled out, which requests could hit the old version after the new one wrote data, and would that break?
+  - What metric would tell you a canary of your change is bad, and how quickly could your setup roll it back?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #30 · 1:16:26](https://www.youtube.com/watch?v=_E8X5RIJfQ4&t=4586s)
+  - [Google SRE Workbook: Canarying Releases](https://sre.google/workbook/canarying-releases/)
+
+## infrastructure-as-code
+
+- **Name:** Infrastructure as code
+- **Requires:** none
+- **Signals:** `resource "aws_`, `terraform plan`, `.tfstate`, `pulumi up`, `AWSTemplateFormatVersion`, `cdk deploy`
+- **Idea:** Servers, networks, databases and permissions are declared in versioned files that a tool applies, so environments are reproducible, reviewed like code and not hand-configured in a console.
+- **Misconceptions:**
+  - Once infrastructure is in code, console tweaks are harmless; manual changes create drift that the next apply silently reverts or fights.
+  - The state file is a disposable artifact; losing or corrupting it makes the tool forget what it owns, and it often holds secrets.
+- **Checks:**
+  - Before your change applies, what in the plan output would warn you that a resource will be destroyed and recreated instead of updated?
+  - Where does your project keep its state file, who can read it, and what stops two people applying at once?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #30 · 1:25:18](https://www.youtube.com/watch?v=_E8X5RIJfQ4&t=5118s)
+  - [martinfowler.com: Infrastructure As Code](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+
+## slos-incidents
+
+- **Name:** SLOs, error budgets and incidents
+- **Requires:** `metrics-monitoring`
+- **Signals:** `slo:`, `error_budget`, `histogram_quantile(`, `burn rate`, `availability: 99.9`, `postmortem`
+- **Idea:** An SLO sets a target for a user-visible indicator like success rate or latency, and the error budget left over decides when to ship faster or stop and fix reliability.
+- **Misconceptions:**
+  - The goal is 100% reliability; it is unattainable and costly, and users cannot tell 99.99% from 100% behind their own networks.
+  - Alert on every CPU spike or error; page on symptoms that burn the error budget, not causes users never notice.
+- **Checks:**
+  - Which user-facing indicator would you measure for the endpoint in your code, and what latency or success threshold would count as good?
+  - If your change caused errors for 5% of requests for ten minutes, how much of a 99.9% monthly budget would that burn?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #30 · 1:33:01](https://www.youtube.com/watch?v=_E8X5RIJfQ4&t=5581s)
+  - [Google SRE Book: Service Level Objectives](https://sre.google/sre-book/service-level-objectives/)