codecall 1.3.0 → 1.4.0

package/README.md

@@ -94,6 +94,21 @@ ideas, nothing else: no time-on-task, no mastery claim, no guess at what you
 would have known anyway. Earlier receipts in `./codecall/` add a streak line
 (sessions this week, running explain rate) and nothing more.
 
+## Backend concept map
+
+For server-side changes, codecall uses a small built-in map of about 80
+backend concepts: HTTP, auth, databases, caching, queues, webhooks, real-time,
+storage, testing and delivery. It gives concepts stable names, orders them by
+what you need to know first, and supplies known misconceptions. You never see
+the map. If a change matches nothing in it, codecall works exactly as before.
+
+When you miss a mapped concept, the receipt adds one **Go deeper** line: the
+matching chapter of Sriniously's free
+[Backend from first principles](https://www.youtube.com/playlist?list=PLui3EUkuMTPgZcV0QhQrOcwMPcBCcd_Q1)
+series, plus an official reference (MDN, OWASP, PostgreSQL and similar). The
+map's wording is codecall's own and links to the videos; it does not copy
+them. codecall is not affiliated with or endorsed by the series' creator.
+
 ## Privacy
 
 - No API key, no account, no signup, no network call.
@@ -128,6 +143,13 @@ npm test
 claude plugin validate ./plugins/codecall
 ```
 
+The backend concept map lives in
+`plugins/codecall/skills/codecall/references/backend-map/`, one Markdown file
+per cluster. Edit those files, then run `node scripts/backend-map.mjs` to
+validate them and regenerate `index.md`; `npm test` fails on a stale index, a
+broken prerequisite, a timestamp that is not a real chapter start, or a link
+outside the documentation allowlist.
+
 The canonical skill lives in `plugins/codecall/skills/codecall/`. The
 TypeScript runtime in `src/` is an offline, deterministic test harness for the
 session state machine, not the product; see [ARCHITECTURE.md](ARCHITECTURE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "type": "module",
   "description": "Implementation-grounded adaptive learning skills for Codex and Claude Code.",

package/plugins/codecall/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Adaptive implementation-grounded learning for Claude Code.",
   "author": {
     "name": "Gaurav",

package/plugins/codecall/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codecall",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Adaptive implementation-grounded learning for Codex.",
   "author": {
     "name": "Gaurav",

package/plugins/codecall/agents/codecall-planner.md

@@ -40,6 +40,11 @@ your starting evidence — you were not part of the conversation that built it.
    anti-patterns, architecture decisions, and misconceptions distinct. Order by
    prerequisite. Do not reduce a multi-concept implementation to one
    vocabulary item.
+5. Only when the change touches server-side code, read the codecall skill's
+   `references/backend-map/index.md` and follow the skill's "Backend concept
+   map" rule: at most one map id per concept, only when it truly fits, never
+   forced. Order with the ids' `requires`. You may grep `./codecall/*.html`
+   for `codecall-concepts` meta tags to find ids missed in earlier sessions.
 
 ## Output
 
@@ -51,7 +56,7 @@ Judgment: recommend | optional | skip
 Reason: <evidence-backed reason, citing the specific file/decision/signal>
 Estimated minutes: <N>
 Plan:
-  1. <concept> — <one-line why this matters here> [prerequisite: none|<concept>]
+  1. <concept> — <one-line why this matters here> [prerequisite: none|<concept>] [map: <id>|none]
   2. ...
 Evidence limits: <anything the given input didn't establish, if applicable>
 ```

package/plugins/codecall/skills/codecall/SKILL.md

@@ -36,6 +36,15 @@ metadata is not a background scheduler.
      uncommitted tree; never scan the whole repository. Judge by novelty,
      architecture impact, concept density, dependency depth, difficulty and
      real decisions, not line count.
+   - **Backend concept map:** only when the change touches server-side code
+     (handlers, auth, databases, caching, queues, webhooks, real-time,
+     storage, deployment), read
+     [references/backend-map/index.md](references/backend-map/index.md).
+     Give each planned concept at most one map id, and only when the id means
+     what this change actually does; leave the rest free-form and never bend a
+     concept to fit. Read only the cluster files holding the chosen ids. Use
+     their `requires` to order the plan. When earlier receipts' `codecall-concepts`
+     meta tags show a mapped id as missed and this change exercises it, prefer it.
 3. Show this and wait:
 
    ```text
@@ -59,7 +68,10 @@ metadata is not a background scheduler.
 3. Teach one concept: what it is, why this code needed it, what breaks without
    it, how it connects to the rest, one misconception, a concise mental model.
    Add one real-world analogy only when it clarifies, mapping each part back
-   to the code. The analogy never replaces the technical explanation.
+   to the code. The analogy never replaces the technical explanation. For a
+   mapped concept, read its card in the cluster file first (the planner may
+   only have read the index); its idea, misconceptions and checks are raw
+   material: adapt them to this code, never recite the card.
 4. Ask two checks per concept, one at a time: first an analogy-to-code mapping,
    then an application, dependency, tradeoff or debugging question. Never a
    generic definition, never a batch.
@@ -83,13 +95,18 @@ One screen, big type, no external assets. It holds:
 - The implementation in one line, and the date.
 - Each concept marked ✅ could explain or ❌ could not, with one line of why.
   A concept counts as explained when both checks were answered correctly
-  without a reteach.
+  without a reteach. A ❌ concept with a map id gets one "Go deeper" line
+  holding its card's links, exactly as written there; no other concept gets
+  links.
+- A `codecall-concepts` meta tag listing each mapped concept as `id:ok` or
+  `id:no`, comma-separated; empty when nothing was mapped.
 - The score, `Could explain N of M`, where M is the number of concepts.
 - Three points to remember, grounded in this code.
 - The edge cases to check before reusing the pattern in another project.
 - When earlier receipts exist in `./codecall/`, one streak line read from
   their `codecall-score` and `codecall-date` meta tags: sessions in the last
-  seven days and the running explain rate.
+  seven days and the running explain rate. When a concept an earlier receipt
+  marked `id:no` came back in this session, add its result to that line.
 
 Short identifiers only; never paste source code or conversation text into it.
 

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

@@ -0,0 +1,113 @@
+# API design
+
+## routing-params
+
+- **Name:** Routing, path and query parameters
+- **Requires:** `http-messages`
+- **Signals:** `/users/:id`, `req.params`, `req.query`, `r.PathValue(`, `@PathVariable`, `Query(`
+- **Idea:** A router maps method plus path to a handler; path parameters identify the resource, query parameters refine the request, and both arrive as untrusted strings.
+- **Misconceptions:**
+  - Route order never matters; many routers match first-registered, so `/users/:id` can swallow `/users/me` if declared first.
+  - Path params are already numbers; they are strings, so `"42"` and `42` compare differently until parsed.
+- **Checks:**
+  - What does your handler do with `/items/abc` when it expects a numeric id, and which status reaches the client?
+  - Your endpoint accepts a filter; would it fit better as a path segment or a query parameter, and why?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #6 · 4:28](https://www.youtube.com/watch?v=SubuU1iOC2s&t=268s)
+  - [MDN: What is a URL?](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL)
+
+## api-versioning
+
+- **Name:** API versioning and deprecation
+- **Requires:** `routing-params`
+- **Signals:** `/api/v1/`, `/v2/`, `Deprecation` header, `Sunset` header, `Accept-Version`
+- **Idea:** Versioning lets you ship breaking changes without breaking existing clients, and announced deprecation gives them time to migrate before the old version disappears.
+- **Misconceptions:**
+  - Adding a field is breaking; additive changes are usually safe, while removing, renaming or retyping fields breaks clients.
+  - A new version means copying every handler; most code stays shared, with only the changed edges adapted.
+- **Checks:**
+  - Does this change to your response shape force a new version, or can existing clients ignore it safely?
+  - How would your code tell old-version clients a sunset date, and how would you know who still calls it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #6 · 15:09](https://www.youtube.com/watch?v=SubuU1iOC2s&t=909s)
+  - [RFC 9745: The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745)
+
+## serialization-json
+
+- **Name:** Serialization and JSON
+- **Requires:** `http-messages`
+- **Signals:** `JSON.stringify(`, `json.Marshal(`, `express.json()`, `@JsonProperty`, `model_dump(`, `toJSON`
+- **Idea:** Serialization turns in-memory objects into bytes for the wire and back, and the chosen JSON shape becomes a public contract clients depend on.
+- **Misconceptions:**
+  - Returning the ORM model directly is fine; it leaks internal fields like password hashes and couples clients to your schema.
+  - JSON numbers are safe for any integer; JavaScript loses precision above 2^53, so large ids should travel as strings.
+- **Checks:**
+  - Which fields does your handler serialize, and could a new column added later leak to clients without anyone noticing?
+  - How does your code encode dates, money amounts and 64-bit ids, and would a JavaScript client read them exactly?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #7 · 8:36](https://www.youtube.com/watch?v=vzg90tY3uM0&t=516s)
+  - [RFC 8259: The JSON Data Interchange Format](https://www.rfc-editor.org/rfc/rfc8259)
+
+## input-validation
+
+- **Name:** Input validation and transformation
+- **Requires:** `serialization-json`
+- **Signals:** `z.object(`, `pydantic.BaseModel`, `@Valid`, `Joi.object(`, `validator.New(`, `class-validator`
+- **Idea:** Validation checks untrusted input against an explicit schema at the boundary and transforms it into trusted types, so the rest of the code never handles malformed data.
+- **Misconceptions:**
+  - Frontend validation is enough; anyone can call the API directly, so the server must validate everything again.
+  - Denylisting bad characters is safe; allowlisting expected shapes, types, lengths and ranges is far more reliable.
+- **Checks:**
+  - If a client sends an extra `role: "admin"` field, does your validation strip it, reject it, or pass it into the database write?
+  - Where in your code does a string from the request become a typed value, and what happens on failure?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #9 · 15:40](https://www.youtube.com/watch?v=qedj_JjjL-U&t=940s)
+  - [OWASP Cheat Sheet: Input Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)
+
+## rest-resource-design
+
+- **Name:** REST resource design
+- **Requires:** `routing-params`, `http-methods-idempotency`
+- **Signals:** `GET /orders/{id}`, `POST /orders`, `/users/{id}/orders`, `Location` header, `201 Created`
+- **Idea:** REST models the API as nouns (resources and collections) acted on by standard HTTP methods, so clients can predict endpoints and behavior without reading custom verbs.
+- **Misconceptions:**
+  - Verbs in URLs like `/createOrder` are REST; the method carries the verb, the path names the resource.
+  - Every database table needs its own endpoint; resources model what clients need, not your storage layout.
+- **Checks:**
+  - Your code adds an action like "cancel order"; would you model it as a state change on the resource or a sub-resource, and why?
+  - How deeply are your routes nested, and would a client need the parent id just to fetch a child it already knows?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #11 · 52:10](https://www.youtube.com/watch?v=RG6q57DwV8Y&t=3130s)
+  - [Microsoft Learn: Web API design best practices](https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design)
+
+## pagination-filtering
+
+- **Name:** Pagination, sorting and filtering
+- **Requires:** `rest-resource-design`
+- **Signals:** `LIMIT`, `OFFSET`, `?cursor=`, `starting_after`, `next_cursor`, `ORDER BY created_at, id`
+- **Idea:** List endpoints return bounded pages with explicit sort and filter rules, so response size and query cost stay predictable as data grows.
+- **Misconceptions:**
+  - OFFSET pagination scales; the database still reads and discards skipped rows, and concurrent inserts shift pages, so cursors suit large feeds.
+  - Sorting by a non-unique column is stable; without a tiebreaker like id, rows can repeat or vanish across pages.
+- **Checks:**
+  - What stops a client calling your list endpoint with `limit=1000000`, and what would that do to your database?
+  - If a row is inserted while a client pages through your results, can it see a duplicate or miss an item?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #11 · 1:10:18](https://www.youtube.com/watch?v=RG6q57DwV8Y&t=4218s)
+  - [Stripe docs: Pagination](https://docs.stripe.com/api/pagination)
+
+## openapi-contract
+
+- **Name:** OpenAPI as the API contract
+- **Requires:** `rest-resource-design`
+- **Signals:** `openapi.yaml`, `openapi: 3.1`, `swagger-ui`, `@ApiOperation`, `components/schemas`, `/docs`
+- **Idea:** An OpenAPI document describes endpoints, parameters and schemas in a machine-readable file that drives docs, client generation, mocks and contract tests from one source.
+- **Misconceptions:**
+  - A spec written once stays accurate; unless it is generated from code or checked in CI, it drifts from the real behavior.
+  - OpenAPI is only documentation; the same file can validate requests and generate typed clients.
+- **Checks:**
+  - If your handler changed a field today, what in your setup would catch that the OpenAPI spec no longer matches?
+  - Does your spec come from code annotations or is it written first, and what does that choice cost your team?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #28 · 16:39](https://www.youtube.com/watch?v=CwKsU84jIWs&t=999s)
+  - [OpenAPI Initiative: Getting started](https://learn.openapis.org/)

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

@@ -0,0 +1,65 @@
+# Request flow and layering
+
+## middleware-pipeline
+
+- **Name:** Middleware pipeline
+- **Requires:** `http-messages`
+- **Signals:** `app.use(`, `next()`, `MIDDLEWARE = [`, `func(next http.Handler)`, `@app.middleware("http")`, `OncePerRequestFilter`
+- **Idea:** Middleware are functions wrapped around every handler in a fixed order, handling cross-cutting work like logging, auth, parsing and error handling once instead of in each route.
+- **Misconceptions:**
+  - Middleware order is cosmetic; auth after the router, or the error handler registered first, silently changes what runs and what is protected.
+  - A middleware that forgets to call `next()` just skips itself; the request hangs or ends there without reaching the handler.
+- **Checks:**
+  - In your app, does the body parser or auth middleware run before the route that needs it, and what happens if the order flips?
+  - If a handler throws, which middleware in your chain turns it into a response, and does logging still record the request?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #10 · 26:52](https://www.youtube.com/watch?v=hyc-7w3pee8&t=1612s)
+  - [Microsoft Learn: ASP.NET Core middleware](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/)
+
+## request-context
+
+- **Name:** Request context
+- **Requires:** `middleware-pipeline`
+- **Signals:** `context.Context`, `r.Context()`, `res.locals`, `req.user`, `AsyncLocalStorage`, `contextvars`
+- **Idea:** Request context carries per-request data such as user, request id and deadline through middleware and layers, and lets cancellation stop downstream work when the client disconnects.
+- **Misconceptions:**
+  - Storing the current user in a module-level variable works; concurrent requests overwrite each other and one user sees another's data.
+  - Context is a bag for any parameter; it suits request-scoped metadata, while required business inputs belong in explicit arguments.
+- **Checks:**
+  - If the client disconnects mid-request, does your code pass the context or signal into the database call so the query is cancelled?
+  - How does the request id set in your middleware reach the log lines your service and repository write?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #10 · 50:57](https://www.youtube.com/watch?v=hyc-7w3pee8&t=3057s)
+  - [Go blog: Go Concurrency Patterns: Context](https://go.dev/blog/context)
+
+## handler-service-repository
+
+- **Name:** Handler, service and repository layers
+- **Requires:** `routing-params`
+- **Signals:** `controllers/`, `services/`, `repositories/`, `@Service`, `@Repository`, `UserRepository`
+- **Idea:** Handlers translate HTTP, services hold business rules, and repositories hide storage, so each layer changes for one reason and logic can run without HTTP or a database.
+- **Misconceptions:**
+  - Layers are bureaucracy for small apps; even a thin service keeps rules out of handlers so a job or CLI can reuse them.
+  - Services can return HTTP status codes or take `req`; that leaks transport into business logic and blocks reuse.
+- **Checks:**
+  - Which business rule in your handler would have to be copied if a background job needed the same behavior?
+  - Does your repository return database rows or domain objects, and what breaks in callers if a column is renamed?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #10 · 18:23](https://www.youtube.com/watch?v=hyc-7w3pee8&t=1103s)
+  - [Martin Fowler: Presentation Domain Data Layering](https://martinfowler.com/bliki/PresentationDomainDataLayering.html)
+
+## dependency-injection
+
+- **Name:** Dependency injection and a testable core
+- **Requires:** `handler-service-repository`
+- **Signals:** `constructor(private readonly`, `Depends(`, `@Autowired`, `@Injectable()`, `NewUserService(repo`, `wire.Build(`
+- **Idea:** A component receives its collaborators (database, clock, HTTP client) from outside instead of creating them, so tests and other environments can swap in fakes without editing the code.
+- **Misconceptions:**
+  - Dependency injection requires a framework or container; passing dependencies as constructor or function arguments is the whole idea.
+  - Mocking imports with patching is equivalent; it couples tests to file layout and hides how many dependencies a component really has.
+- **Checks:**
+  - To unit test your service without a real database, what would you pass in, and does your code currently allow that?
+  - Where does your code call `new`, a global client, or the current time directly, and how would that make a test flaky?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #26 · 37:24](https://www.youtube.com/watch?v=HgVrfHX92y4&t=2244s)
+  - [Martin Fowler: Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html)

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

@@ -0,0 +1,81 @@
+# Background work and webhooks
+
+## background-jobs
+
+- **Name:** Background jobs and task queues
+- **Requires:** none
+- **Signals:** `BullMQ`, `@shared_task`, `perform_later`, `@Async`, `visibilityTimeout`, `dead-letter queue`
+- **Idea:** Slow or failure-prone work like emails, image processing or third-party calls is put on a durable queue and run by separate workers, so the request returns quickly and the work survives crashes.
+- **Misconceptions:**
+  - Firing an unawaited promise or thread from the request handler is a background job; it vanishes on a crash or deploy and nothing retries it.
+  - A queued job runs exactly once; brokers redeliver after visibility timeouts or worker crashes, so job handlers must be safe to run twice.
+- **Checks:**
+  - If the worker dies halfway through this job in your code, what state is left behind and what happens when the job is retried?
+  - What does your code do with a job that fails every attempt, and how would anyone find out it is stuck?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #14 · 9:17](https://www.youtube.com/watch?v=r-nQsyguU1Y&t=557s)
+  - [Microsoft Learn: Best practices for background jobs](https://learn.microsoft.com/en-us/azure/architecture/best-practices/background-jobs)
+
+## idempotency-keys
+
+- **Name:** Idempotency keys and at-least-once delivery
+- **Requires:** `http-methods-idempotency`
+- **Signals:** `Idempotency-Key`, `ON CONFLICT DO NOTHING`, `processed_events` table, unique index on an event or request id
+- **Idea:** When a sender may deliver the same request twice, a key the receiver remembers turns the second delivery into a no-op that returns the first result.
+- **Misconceptions:**
+  - Checking "have I seen this id?" and then inserting is safe; two concurrent duplicates both pass the check unless a unique constraint decides.
+  - Retries are rare enough to ignore; every queue, webhook provider and mobile client on a flaky network retries by design.
+- **Checks:**
+  - If two copies of the same event reach your handler at the same moment, which line in your code stops the second one from charging twice?
+  - How long does your code keep processed keys, and what happens to a duplicate that arrives after they expire?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 27:39](https://www.youtube.com/watch?v=eWM0CVReP04&t=1659s)
+  - [Stripe docs: Idempotent requests](https://docs.stripe.com/api/idempotent_requests)
+
+## transactional-outbox
+
+- **Name:** Transactional outbox
+- **Requires:** `transactions-isolation`, `background-jobs`
+- **Signals:** `outbox_events`, `INSERT INTO outbox`, `FOR UPDATE SKIP LOCKED`, `published_at IS NULL`, `Debezium`
+- **Idea:** Save the event to an outbox table inside the same transaction as the data change, and let a relay publish it later, so a commit and its message can never disagree.
+- **Misconceptions:**
+  - Publishing to the broker right after commit is close enough; a crash between the two loses the event, and publishing before commit announces data that may roll back.
+  - The outbox gives exactly-once delivery; the relay can publish a row and crash before marking it sent, so consumers still need deduplication.
+- **Checks:**
+  - If your process crashes right after the database commit in this code, how does the event still reach the queue?
+  - How does your relay stop two instances publishing the same outbox row, and what keeps the outbox table from growing forever?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 38:58](https://www.youtube.com/watch?v=eWM0CVReP04&t=2338s)
+  - [microservices.io: Pattern: Transactional outbox](https://microservices.io/patterns/data/transactional-outbox.html)
+
+## webhook-receiver
+
+- **Name:** Receiving webhooks
+- **Requires:** `idempotency-keys`
+- **Signals:** `/webhooks/stripe`, `express.raw(`, `@csrf_exempt`, `switch (event.type)`, `event.id`
+- **Idea:** A webhook is an HTTP request another service sends when something changes there, so your endpoint must acknowledge fast and handle events arriving late, twice or out of order.
+- **Misconceptions:**
+  - Doing all the work inside the webhook request is fine; slow handlers hit the sender's timeout, get marked failed and are redelivered while still running.
+  - Events arrive in the order they happened; providers retry independently, so an older update can land after a newer one unless you compare timestamps or refetch state.
+- **Checks:**
+  - If your handler crashes after updating the database but before returning 200, what happens when the provider redelivers the same event?
+  - Which status codes does your endpoint return for unknown event types and for internal errors, and how will the sender react to each?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 9:56](https://www.youtube.com/watch?v=eWM0CVReP04&t=596s)
+  - [GitHub Docs: Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)
+
+## webhook-signatures
+
+- **Name:** Verifying webhook signatures (HMAC)
+- **Requires:** `webhook-receiver`
+- **Signals:** `Stripe-Signature`, `X-Hub-Signature-256`, `crypto.timingSafeEqual`, `hmac.compare_digest`, `hmac.Equal`, `constructEvent(`
+- **Idea:** The sender signs the raw request body with a shared secret using HMAC, and your endpoint recomputes the signature to prove the request is genuine, unmodified and recent before trusting it.
+- **Misconceptions:**
+  - Verifying against the parsed JSON works; re-serializing changes bytes and spacing, so the signature must be computed over the exact raw body received.
+  - Comparing signatures with `==` is fine; an ordinary string compare can leak timing information, so use a constant-time comparison function.
+- **Checks:**
+  - Does your handler read the raw body before any JSON middleware parses it, and what happens to verification if that middleware order changes?
+  - How does your code reject a correctly signed request that was captured last week and replayed today?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #29 · 16:52](https://www.youtube.com/watch?v=eWM0CVReP04&t=1012s)
+  - [GitHub Docs: Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)

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

@@ -0,0 +1,97 @@
+# Authentication and authorization
+
+## session-auth
+
+- **Name:** Session-based authentication
+- **Requires:** `http-messages`
+- **Signals:** `express-session`, `req.session`, `SESSION_ENGINE`, `connect-redis`, `session_id` cookie, `regenerate(`
+- **Idea:** After login the server stores session state and gives the browser an opaque random id in a cookie, so each request is authenticated by looking that id up server-side.
+- **Misconceptions:**
+  - Keeping the same session id after login is fine; it enables session fixation, so regenerate the id whenever privilege changes.
+  - In-memory session stores work in production; they vanish on restart and are not shared across instances behind a load balancer.
+- **Checks:**
+  - When a user logs out or changes their password, which line in your code destroys the server-side session, and do other sessions survive?
+  - With two instances of your app behind a load balancer, where do sessions live and does a request reaching the other instance still work?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #8 · 18:26](https://www.youtube.com/watch?v=A95rliroC8Q&t=1106s)
+  - [OWASP Cheat Sheet: Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
+
+## cookie-security
+
+- **Name:** Cookie security attributes
+- **Requires:** `session-auth`
+- **Signals:** `HttpOnly`, `Secure`, `SameSite=Lax`, `__Host-`, `res.cookie(`, `SESSION_COOKIE_SECURE`
+- **Idea:** Cookie attributes control who can read a cookie and when browsers send it, limiting theft by scripts, exposure over plain HTTP and cross-site request forgery.
+- **Misconceptions:**
+  - `HttpOnly` stops XSS; it only hides the cookie from JavaScript, while injected script can still send requests as the user.
+  - `SameSite=Lax` replaces all CSRF defenses; state-changing GET requests and same-site subdomains still need protection.
+- **Checks:**
+  - Which attributes does your code set on the session cookie, and what could a script injected into your page do with it?
+  - If your frontend and API live on different sites, which `SameSite` value does your cookie need, and what CSRF defense must replace it?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 1:07:17](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=4037s)
+  - [MDN: Using HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies)
+
+## jwt-auth
+
+- **Name:** JWTs and stateless authentication
+- **Requires:** `http-messages`
+- **Signals:** `Authorization: Bearer`, `jwt.verify(`, `jsonwebtoken`, `PyJWT`, `golang-jwt`, `exp` claim
+- **Idea:** A JWT is a signed token carrying claims the server verifies with a key instead of a database lookup, trading easy horizontal scaling for harder revocation.
+- **Misconceptions:**
+  - JWT payloads are encrypted; they are only base64url-encoded and signed, so anyone holding the token can read the claims.
+  - Logging out deletes the token; a stolen JWT stays valid until `exp` unless you keep short lifetimes or a denylist.
+- **Checks:**
+  - Does your verification pin the expected algorithm and check `exp`, `iss` and `aud`, or does it trust whatever the token header says?
+  - If an account is disabled right now, how long can an already-issued token keep calling your API, and is that acceptable?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #8 · 25:40](https://www.youtube.com/watch?v=A95rliroC8Q&t=1540s)
+  - [RFC 8725: JSON Web Token Best Current Practices](https://www.rfc-editor.org/rfc/rfc8725)
+
+## oauth2-oidc
+
+- **Name:** OAuth 2.0 and OpenID Connect
+- **Requires:** `jwt-auth`
+- **Signals:** `/oauth/authorize`, `code_challenge`, `redirect_uri`, `id_token`, `openid profile email`, `passport-google-oauth20`
+- **Idea:** OAuth 2.0 lets an app obtain scoped access tokens without seeing the user's password, and OpenID Connect adds an ID token so the app also learns who signed in.
+- **Misconceptions:**
+  - OAuth is an authentication protocol; it grants access, and using an access token as proof of identity is unsafe without OIDC's ID token.
+  - PKCE is only for mobile apps; current best practice recommends it for every authorization code flow, including server-side apps.
+- **Checks:**
+  - In your callback handler, which checks verify `state`, the ID token signature, `aud` and `nonce` before you create a local session?
+  - Which scopes does your code request, and what could an attacker do if the stored provider token leaked?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #8 · 50:25](https://www.youtube.com/watch?v=A95rliroC8Q&t=3025s)
+  - [OAuth.net: OAuth 2.0](https://oauth.net/2/)
+
+## password-hashing
+
+- **Name:** Password hashing
+- **Requires:** none
+- **Signals:** `argon2id`, `bcrypt.hash(`, `scrypt`, `PBKDF2`, `password_hash`, `check_password(`
+- **Idea:** Passwords are stored as slow, salted one-way hashes, so a leaked database cannot be reversed cheaply and identical passwords produce different hashes.
+- **Misconceptions:**
+  - SHA-256 with a salt is enough; fast hashes allow billions of guesses per second, so use Argon2id, scrypt or bcrypt.
+  - Encrypting passwords is safer than hashing; anyone holding the key decrypts every password, while hashes cannot be reversed.
+- **Checks:**
+  - What work factor does your code use, and how would you upgrade old hashes when users next log in?
+  - Does your login handler take the same time and return the same error for an unknown email and a wrong password?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #20 · 45:25](https://www.youtube.com/watch?v=xB1C1xZZW4k&t=2725s)
+  - [OWASP Cheat Sheet: Password Storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+
+## rbac-authorization
+
+- **Name:** Role-based authorization
+- **Requires:** `session-auth`
+- **Signals:** `@PreAuthorize`, `hasRole(`, `requireRole(`, `user.role ===`, `permission_required`, `WHERE owner_id =`
+- **Idea:** Authorization decides what an authenticated user may do, typically by mapping roles to permissions and checking both the action and ownership of the specific resource on the server.
+- **Misconceptions:**
+  - Hiding a button in the UI enforces permissions; the API must check every request because anyone can call it directly.
+  - A role check is enough; without verifying the user owns the record, changing an id in the URL exposes other users' data.
+- **Checks:**
+  - If a regular user changes the id in this request to someone else's record, which line in your code stops them?
+  - Your code checks `role === "admin"` in several handlers; how would you add a new role without editing each of them?
+- **Go deeper:**
+  - [Sriniously · Backend from first principles #8 · 1:19:10](https://www.youtube.com/watch?v=A95rliroC8Q&t=4750s)
+  - [OWASP Cheat Sheet: Authorization](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)

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