codecall 1.2.3 → 1.4.0

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

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

@@ -0,0 +1,81 @@
+# Testing
+
+## test-pyramid
+
+- **Name:** Unit, integration and end-to-end tests
+- **Requires:** none
+- **Signals:** `describe(`, `pytest`, `func TestX(t *testing.T)`, `@SpringBootTest`, `playwright.config`, `supertest`
+- **Idea:** Tests at different scopes trade speed for realism, so most checks live in fast unit tests, fewer in integration tests and a handful in slow end-to-end tests.
+- **Misconceptions:**
+  - More end-to-end tests always mean more confidence; they are slow, flaky and point vaguely at failures, so suites built mostly from them get ignored.
+  - Unit tests alone prove the system works; they miss bugs in SQL, serialization, config and the wiring between components.
+- **Checks:**
+  - For the change in your code, which bug would a unit test catch that an end-to-end test would not pinpoint, and vice versa?
+  - If your test suite took twenty minutes, which tests would you move down a level, and what realism would you give up?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 14:46](https://www.youtube.com/watch?v=HgVrfHX92y4&t=886s)
+  - [martinfowler.com: The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)
+
+## test-doubles
+
+- **Name:** Test doubles: stubs, mocks and fakes
+- **Requires:** `dependency-injection`
+- **Signals:** `jest.mock(`, `vi.fn()`, `unittest.mock.patch`, `@MockBean`, `gomock`, `sinon.stub`
+- **Idea:** A test double stands in for a real dependency, with stubs returning canned answers, mocks verifying calls and fakes giving a working lightweight version, so tests stay fast and deterministic.
+- **Misconceptions:**
+  - Mocking everything makes tests thorough; tests that assert exact internal calls break on every refactor while still passing when the real dependency behaves differently.
+  - A mock that returns success proves the integration works; it only proves your code handles the answer you invented.
+- **Checks:**
+  - In your test, does the double check the outcome your code produces, or just that a specific method was called, and which survives a refactor?
+  - What real behaviour of the dependency your code calls, such as timeouts or constraint errors, does your double never simulate?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 27:27](https://www.youtube.com/watch?v=HgVrfHX92y4&t=1647s)
+  - [martinfowler.com: Test Double](https://martinfowler.com/bliki/TestDouble.html)
+
+## integration-tests-real-deps
+
+- **Name:** Integration tests against real dependencies
+- **Requires:** `test-pyramid`
+- **Signals:** `testcontainers`, `PostgreSqlContainer`, `docker-compose.test.yml`, `services: postgres`, `@DataJpaTest`, `pytest-postgresql`
+- **Idea:** Integration tests run your code against real instances of the database, cache or broker, usually in throwaway containers, to catch bugs that only appear with the actual engine.
+- **Misconceptions:**
+  - SQLite or an in-memory fake is close enough to Postgres; types, locking, constraints and SQL dialect differ, so bugs slip through.
+  - Integration tests can share one database freely; leftover rows from one test change another's result unless each test isolates or resets data.
+- **Checks:**
+  - Which behaviour in your code, such as a unique constraint, transaction or JSON column, would pass against a fake but fail against the real database?
+  - How does your test suite reset data between tests, and what happens if two tests run in parallel against the same schema?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 41:04](https://www.youtube.com/watch?v=HgVrfHX92y4&t=2464s)
+  - [martinfowler.com: Integration Test](https://martinfowler.com/bliki/IntegrationTest.html)
+
+## flaky-tests
+
+- **Name:** Flaky tests: time, network and order
+- **Requires:** `test-pyramid`
+- **Signals:** `jest.useFakeTimers`, `freezegun`, `setTimeout(` in a test, `Date.now()`, `--randomize`, `retry: 3`
+- **Idea:** A flaky test passes or fails without code changes because it depends on wall-clock time, real network, shared state or run order, so its failures stop meaning anything.
+- **Misconceptions:**
+  - Adding retries or a longer sleep fixes flakiness; it hides a race or hidden dependency and makes the suite slower.
+  - A test that passes alone is correct; it may rely on state left by an earlier test and fail when order changes.
+- **Checks:**
+  - What in your test depends on the current time, a real network call or a fixed sleep, and how would you make it deterministic?
+  - If your test fails only in CI under parallel runs, which shared resource in your code would you suspect first?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 1:02:36](https://www.youtube.com/watch?v=HgVrfHX92y4&t=3756s)
+  - [martinfowler.com: Eradicating Non-Determinism in Tests](https://martinfowler.com/articles/nonDeterminism.html)
+
+## code-coverage
+
+- **Name:** What code coverage can and cannot tell you
+- **Requires:** `test-pyramid`
+- **Signals:** `--coverage`, `coverageThreshold`, `pytest-cov`, `go test -cover`, `jacoco`, `istanbul ignore`
+- **Idea:** Coverage reports which lines or branches ran during tests, which reveals untested code but says nothing about whether the assertions would catch a wrong result.
+- **Misconceptions:**
+  - 100% coverage means the code is correct; a test with no meaningful assertions can execute every line.
+  - Raising the coverage threshold improves quality; teams then write tests that touch code without checking behaviour, just to hit the number.
+- **Checks:**
+  - Which branch in your change, such as an error path, is uncovered, and what real failure would it hide?
+  - If you broke the main calculation in your code, would any covered test fail, or do the tests only execute it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 1:07:39](https://www.youtube.com/watch?v=HgVrfHX92y4&t=4059s)
+  - [martinfowler.com: Test Coverage](https://martinfowler.com/bliki/TestCoverage.html)

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

@@ -0,0 +1,65 @@
+# Real-time
+
+## polling-long-polling
+
+- **Name:** Polling and long polling
+- **Requires:** `http-messages`
+- **Signals:** `setInterval(`, `refetchInterval`, `?since=`, `WaitTimeSeconds`, `204 No Content`
+- **Idea:** Polling asks the server for updates on a timer, while long polling holds each request open until data arrives or a timeout passes, giving near-real-time updates over plain HTTP.
+- **Misconceptions:**
+  - Short polling every second is harmless; with many clients most requests return nothing yet still cost auth checks, database queries and connections.
+  - A long-poll request can stay open indefinitely; proxies and load balancers cut idle connections, so respond within their timeout and let the client reconnect.
+- **Checks:**
+  - If the client misses a response from your polling endpoint, how does your code let it resume without losing or duplicating updates?
+  - How many requests per minute will your polling interval produce at your expected number of open clients, and what does each one cost?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #25 · 2:26](https://www.youtube.com/watch?v=wUQryt697cs&t=146s)
+  - [IETF: RFC 6202, Long polling and streaming in bidirectional HTTP](https://datatracker.ietf.org/doc/html/rfc6202)
+
+## server-sent-events
+
+- **Name:** Server-sent events
+- **Requires:** `polling-long-polling`
+- **Signals:** `text/event-stream`, `EventSource`, `Last-Event-ID`, `StreamingResponse`, `SseEmitter`, `retry:`
+- **Idea:** Server-sent events stream one-way updates from server to browser over a long-lived HTTP response, with built-in reconnection and resume via event ids, which suits feeds, notifications and LLM token streaming.
+- **Misconceptions:**
+  - SSE needs WebSockets underneath; it is a plain HTTP response with `text/event-stream`, so it works through most proxies and over HTTP/2 without a protocol upgrade.
+  - Events reach the client as soon as you write them; compression or proxy buffering can hold them back unless you flush and disable buffering, for example `X-Accel-Buffering: no`.
+- **Checks:**
+  - When a client reconnects with `Last-Event-ID`, how does your code replay the events it missed?
+  - How does your code notice that a client disconnected and stop the work and timers feeding that stream?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #25 · 11:57](https://www.youtube.com/watch?v=wUQryt697cs&t=717s)
+  - [MDN: Using server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
+
+## websockets
+
+- **Name:** WebSockets
+- **Requires:** `polling-long-polling`
+- **Signals:** `new WebSocket(`, `Upgrade: websocket`, `socket.io`, `ws.on('message'`, `websocket.accept()`, `gorilla/websocket`
+- **Idea:** A WebSocket upgrades one HTTP request into a persistent, full-duplex connection where client and server send messages anytime, suiting chat, collaboration and games but requiring you to manage connection state.
+- **Misconceptions:**
+  - CORS protects WebSocket endpoints like it protects fetch; browsers do not apply it to the handshake, so your server must check `Origin` and authenticate the connection itself.
+  - A connection stays open until someone closes it; NATs and proxies silently drop idle sockets, so use ping/pong heartbeats and client reconnection with backoff.
+- **Checks:**
+  - When a client reconnects after a network drop, how does your code recover the messages sent while it was offline?
+  - What does your code do when a client stops reading and outgoing messages pile up in that socket's buffer?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #25 · 19:21](https://www.youtube.com/watch?v=wUQryt697cs&t=1161s)
+  - [MDN: The WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
+
+## pub-sub-fanout
+
+- **Name:** Pub/sub fan-out across instances
+- **Requires:** `websockets`, `stateless-services`
+- **Signals:** `redis.publish(`, `@socket.io/redis-adapter`, `CHANNEL_LAYERS`, `pg_notify(`, `XADD`
+- **Idea:** When clients are spread across many server instances, each instance subscribes to a shared broker channel so an event published once reaches every instance and its locally connected sockets.
+- **Misconceptions:**
+  - Broadcasting to your in-memory connection list reaches all users; once you run more than one replica, it only reaches sockets on that instance.
+  - Redis Pub/Sub keeps messages for subscribers that are briefly offline; it is at-most-once, so use Streams or a durable log when missed messages matter.
+- **Checks:**
+  - If the instance holding a user's socket restarts while an event is published, how does your code make sure that user still sees it?
+  - How does your code avoid sending every event to every instance when only a few hold interested subscribers?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #25 · 40:51](https://www.youtube.com/watch?v=wUQryt697cs&t=2451s)
+  - [Redis: Redis Pub/sub](https://redis.io/docs/latest/develop/pubsub/)

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

@@ -0,0 +1,65 @@
+# Errors and reliability
+
+## error-handling-global
+
+- **Name:** Centralized error handling
+- **Requires:** `middleware-pipeline`
+- **Signals:** `app.use((err, req, res, next)`, `setErrorHandler`, `@ControllerAdvice`, `@app.exception_handler`, `rescue_from`, `application/problem+json`
+- **Idea:** One error-handling layer at the edge of the app turns any thrown error into a consistent, safe HTTP response and a log entry, so handlers do not each reinvent status codes and leak internals.
+- **Misconceptions:**
+  - Sending `err.message` or the stack trace to the client helps debugging; it leaks internals, so return a generic message with a request id and log details server-side.
+  - Every error should become a 500; validation, not-found and conflict errors are expected outcomes and deserve their own 4xx codes.
+- **Checks:**
+  - If an async function in your handler rejects without a try/catch, does the error reach your central handler, or does the request hang or the process crash?
+  - How does your error handler decide between a 4xx and a 500, and what does it log for each?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #16 · 41:48](https://www.youtube.com/watch?v=8NaM_9aKS24&t=2508s)
+  - [OWASP Cheat Sheet Series: Error handling](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html)
+
+## timeouts-external-calls
+
+- **Name:** Timeouts on external calls
+- **Requires:** none
+- **Signals:** `AbortSignal.timeout(`, `requests.get(url, timeout=`, `context.WithTimeout`, `http.Client{Timeout:`, `statement_timeout`, `connectTimeout`
+- **Idea:** Every network call to a database, API or cache needs an explicit time limit, because without one a slow dependency holds threads, connections and memory until your own service stops responding.
+- **Misconceptions:**
+  - HTTP clients ship with sensible timeouts; Python `requests` and Go's default `http.Client` wait forever, and Node `fetch` waits minutes before giving up.
+  - A timeout means the remote operation failed; it may have succeeded after you gave up, so blindly retrying a non-idempotent call can apply it twice.
+- **Checks:**
+  - What is the total time budget for this request in your code, and do the timeouts on each downstream call fit inside it?
+  - When this external call times out in your code, what does the user see, and is it safe to retry?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #16 · 10:40](https://www.youtube.com/watch?v=8NaM_9aKS24&t=640s)
+  - [Google SRE book: Addressing cascading failures](https://sre.google/sre-book/addressing-cascading-failures/)
+
+## retries-backoff-jitter
+
+- **Name:** Retries with backoff and jitter
+- **Requires:** `timeouts-external-calls`, `idempotency-keys`
+- **Signals:** `Retry-After`, `p-retry`, `tenacity`, `@Retryable`, `maxAttempts`, `2 ** attempt`
+- **Idea:** Retrying transient failures after exponentially growing, randomized delays lets a call recover from blips without a synchronized storm of retries overwhelming a dependency that is already struggling.
+- **Misconceptions:**
+  - Any error is worth retrying; 400s, auth failures and validation errors fail identically every time, so retry only timeouts, connection errors, 429 and selected 5xx.
+  - Retrying at every layer adds safety; three layers with three attempts each multiply into 27 calls against a dependency that is already failing.
+- **Checks:**
+  - Is the operation your code retries idempotent, and if not, what stops a retry after a timeout from doing it twice?
+  - What is the worst-case total time your retry loop can spend, including backoff, and does it fit inside the caller's timeout?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 34:31](https://www.youtube.com/watch?v=eWM0CVReP04&t=2071s)
+  - [AWS SDKs and Tools: Retry behavior](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)
+
+## graceful-shutdown
+
+- **Name:** Graceful shutdown and connection draining
+- **Requires:** none
+- **Signals:** `SIGTERM`, `server.close(`, `srv.Shutdown(ctx)`, `terminationGracePeriodSeconds`, `preStop`, `server.shutdown=graceful`
+- **Idea:** On SIGTERM a service should stop accepting new work, let in-flight requests and jobs finish, close pools cleanly, then exit, so deploys and scale-downs do not drop requests or corrupt half-done work.
+- **Misconceptions:**
+  - Shutdown needs no code; without a SIGTERM handler most runtimes exit instantly, and a process running as container PID 1 may ignore the signal until SIGKILL.
+  - Closing the server is enough; the load balancer may keep routing new requests for a few seconds, so fail readiness first and keep serving briefly.
+- **Checks:**
+  - What happens to a request your code is halfway through when the container receives SIGTERM during a deploy?
+  - Does your shutdown path finish within the platform's grace period, and what is left undone if it gets killed early?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #19 · 8:49](https://www.youtube.com/watch?v=6rfBgphiCWM&t=529s)
+  - [Kubernetes: Pod lifecycle, termination of Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination)

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

@@ -0,0 +1,81 @@
+# Scaling and concurrency
+
+## stateless-services
+
+- **Name:** Stateless services and horizontal scaling
+- **Requires:** none
+- **Signals:** `MemoryStore`, `connect-redis`, `SESSION_ENGINE`, `sticky sessions`, `replicas:`, `HorizontalPodAutoscaler`
+- **Idea:** A stateless instance keeps nothing between requests in local memory or disk, putting sessions, uploads and caches in shared stores, so any instance can serve any request and you scale by adding copies.
+- **Misconceptions:**
+  - Stateless means no state anywhere; the state still exists, it just moves to a database, cache or object store that all instances share.
+  - An in-process cache or rate-limit counter behaves the same with more replicas; each instance keeps its own copy, so limits multiply and caches disagree.
+- **Checks:**
+  - If a second instance of your service starts behind the load balancer, which variables or files in your code would give users different answers?
+  - Where does your code keep sessions, uploaded files and in-memory counters, and what happens to them when an instance restarts?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.2 · 0:43](https://www.youtube.com/watch?v=sOhAopEwjH4&t=43s)
+  - [The Twelve-Factor App: Processes](https://12factor.net/processes)
+
+## load-balancing
+
+- **Name:** Load balancing
+- **Requires:** `stateless-services`
+- **Signals:** `upstream backend {`, `proxy_pass`, `least_conn`, `X-Forwarded-For`, `readinessProbe`, `trust proxy`
+- **Idea:** A load balancer spreads requests across healthy instances, by round robin or least connections, skipping ones that fail health checks so no single machine is overloaded or a single point of failure.
+- **Misconceptions:**
+  - Behind a load balancer, `req.ip` is the client's address; it is the proxy's unless you parse `X-Forwarded-For` and trust only your own proxies.
+  - An endpoint that always returns 200 is a good health check; readiness should fail whenever the instance cannot serve, such as during startup or shutdown.
+- **Checks:**
+  - If one instance behind your load balancer becomes slow but not dead, how would your current health check and balancing policy react?
+  - Does your code rely on the same client reaching the same instance twice, such as for socket state or uploads, and what breaks if it does not?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #21.2 · 9:11](https://www.youtube.com/watch?v=sOhAopEwjH4&t=551s)
+  - [Google SRE book: Load balancing in the datacenter](https://sre.google/sre-book/load-balancing-datacenter/)
+
+## io-vs-cpu-bound
+
+- **Name:** IO-bound vs CPU-bound work
+- **Requires:** none
+- **Signals:** `worker_threads`, `ProcessPoolExecutor`, `asyncio.to_thread(`, `bcrypt.hashSync`, `GOMAXPROCS`
+- **Idea:** IO-bound work spends its time waiting on networks and disks and scales with concurrency, while CPU-bound work like hashing, image resizing or parsing huge JSON needs real cores, so they need different tools.
+- **Misconceptions:**
+  - Marking a function `async` makes CPU-heavy work non-blocking; async only helps while waiting, and a tight loop still freezes the event loop.
+  - Python threads speed up CPU-bound code; in standard CPython builds the GIL runs one thread's bytecode at a time, so use processes or native code.
+- **Checks:**
+  - Which step in your handler is CPU-heavy, and what happens to other users' requests on the same instance while it runs?
+  - Would more concurrency or more cores make this part of your code faster, and how could you measure which one it needs?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #22 · 5:55](https://www.youtube.com/watch?v=bs9MEYRTA30&t=355s)
+  - [Node.js: Don't block the event loop (or the worker pool)](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop)
+
+## event-loop-async
+
+- **Name:** Event loop and async/await
+- **Requires:** `io-vs-cpu-bound`
+- **Signals:** `async def`, `Promise.all(`, `asyncio.gather(`, `setImmediate`, `readFileSync`, `CompletableFuture`
+- **Idea:** An event loop runs many tasks on one thread by switching whenever a task awaits IO, so it handles thousands of connections cheaply as long as no task blocks the thread.
+- **Misconceptions:**
+  - Awaiting calls one by one in a loop runs them in parallel; each `await` waits for the previous one, so use `Promise.all` or `gather` for independent calls.
+  - Calling a blocking library inside an async function is fine; synchronous drivers, `time.sleep` or `fs.readFileSync` stall every request on that loop.
+- **Checks:**
+  - Which awaited calls in your handler are independent of each other, and how much latency would running them concurrently save?
+  - Does any library your async code calls perform blocking IO under the hood, and how would you notice it in production?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #22 · 37:15](https://www.youtube.com/watch?v=bs9MEYRTA30&t=2235s)
+  - [Node.js: The Node.js event loop](https://nodejs.org/en/learn/asynchronous-work/event-loop-timers-and-nexttick)
+
+## race-conditions
+
+- **Name:** Race conditions and locks
+- **Requires:** none
+- **Signals:** `SELECT ... FOR UPDATE`, `pg_advisory_xact_lock`, `sync.Mutex`, `SET stock = stock - 1`, `WHERE version = $1`, `SET key val NX PX`
+- **Idea:** A race condition happens when concurrent requests read and write the same data and the result depends on timing, so code needs atomic updates, constraints or locks to keep its invariants.
+- **Misconceptions:**
+  - A single-threaded runtime like Node cannot have races; any `await` between reading and writing lets another request interleave, and multiple instances race anyway.
+  - An in-memory mutex protects shared data; it only covers one process, so across replicas use row locks, conditional updates or a distributed lock.
+- **Checks:**
+  - If two requests run the read-then-write sequence in your code at the same moment, what final value ends up in the database?
+  - Could a single conditional `UPDATE ... WHERE` replace the lock in your code, and what would you gain or lose?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #22 · 1:15:32](https://www.youtube.com/watch?v=bs9MEYRTA30&t=4532s)
+  - [PostgreSQL: Explicit locking](https://www.postgresql.org/docs/current/explicit-locking.html)

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

@@ -0,0 +1,97 @@
+# Security
+
+## sql-injection
+
+- **Name:** SQL injection and parameterized queries
+- **Requires:** none
+- **Signals:** `WHERE id = $1`, `cursor.execute(sql, params)`, `PreparedStatement`, `$queryRawUnsafe`, `f"SELECT`, `ORDER BY ${`
+- **Idea:** When user input is concatenated into SQL text the database parses it as code, so values must travel separately as bound parameters that can never change the query's structure.
+- **Misconceptions:**
+  - Using an ORM makes you immune; raw-query escape hatches, string-built `where` clauses and dynamic sort columns still inject.
+  - Escaping quotes or validating input is enough; identifiers like column names cannot be bound, so they need an allowlist instead.
+- **Checks:**
+  - Which value in your query reaches the SQL string by concatenation or interpolation rather than as a bound parameter, and where does it come from?
+  - If your handler lets the client choose a sort column or filter field, how does your code stop that name from becoming arbitrary SQL?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 29:27](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=1767s)
+  - [OWASP Cheat Sheet: SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html)
+
+## object-level-authorization
+
+- **Name:** Object-level authorization (BOLA)
+- **Requires:** `rbac-authorization`
+- **Signals:** `req.params.id`, `findById(id)` without an owner filter, `WHERE id = $1 AND owner_id = $2`, `get_object_or_404(`, `@PreAuthorize`, `/users/:userId/`
+- **Idea:** Being logged in and holding the right role says nothing about this particular record, so every lookup by client-supplied id must also check that the caller may access that object.
+- **Misconceptions:**
+  - Unguessable UUIDs protect records; ids leak through URLs, logs and shared links, so obscurity is not an access check.
+  - A role check in middleware covers it; roles say what kind of action is allowed, not whose order or invoice it is.
+- **Checks:**
+  - If another logged-in user changes the id in this request to yours, which line in your handler returns 404 or 403 instead of your data?
+  - Does your code scope the database query itself to the caller's tenant or owner, or fetch first and compare afterwards, and which is easier to forget?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 1:37:31](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=5851s)
+  - [OWASP Cheat Sheet: Insecure Direct Object Reference Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html)
+
+## rate-limiting
+
+- **Name:** Rate limiting
+- **Requires:** `http-status-codes`
+- **Signals:** `429 Too Many Requests`, `Retry-After`, `express-rate-limit`, `golang.org/x/time/rate`, Redis `INCR` with `EXPIRE`
+- **Idea:** Capping how many requests a client, key or tenant may make per time window protects shared capacity and slows abuse such as credential stuffing, scraping and runaway retry loops.
+- **Misconceptions:**
+  - An in-memory counter works in production; with several replicas each instance counts separately, so the real limit becomes the limit times the instance count.
+  - Keying limits only by IP is fair; NAT and proxies share IPs, while attackers rotate them, so key by user, API key or account too.
+- **Checks:**
+  - Where does your limiter store its counters, and what limit does a client actually get when your service runs on three instances behind a load balancer?
+  - When your code rejects a request with 429, what does the client learn about when to retry, and how would a well-behaved SDK back off?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 1:32:41](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=5561s)
+  - [Microsoft Learn: Throttling pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/throttling)
+
+## xss
+
+- **Name:** Cross-site scripting (XSS)
+- **Requires:** none
+- **Signals:** `innerHTML`, `dangerouslySetInnerHTML`, `v-html`, `mark_safe(`, `Content-Security-Policy`, `DOMPurify.sanitize(`
+- **Idea:** When untrusted data is written into a page without encoding for its context, the browser runs it as script with the victim's session, so output must be escaped or sanitized where it lands.
+- **Misconceptions:**
+  - Sanitizing input once on the way in is enough; the safe encoding depends on output context, such as HTML body, attribute, URL or inline script.
+  - A JSON API cannot cause XSS; a wrong `Content-Type`, or a frontend inserting the response as HTML, turns stored data into script.
+- **Checks:**
+  - Which user-controlled field in your change ends up rendered as HTML, and what escapes or sanitizes it right before it reaches the page?
+  - If an attacker stored `<img src=x onerror=...>` in this field, where would your code render it, and would your CSP block it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 2:17:21](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=8241s)
+  - [OWASP Cheat Sheet: Cross Site Scripting Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
+
+## csrf
+
+- **Name:** Cross-site request forgery (CSRF)
+- **Requires:** `cookie-security`
+- **Signals:** `SameSite=Lax`, `X-CSRF-Token`, `@csrf_exempt`, `csrf().disable()`, `Sec-Fetch-Site`, `protect_from_forgery`
+- **Idea:** Browsers attach cookies to requests that other sites trigger, so a cookie-authenticated endpoint that changes state needs proof the request came from your own pages, not merely the user's browser.
+- **Misconceptions:**
+  - CORS stops CSRF; CORS only controls reading responses, while a simple cross-site form POST is still sent with cookies.
+  - `SameSite` cookies end the problem; `Lax` still permits top-level GET navigations, so state-changing GET routes stay exploitable.
+- **Checks:**
+  - Which state-changing routes in your code rely on a session cookie, and what token, header or origin check rejects the same request sent from another site?
+  - If your code disables CSRF protection for an API route, what guarantees callers authenticate with a header token rather than the browser's cookie?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 2:28:32](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=8912s)
+  - [OWASP Cheat Sheet: Cross-Site Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)
+
+## ssrf
+
+- **Name:** Server-side request forgery (SSRF)
+- **Requires:** none
+- **Signals:** `fetch(req.body.url)`, `requests.get(url)`, `http.Get(userURL)`, `169.254.169.254`, `redirect: "manual"`
+- **Idea:** When your server fetches a URL the user supplied, an attacker can aim it at internal services or cloud metadata your network trusts, so outbound targets must be restricted.
+- **Misconceptions:**
+  - Blocking `localhost` in the string is enough; decimal IPs, IPv6, DNS names resolving to private ranges and redirects all bypass string checks.
+  - Validating the hostname once is safe; DNS can resolve differently at fetch time, so check the resolved IP on every connection and redirect.
+- **Checks:**
+  - Which URL in your handler comes from the client, and what stops your code from fetching `http://169.254.169.254/` or a private 10.x address with it?
+  - Does your HTTP client follow redirects here, and does your code re-check the destination after each hop?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 25:16](https://www.youtube.com/watch?v=eWM0CVReP04&t=1516s)
+  - [OWASP Cheat Sheet: Server Side Request Forgery Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)

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

@@ -0,0 +1,81 @@
+# Files and object storage
+
+## object-storage
+
+- **Name:** Object storage instead of local disk
+- **Requires:** `stateless-services`
+- **Signals:** `PutObjectCommand`, `boto3.client("s3")`, `@google-cloud/storage`, `S3_BUCKET`, `ActiveStorage::Blob`, `multer.diskStorage`
+- **Idea:** Files go to a shared bucket addressed by key instead of the server's own disk, so any instance can read them and nothing is lost when a container is replaced.
+- **Misconceptions:**
+  - Writing uploads to `./uploads` is fine until you scale; it breaks the moment a second instance or a redeploy wipes the container filesystem.
+  - A bucket is a filesystem; keys only look like paths, renames are copies, and there is no atomic move or append.
+- **Checks:**
+  - If your service runs on three instances behind a load balancer, which instance can serve a file your handler just saved, and why?
+  - What does your code store in the database for each file, and what happens if the object upload succeeds but that row insert fails?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #23 · 9:54](https://www.youtube.com/watch?v=Ie0TjKI9cDI&t=594s)
+  - [AWS docs: What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html)
+
+## presigned-urls
+
+- **Name:** Pre-signed URLs
+- **Requires:** `object-storage`
+- **Signals:** `getSignedUrl`, `generate_presigned_url`, `PresignPutObject`, `X-Amz-Signature`, `createPresignedPost`
+- **Idea:** The server signs a short-lived URL for one object and one method, so clients upload or download directly from storage without file bytes passing through your API or holding bucket credentials.
+- **Misconceptions:**
+  - A pre-signed URL is private once issued; it is a bearer token, so anyone holding it can use it until it expires.
+  - Signing an upload URL means the upload is validated; size, content type and contents still need limits in the policy or a check afterwards.
+- **Checks:**
+  - How long do the URLs your code signs stay valid, and what could someone do with one copied from a log or browser history?
+  - After a client uploads through your pre-signed URL, how does your code learn the upload finished and verify it is the expected file?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #23 · 1:16:42](https://www.youtube.com/watch?v=Ie0TjKI9cDI&t=4602s)
+  - [AWS docs: Download and upload objects with presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html)
+
+## streaming-uploads
+
+- **Name:** Streaming instead of buffering uploads
+- **Requires:** none
+- **Signals:** `stream.pipeline`, `req.pipe(`, `busboy`, `multer.memoryStorage`, `io.Copy(`, `UploadFile.read()`
+- **Idea:** Streaming moves request bytes through the server in small chunks to their destination, so memory stays flat regardless of file size instead of holding the whole body in RAM.
+- **Misconceptions:**
+  - Memory storage is fine for uploads; a few concurrent large files load entirely into RAM and the process gets killed for running out of memory.
+  - Streaming means no limits are needed; you still cap total bytes, because an endless stream ties up a connection and fills the destination.
+- **Checks:**
+  - If ten users upload a 2 GB file to your handler at once, roughly how much memory does your process need, and why?
+  - When the client disconnects halfway through, what does your code do with the partial data it already wrote to the destination?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #23 · 1:11:43](https://www.youtube.com/watch?v=Ie0TjKI9cDI&t=4303s)
+  - [Node.js docs: Stream](https://nodejs.org/api/stream.html)
+
+## multipart-upload
+
+- **Name:** Multipart uploads
+- **Requires:** `object-storage`
+- **Signals:** `CreateMultipartUpload`, `UploadPart`, `CompleteMultipartUpload`, `AbortIncompleteMultipartUpload`, `@aws-sdk/lib-storage`
+- **Idea:** A large object is uploaded as independently sent numbered parts and then assembled, so failed parts retry alone, parts go in parallel, and huge files fit within per-request limits.
+- **Misconceptions:**
+  - Multipart upload is the same as `multipart/form-data`; one is an HTML form encoding, the other is a storage API for chunked objects.
+  - Abandoned uploads clean themselves up; incomplete parts stay stored and billed until aborted, so you need an abort lifecycle rule.
+- **Checks:**
+  - If part 37 of 80 fails in your code, what gets retried, and where do you keep the part numbers and ETags needed to complete?
+  - What in your setup removes multipart uploads that a client started but never completed or aborted?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #24 · 4:30](https://www.youtube.com/watch?v=iWrVCxexUWY&t=270s)
+  - [AWS docs: Uploading and copying objects using multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html)
+
+## range-requests
+
+- **Name:** HTTP range requests
+- **Requires:** `http-messages`
+- **Signals:** `Range: bytes=`, `Accept-Ranges: bytes`, `206 Partial Content`, `Content-Range`, `416 Range Not Satisfiable`, `If-Range`
+- **Idea:** A client asks for a byte slice of a resource with a Range header and the server returns 206 with just that slice, enabling resumable downloads and video seeking.
+- **Misconceptions:**
+  - Range support is automatic; a handler that streams a file and always returns 200 forces players and download managers to restart from byte zero.
+  - Ranges only matter for video; resumable downloads, parallel chunked fetches and reading file footers like ZIP or Parquet all depend on them.
+- **Checks:**
+  - When a client sends `Range: bytes=1000-` to your download endpoint, does your code return 206 with the right Content-Range, or the whole file?
+  - If the file changes between two range requests to your handler, how could the client end up with a corrupted mix, and what header prevents that?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #24 · 32:51](https://www.youtube.com/watch?v=iWrVCxexUWY&t=1971s)
+  - [MDN: HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Range_requests)