Skip to content

Engineering handbook

How I build and run software, written down. Twenty deep dives that show the way I work from schema to deployment, and a searchable collection of field notes behind them.

deep dives
20deep dives
field notes
281field notes
areas of practice
14areas of practice

The signature twenty

The pieces that best show how I think: systems and ERP depth first, then delivery and leadership, then the craft underneath.

Field notes

Short, specific rules and lessons across 14 areas. Open one for the detail, or follow its link to the full write-up.

281 of 281 notes

  • ArchitectureDesign the data before the endpoints

    Endpoints are cheap to change. A wrong schema in production is not. Sketch tables, relations and the tenancy model first.

    Read the deep diveLink to this note

  • ArchitectureArchitecture first, then code

    No implementation before the design is reviewed. A day of design costs less than a week of rework.

    Link to this note

  • ArchitectureWrite the module breakdown from the business requirements

    A module map derived from real requirements keeps scope honest and gives every engineer the same picture.

    Link to this note

  • ArchitecturePrefer vertical slices to horizontal layers

    Organise by feature so one change touches one folder, instead of scattering a feature across controllers, services and models.

    Read the deep diveLink to this note

  • ArchitectureRecord every non-obvious decision

    A short decision record states what was chosen, why, and what was rejected. It saves the next engineer from re-arguing it.

    Link to this note

  • ArchitectureMake the boundary the contract

    Between services, and between portal and ERP, define exactly what crosses and who owns it. Most integration pain is an unclear boundary.

    Link to this note

  • ArchitectureStart with a modular monolith

    Split into microservices only where billing, sync or scale earns it. Premature services multiply deployment and debugging cost.

    Link to this note

  • ArchitectureSplit a service when it has a different failure or scaling profile

    Usage-based billing and bulk sync behave differently from request/response APIs. That is a reason to separate them, not fashion.

    Link to this note

  • ArchitecturePut an adapter in front of every third-party system

    Your code talks to your interface. Swapping, mocking or retrying a vendor then touches one file.

    Link to this note

  • ArchitecturePrefer boring technology on the critical path

    Use well-understood tools for auth, payments and data. Spend novelty budget where it differentiates the product.

    Link to this note

  • ArchitectureKnow what the system of record is

    For every entity, name the one system that owns the truth. Everything else is a cache and should behave like one.

    Link to this note

  • ArchitectureDesign for the failure of every dependency

    Ask what happens when the ERP, the payment provider or the mail service is down. A queue and a status field beat an error page.

    Link to this note

  • ArchitectureMake state transitions explicit

    Orders, proposals and syncs move through named states. Encode allowed transitions so impossible states cannot exist.

    Link to this note

  • ArchitectureKeep read models separate when reads dominate

    Dashboards and lists can use shaped queries or cached projections without bending the write model.

    Link to this note

  • ArchitecturePrefer idempotent operations

    If doing it twice is safe, retries, replays and duplicate webhooks stop being incidents.

    Read the deep diveLink to this note

  • ArchitectureVersion anything a client depends on

    API paths, webhook payloads, AL extension APIs. A breaking change gets a new version, and the old one keeps its contract.

    Link to this note

  • ArchitecturePut cross-cutting concerns in the framework

    Auth, validation, logging, error shaping and audit belong in guards, pipes, filters and interceptors, not in every handler.

    Link to this note

  • ArchitectureDiagram the data flow, not the boxes

    A sequence of who calls whom and what is stored tells you more than a layered picture ever will.

    Link to this note

  • Backend and NestJSUse DTO classes for every payload

    Each incoming body, query and param has a typed class with validation decorators. Nothing reaches a service unvalidated.

    Link to this note

  • Backend and NestJSTurn on whitelisting in the validation pipe

    Strip unknown properties, or reject them. It stops a client from smuggling a role or tenant id into a create call.

    Link to this note

  • Backend and NestJSReturn response DTOs, not entities

    Never serialise a database model directly. A response class decides exactly which fields can leave the system.

    Read the deep diveLink to this note

  • Backend and NestJSApply the auth guard globally

    Protect by default and mark exceptions with a public decorator. Forgetting a guard should be impossible.

    Link to this note

  • Backend and NestJSWrap the ORM in a repository

    Services call repositories. Tests stub one small class and an ORM upgrade touches one layer.

    Read the deep diveLink to this note

  • Backend and NestJSLet a global exception filter shape every error

    One place formats errors, hides stack traces and attaches an error code. Controllers throw and forget.

    Link to this note

  • Backend and NestJSUse an interceptor for the response envelope

    Wrapping success responses in one interceptor keeps every endpoint's shape identical.

    Read the deep diveLink to this note

  • Backend and NestJSLog writes through an audit interceptor

    Capturing who changed what, automatically, gives support and compliance a trail without per-handler code.

    Link to this note

  • Backend and NestJSKeep controllers thin

    A controller parses input, calls a service and returns. If it has an if-statement about business rules, it is in the wrong place.

    Link to this note

  • Backend and NestJSInject configuration, do not read process.env everywhere

    A typed config service validated at startup fails fast on a missing variable instead of failing mid-request.

    Link to this note

  • Backend and NestJSFail fast on bad environment

    Validate required variables at boot. A crash on deploy is better than a half-working service.

    Link to this note

  • Backend and NestJSPrefer constructor injection and small modules

    Each module exports only what others need. Circular dependencies are a design smell, not a Nest quirk.

    Link to this note

  • Backend and NestJSShare auth and RBAC as workspace packages

    In a monorepo, reuse beats copy-paste. One fix reaches every service.

    Read the deep diveLink to this note

  • Backend and NestJSUse transactions for multi-step writes

    Create-plus-children-plus-balances happen in one transaction. Test that a failure leaves nothing behind.

    Link to this note

  • Backend and NestJSInside a transaction callback, use only the transaction client

    Reaching for the outer client opens a second connection and can deadlock.

    Link to this note

  • Backend and NestJSPaginate every list on the server

    Default 20, maximum 100. Never return an unbounded collection.

    Link to this note

  • Backend and NestJSWhitelist sortable and filterable fields

    Query-string filters map onto a fixed list of columns, so a client cannot sort by anything it likes.

    Link to this note

  • Backend and NestJSUse soft delete for personal data

    Mark deleted, filter in one place, and purge for real after the retention period.

    Link to this note

  • Backend and NestJSKeep long work off the request path

    Queue, schedule or run it after responding. Users should not wait for an LLM call or a bulk sync.

    Link to this note

  • Backend and NestJSUse a scheduler for retention and cleanup

    Expiring tokens, purging old records and flagging stale state are jobs with tests, not manual chores.

    Link to this note

  • Backend and NestJSPrefer a structured logger to console output

    Structured logs with levels and correlation ids can be searched. Console lines cannot.

    Link to this note

  • Backend and NestJSStrip PII from log lines

    No emails, names or tokens in logs. Log ids and let people look the rest up where access is controlled.

    Link to this note

  • Backend and NestJSHealth endpoints should check real dependencies

    A health route that only returns ok hides a broken database connection.

    Link to this note

  • Backend and NestJSUse URI versioning for public APIs

    /api/v1/... makes versions visible, cacheable and routable at the proxy.

    Link to this note

  • Backend and NestJSKeep module docs next to the module

    A short page per module on what it does and which behaviour is deliberate saves archaeology later.

    Link to this note

  • API designResources are nouns, collections are plural

    GET /invoices, not GET /getInvoices. Nest relations: /companies/:id/users.

    Link to this note

  • API designUse HTTP methods for what they mean

    GET reads, POST creates, PUT replaces, PATCH updates part, DELETE removes. GET, PUT and DELETE must be idempotent.

    Link to this note

  • API designOne response envelope for every endpoint

    A success flag, data, and meta for pagination. Errors use the same outer shape.

    Read the deep diveLink to this note

  • API designUse stable error code constants

    Clients should branch on a code like VALIDATION_FAILED, not parse a message.

    Link to this note

  • API design400 means invalid, 422 means not allowed by a rule

    Separate malformed input from valid input that violates a business rule.

    Link to this note

  • API designUse 409 for conflicts

    Unique constraint violations and state conflicts deserve their own status, so clients can handle them.

    Link to this note

  • API design401 versus 403 is not interchangeable

    401 is no or bad credentials. 403 is a valid user who is not allowed.

    Link to this note

  • API designReturn 404 for soft-deleted records

    To the client a deleted thing does not exist. Do not leak that it once did.

    Link to this note

  • API designRate limit with a Retry-After header

    A 429 without a retry hint invites hammering. Tell clients when to come back.

    Link to this note

  • API designCap page size

    A client that can request limit=100000 can take your database down.

    Link to this note

  • API designReturn the total in meta

    UIs need it for page controls, and a second count request wastes a round trip.

    Link to this note

  • API designMerge count and find where the database allows

    One pass for rows and total cut list latency noticeably on a busy platform.

    Link to this note

  • API designNever change a contract in place

    Add a field, deprecate, then version. A breaking change creates v2.

    Link to this note

  • API designMake writes safe to retry

    Accept an idempotency key on operations that create money or documents.

    Link to this note

  • API designDocument with examples, not just schemas

    A real request and response teaches faster than a field table. Gate interactive docs off in production.

    Link to this note

  • API designModel long operations as resources

    Return 202 with a status resource instead of holding a connection for minutes.

    Link to this note

  • Security and authTokens belong in HttpOnly cookies

    A token JavaScript can read is a token an XSS bug can steal. Use HttpOnly, Secure and SameSite cookies.

    Read the deep diveLink to this note

  • Security and authKeep access tokens short-lived

    Fifteen minutes limits the damage of a leak. Use a refresh token for session length.

    Link to this note

  • Security and authRotate refresh tokens on every use

    Issue a new pair and revoke the old one immediately. A stolen, replayed token then fails.

    Link to this note

  • Security and authStore refresh tokens hashed

    If the database leaks, hashed refresh tokens cannot be replayed.

    Link to this note

  • Security and authPut only what you need in the token

    User id, tenant id, role. Anything else can be fetched, and anything readable is visible.

    Link to this note

  • Security and authReject tokens without a tenant claim

    In multi-tenant systems the guard is the choke point. A token with no tenant must never pass.

    Link to this note

  • Security and authAlways clear cookies on the server at logout

    Never rely on client script to remove them. Revoke the refresh token too.

    Link to this note

  • Security and authHash passwords with bcrypt at 12 rounds or more

    Use 14 for new services. Never store, log or email a plaintext password.

    Link to this note

  • Security and authUse cryptographic randomness for reset tokens

    crypto.randomBytes, a TTL of 24 hours or less, and single use.

    Link to this note

  • Security and authMake verification tokens one-time

    Invalidate on use. A replayable link is a standing back door.

    Link to this note

  • Security and authRate limit login harder than anything else

    Five attempts a minute is plenty. Reset and resend endpoints get stricter limits still.

    Link to this note

  • Security and authOffer TOTP 2FA, and enforce it for internal users

    Admin accounts without a second factor are the usual way in.

    Link to this note

  • Security and authNever use a wildcard CORS origin in production

    Use an allowlist from configuration. Credentials plus wildcard is not allowed anyway, and for good reason.

    Link to this note

  • Security and authSet security headers by default

    helmet gives sensible defaults in one line. Strip X-Powered-By.

    Link to this note

  • Security and authValidate file uploads by content

    Check magic bytes, not the extension. Enforce a size limit and store outside the web root.

    Link to this note

  • Security and authPrefix storage paths with the tenant from the token

    Never trust a client-supplied path prefix.

    Link to this note

  • Security and authNever fetch a user-supplied URL without an allowlist

    That is how SSRF starts. Resolve and check the destination.

    Link to this note

  • Security and authAudit dependencies before you merge

    npm audit and automated dependency updates. Check licences and maintenance for new packages.

    Link to this note

  • Security and authCommit lock files and pin major versions

    Reproducible installs are a security property, not just a convenience.

    Link to this note

  • Security and authKeep secrets out of git, always

    A committed example file lists names only. Check git status before staging, so a stray env file is spotted.

    Link to this note

  • Security and authRotate any secret that touched a chat or a ticket

    Treat it as compromised. Rotation is cheap, an incident is not.

    Link to this note

  • Security and authSeparate response classes per role

    Hiding a field with a ternary is how it leaks. A role without the property cannot return it.

    Read the deep diveLink to this note

  • Security and authTest authorisation as an attacker

    Call every endpoint as every role, try role escalation in a signup body, and try cross-tenant reads.

    Link to this note

  • Security and authRecord security findings, do not silently fix them

    A public signup that accepts a role field belongs in the security notes and in a ticket, with a visible fix.

    Link to this note

  • Security and authUse a threat model per integration

    Three questions: what can go wrong, who can abuse it, what do we do about it. Keep it to a page.

    Link to this note

  • Security and authVerify webhook signatures on raw bodies

    Re-serialised JSON will not match. Reject and log failures.

    Read the deep diveLink to this note

  • Security and authPrefer least privilege for service accounts

    Give an integration app the permission set it needs and nothing more.

    Link to this note

  • Security and authMask secrets in every output

    Logs, error pages, support screenshots and chat transcripts all end up somewhere.

    Link to this note

  • Data and databasesUse time-ordered UUIDs for primary keys

    They are unguessable, sortable by creation, and safe to generate in the app. Keep legacy ids in a separate column during migrations.

    Link to this note

  • Data and databasesMoney is a decimal, and the API returns a string

    Never a floating-point number. Decimal(28,10) for amounts, a narrower type for rates.

    Read the deep diveLink to this note

  • Data and databasesAdd timestamps to every table

    createdAt, updatedAt and, where it applies, deletedAt. Debugging without them is guessing.

    Link to this note

  • Data and databasesIndex what you filter and sort on

    Look at real query shapes. Compound indexes should lead with the most selective column, and with the tenant id on shared tables.

    Link to this note

  • Data and databasesProfile before you cache

    Most slow screens are one bad query or too many queries. Fix the query, then decide whether a cache is still needed.

    Link to this note

  • Data and databasesCollapse five analytics queries into one

    A single well-shaped query often beats a chatty dashboard, and keeps the numbers consistent with each other.

    Link to this note

  • Data and databasesUse enums for statuses and roles

    Free-text statuses drift. An enum is validated by the database and visible in the schema.

    Link to this note

  • Data and databasesModel small fixed shapes as columns

    A borrower name and email are columns. Embedding them as an object buys nothing in a relational store.

    Link to this note

  • Data and databasesModel lists with identity as child tables

    Give them an id and a position. Free-form blobs go in a JSON column.

    Link to this note

  • Data and databasesNever drop an array of ids

    Use join tables. They are lossless, indexable and enforce referential integrity.

    Link to this note

  • Data and databasesDecide foreign key delete rules deliberately

    Restrict for financial links, SetNull for audit pointers, Cascade for owned children. Then test the delete flows.

    Link to this note

  • Data and databasesEnforce invariants in the database too

    A service-level check can be bypassed. A unique index or a CHECK constraint cannot.

    Link to this note

  • Data and databasesUse partial unique indexes for conditional uniqueness

    Unique only where the record is active, for example. It is expressive and enforced.

    Link to this note

  • Data and databasesA unique violation aborts a Postgres transaction

    You cannot retry the next statement inside it. Check for existence first, or retry the whole transaction.

    Link to this note

  • Data and databasesMake migrations small and reversible in intent

    One change per migration, named for what it does. Never edit one that has shipped.

    Link to this note

  • Data and databasesRun a schema drift check in CI

    The schema file and the migration history must agree, or someone's laptop is the real source of truth.

    Link to this note

  • Data and databasesNever reset a shared or production database

    Destructive commands run on local databases through guarded scripts, nowhere else.

    Link to this note

  • Data and databasesKeep seeds and tests off shared databases

    Point them at a local instance. A test that writes to a shared dev database is a team incident.

    Link to this note

  • Data and databasesTest on the real database engine

    An embedded stand-in is not the real thing. Concurrency, collation and error codes differ, so verify on real PostgreSQL.

    Link to this note

  • Data and databasesUse a pool of one when a test double shares a session

    Some embedded servers share one SQL session across connections and interleave. Serialise the tests.

    Link to this note

  • Data and databasesQualify the schema in raw SQL

    Raw queries can ignore the client's schema setting. Be explicit.

    Link to this note

  • Data and databasesLower-case emails on write and on lookup

    Otherwise the same person registers twice.

    Link to this note

  • Data and databasesRemember text sort order depends on collation

    Postgres and Mongo sort differently. Surface it in the migration notes if users sort lists.

    Link to this note

  • Data and databasesAggregation pipelines skip query hooks

    In Mongo, start every pipeline with a manual tenant match. Hooks do not run for aggregate.

    Read the deep diveLink to this note

  • Data and databasesSumming strings gives zero in Mongo aggregations

    Money stored as strings breaks totals silently. Migrating to decimals reveals logic that never worked.

    Link to this note

  • Data and databasesFilter nullish values before building ObjectIds

    new ObjectId(undefined) creates a random id and a phantom link.

    Link to this note

  • Data and databasesUse TTL indexes only for purely time-based expiry

    For conditional retention, an explicit job is visible and testable.

    Link to this note

  • Data and databasesPrefer ILIKE and contains before reaching for full-text search

    Add trigram indexes later if it is slow. Measure first.

    Link to this note

  • Data and databasesSoft-delete with a retention plan

    Mark, filter centrally, purge on schedule. Document the period per data type.

    Read the deep diveLink to this note

  • Data and databasesReconcile after any bulk move

    Counts, orphan foreign keys and exact decimal sums, checked directly on the target and not just in the script's report.

    Link to this note

  • Multi-tenancyChoose the tenancy model before the first table

    Shared tables, schema per tenant or database per tenant. It shapes migrations, backups and performance.

    Read the deep diveLink to this note

  • Multi-tenancyStart shared unless there is a concrete reason not to

    It is the cheapest to operate and the easiest to evolve.

    Link to this note

  • Multi-tenancyEnforce isolation in one place

    A plugin, a guard or a row-level policy, never a filter each developer must remember.

    Link to this note

  • Multi-tenancyCarry the tenant in the signed token

    The server decides the tenant from the claim, never from a request field.

    Link to this note

  • Multi-tenancyLead compound indexes with the tenant id

    Scoped queries use them, and uniqueness becomes per tenant.

    Link to this note

  • Multi-tenancyMake background jobs set the tenant explicitly

    Outside a request there is no current tenant. A job without one should fail loudly.

    Link to this note

  • Multi-tenancyTest with a second tenant

    Create data for tenant A, authenticate as tenant B, and assert nothing comes back.

    Link to this note

  • Multi-tenancySchema per tenant needs idempotent migrations

    A failed run must be safe to run again. ON CONFLICT DO NOTHING is your friend.

    Link to this note

  • Multi-tenancyUse a worker pool for per-tenant jobs

    One connection per worker lets dozens of tenants migrate in parallel without starving the database.

    Link to this note

  • Multi-tenancyReserve database per tenant for contractual needs

    It has the highest operating cost. Use it when a contract demands separation, and no earlier.

    Link to this note

  • Enterprise SaaS and BillingDraw the tenancy hierarchy first

    Platform Admins govern global health; Resellers manage retained clients; Clients operate self-service portals.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingIsolate tenant state with AsyncLocalStorage

    Carry tenant context in Node.js AsyncLocalStorage to prevent cross-tenant database leakage automatically.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingCompute money in integer minor units

    Never use floating-point numbers for wholesale margins. Store pence/cents to eliminate compounding rounding errors.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingStream PDFs instead of buffering memory

    When generating regulatory inspection certificates with photos, stream directly to response and cloud storage.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingAbstract cloud storage behind a common provider

    Support both AWS S3 and Azure Blob SAS tokens through a swappable interface without changing business logic.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingSign outgoing webhook payloads with HMAC-SHA256

    Allow subscriber endpoints to cryptographically verify payload authenticity using shared secret keys.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingEnforce sandwich rules across calendar boundaries

    Weekend days sandwiched between active leaves must be automatically deducted according to corporate policy.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingSeparate client store from server cache

    Manage API cache with TanStack Query and local UI interactions with lightweight Zustand stores.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingGate routes with 5-level hierarchical RBAC

    Super Admin, Org Admin, HR Manager, Department Manager, and Employee inherit permissions through rank bitmasks.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingStore tokens in httpOnly cookies, never localStorage

    Prevent credential exfiltration by keeping access and refresh tokens out of reach of malicious browser scripts.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingRotate refresh tokens on every single use

    Detect token replay attacks in Redis and revoke the entire token family immediately upon breach detection.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingUse $facet aggregations for executive rollups

    Compute deal totals, product category breakdowns, and gross profit distributions in a single indexed query.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingDownsample inspection photos before embedding

    Mobile cameras capture 12MP photos. Downsample to 300 DPI WebP/JPEG to prevent PDF memory bloat.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingAdvance sync checkpoints only after database commit

    If a worker crashes mid-batch, re-read from the last confirmed checkpoint rather than dropping events.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingMake upserts idempotent across all consumers

    Replaying a webhook or document state transition multiple times must never duplicate invoice or ledger records.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingAnonymize PII instead of hard deleting audit logs

    When users exercise Right to Erasure, hash identifiers with SHA-256 while preserving tax and financial transactions.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingRun automated CI/CD checks before cloud deploy

    Enforce linting, type checks, and unit tests in GitHub Actions before deploying to AWS EC2 or Azure VMs.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingTriage legacy bugs by cluster patterns

    70% of production issues cluster around uncontrolled async state mutations, missing null checks, or unclosed streams.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingWrite ADRs before implementing database schemas

    Agreeing on entity relationships and boundary contracts upfront prevents expensive mid-flight architectural rework.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingEstablish automated health checks for zero-downtime reloads

    PM2 clusters must verify the `/health` endpoint before terminating previous worker processes.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingScope audit logs to the tenant and actor

    Record who modified an employee salary or approved a proposal with immutable timestamp and IP tracking.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingEnforce dynamic entitlement guards per subscription tier

    Check whether a client organization subscribes to HR Advisory, Software, or Hybrid before granting feature execution.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingDeliver instant shells with Next.js Suspense

    Wrap URL params inside Suspense boundaries to allow instant client prefetching across dynamic routes.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingCalibrate appraisals across normalized KPI bands

    Self-appraisals and manager reviews must feed into HR executive normalization before salary revisions trigger.

    Read the deep diveLink to this note

  • Enterprise SaaS and BillingBuild with AI agents anchored to verified context

    Constrain autonomous agents with architecture registers, strict type checks, and automated regression suites.

    Read the deep diveLink to this note

  • Integrations and paymentsVerify the signature of every webhook

    HMAC over the raw body. Reject and log failures, never process them silently.

    Read the deep diveLink to this note

  • Integrations and paymentsUse the provider's event id as an idempotency key

    Store processed ids. A repeated delivery then does nothing.

    Link to this note

  • Integrations and paymentsSend idempotency keys when you create things

    A retried create cannot charge or book twice.

    Link to this note

  • Integrations and paymentsStore provider ids, never card or bank numbers

    Customer, mandate and payment ids are enough to operate.

    Link to this note

  • Integrations and paymentsGate business actions on the real state

    A proposal waits for an active mandate. Enforce it on the server.

    Link to this note

  • Integrations and paymentsReconcile with the provider regularly

    A job compares your records with theirs and reports differences before finance does.

    Link to this note

  • Integrations and paymentsReproduce an integration failure with a direct request

    A 403 might be an account setting. A one-minute request proves it before you change code.

    Link to this note

  • Integrations and paymentsPrefer the provider's current API flow

    Legacy redirect flows tend to lose features and webhooks over time. Migrate before you are forced to.

    Link to this note

  • Integrations and paymentsHandle every webhook type you subscribe to

    A handler that is never triggered, or an event with no handler, is a silent gap.

    Link to this note

  • Integrations and paymentsBack off and retry with jitter

    Retries in lockstep become a second outage.

    Link to this note

  • Integrations and paymentsTime-box every outbound call

    A missing timeout is a latent outage. Set connection and read timeouts.

    Link to this note

  • Integrations and paymentsLog the request id from every provider

    Support conversations with a vendor need it.

    Link to this note

  • Integrations and paymentsKeep integration credentials per environment

    Test keys in test, live keys only in production, and never in the repository.

    Link to this note

  • Integrations and paymentsTest with the provider's sandbox and published test data

    Never use real customers or real money to check a flow.

    Link to this note

  • Integrations and paymentsWrap OCR and AI vendors behind the same adapter style

    Switching Google Vision for another engine should not touch the business logic.

    Link to this note

  • Integrations and paymentsPlan for the vendor changing their API

    Pin versions where you can, subscribe to change notices, and keep contract tests.

    Link to this note

  • Frontend and UIServer state belongs in a query cache

    TanStack Query for fetching, caching and syncing. No data fetching inside effects.

    Read the deep diveLink to this note

  • Frontend and UIWrap every query in a typed custom hook

    Hooks give you one place for keys, types and invalidation.

    Link to this note

  • Frontend and UICentralise query keys

    Predictable keys make invalidation after a mutation boring, which is the goal.

    Link to this note

  • Frontend and UIKeep client state tiny

    If it came from the server, it is cached server state. A small store holds only the user, toggles and wizard steps.

    Link to this note

  • Frontend and UIPrefer Zustand for new client state

    A minimal API surface beats a large boilerplate for small stores.

    Link to this note

  • Frontend and UIOwn your components

    Build on accessible primitives with the code in the repository. No library upgrade to fear and no theming fight.

    Link to this note

  • Frontend and UIAvoid heavy component suites in new projects

    They are hard to theme and hard to unlearn. Add one only with a reason.

    Link to this note

  • Frontend and UIShare validation rules with the API

    Zod schemas that mirror the backend DTOs protect the boundary on both sides.

    Link to this note

  • Frontend and UIUse React Hook Form for anything with more than three fields

    Uncontrolled inputs and schema validation keep large forms fast.

    Link to this note

  • Frontend and UIPaginate, search and sort on the server

    A table that can grow must not load everything into the browser.

    Link to this note

  • Frontend and UILoad dashboards per section

    Each tab fetches what it shows, with its own date filter. One slow query must not block the page.

    Link to this note

  • Frontend and UICollapse chatty screens

    Merge calls, then cache. One dashboard dropped from seven calls to two to four.

    Link to this note

  • Frontend and UIDesign loading, empty and error states

    An empty screen is an invitation to act. An error says what happened and how to fix it.

    Link to this note

  • Frontend and UIBuild role-aware screens from the session

    Hiding a button is convenience. The API is the real gate.

    Link to this note

  • Frontend and UIDefine design tokens as CSS custom properties

    Colours, spacing and radii as variables. A missing token should fail loudly, not render an invisible control.

    Link to this note

  • Frontend and UISupport dark mode from day one

    Tokens that swap under a theme attribute are cheap early and painful late.

    Link to this note

  • Frontend and UIRespect reduced motion

    Disable non-essential animation under the user's preference. Motion should answer an action, not decorate a page.

    Link to this note

  • Frontend and UIMake every control keyboard reachable

    Visible focus, logical order and labels. Accessibility is part of the definition of done.

    Link to this note

  • Frontend and UIDesign for every screen from a phone to an ultra-wide monitor

    Fluid gutters, content caps and root-size scaling, tested at the extremes.

    Link to this note

  • Frontend and UIShip static where you can

    Public pages prerender and load fast, even on poor networks.

    Link to this note

  • Frontend and UIUse route groups to separate public and authenticated areas

    The folder structure then mirrors the product.

    Read the deep diveLink to this note

  • Frontend and UILet middleware save a round trip, not enforce security

    It can redirect an expired session, but the API is the boundary.

    Link to this note

  • Frontend and UIPush client components down the tree

    Keep the interactive leaf small. The rest can render on the server.

    Link to this note

  • Frontend and UIRead the docs for the installed framework version

    Conventions change between majors. The repository's version is the truth, not memory.

    Link to this note

  • Frontend and UIDelete dead hooks and helpers

    A permissions hook nobody wires in returns false for everyone. Gate on what the app actually uses.

    Link to this note

  • DevOps and cloudPick the cloud region once and record it

    For residency-bound work the region is a contract term. Everything touching data stays inside it.

    Read the deep diveLink to this note

  • DevOps and cloudDeploy on merge

    A pipeline that deploys every merge keeps releases small, boring and reversible.

    Link to this note

  • DevOps and cloudBlock merges on failed checks

    Lint, types, tests and build are required. A red check is not a suggestion.

    Link to this note

  • DevOps and cloudRun the build as its own step

    The log then shows the real error. Do not redirect it into a file and guess.

    Link to this note

  • DevOps and cloudPin tool versions in pipelines

    A floating CLI or Node version is a surprise waiting for a Friday.

    Link to this note

  • DevOps and cloudCache dependencies in CI

    Faster feedback keeps people running the checks.

    Link to this note

  • DevOps and cloudCreate preview deployments for pull requests

    Reviewers click the change instead of imagining it.

    Link to this note

  • DevOps and cloudUse a branch strategy that fits the team

    Main is production, develop is integration, features are short-lived. Never force-push main.

    Link to this note

  • DevOps and cloudRun migrations in the pipeline

    A deploy step runs them with the production command. Nobody runs them from a laptop.

    Link to this note

  • DevOps and cloudKeep secrets in the platform's store

    Environment secrets or a vault, never the repository. Provide an example file with names only.

    Link to this note

  • DevOps and cloudSeparate configuration per environment

    Including CORS allowlists, callback URLs and feature flags.

    Link to this note

  • DevOps and cloudTerminate TLS at the platform and renew automatically

    Expired certificates are an outage you scheduled yourself.

    Link to this note

  • DevOps and cloudUse containers for APIs with health checks

    A health check that touches the database tells the platform when to restart.

    Link to this note

  • DevOps and cloudUse a VM and process manager for steady sync workers

    A long-running worker behind a reverse proxy can beat a function with timeouts and cold starts.

    Link to this note

  • DevOps and cloudPut Nginx in front of Node when you run it yourself

    TLS, compression, caching and request limits belong at the edge.

    Link to this note

  • DevOps and cloudRestart with PM2, and keep logs rotated

    A process manager gives restarts, clustering and logs. Rotate them so disks do not fill.

    Link to this note

  • DevOps and cloudKeep object storage private

    Use time-limited signed links. A public bucket is an incident waiting to be indexed.

    Link to this note

  • DevOps and cloudPrefix storage by tenant

    Paths come from the token, not the request.

    Link to this note

  • DevOps and cloudMonitor before you launch

    Logs, alerts and a status check should exist before the first user does.

    Link to this note

  • DevOps and cloudBack up, and rehearse the restore

    A backup you have never restored is a hope.

    Link to this note

  • DevOps and cloudWrite the runbook while you remember

    How to deploy, roll back, rotate a secret and read the logs. The next person is probably you in three months.

    Link to this note

  • DevOps and cloudUse infrastructure as code where it pays for itself

    Terraform for the parts you would otherwise click through twice.

    Link to this note

  • DevOps and cloudAvoid broad process kills

    Kill by the port you started. Patterns like 'nest start' match other people's servers.

    Link to this note

  • DevOps and cloudLeave a shared dev server alone

    Use another port and ask before switching.

    Link to this note

  • Testing and qualitySet coverage floors and enforce them

    80 percent overall and 90 percent for authentication. A floor is a conversation starter, not a goal.

    Read the deep diveLink to this note

  • Testing and qualityTest on the real database

    Happy path, validation, 404, 400, 409, soft delete, pagination, foreign keys and rollback.

    Link to this note

  • Testing and qualityUse realistic fixtures for validation

    Dozens of real postcodes, not two synthetic ones. Edge cases are where bugs live.

    Link to this note

  • Testing and qualityTest every endpoint as every role

    Assert status and response shape. A role matrix test is the cheapest access-control audit.

    Link to this note

  • Testing and qualityTest cross-tenant isolation explicitly

    A second tenant should see nothing, and not even learn the record exists.

    Link to this note

  • Testing and qualityAssert that failures leave nothing behind

    A transaction test checks rows and counters after a thrown error.

    Link to this note

  • Testing and qualityRecord the failing baseline first

    Then you can prove you reduced it, and nobody blames you for old failures.

    Link to this note

  • Testing and qualityRewrite broken tests to the current contract

    Never skip or loosen them to get green.

    Link to this note

  • Testing and qualityReplace mock-heavy specs with integration tests

    Cover the same scenarios against real behaviour, then add the gaps.

    Link to this note

  • Testing and qualitySmoke-test in a real browser

    A passing unit test does not prove a screen works. Click the flow a client will click first.

    Link to this note

  • Testing and qualitySearch the whole codebase for other instances of a bug

    The reported file is rarely the only place. Search unscoped first, then narrow.

    Link to this note

  • Testing and qualityLook for duplicated constants in lib folders too

    Hard-coded values hide in helpers as often as in components.

    Link to this note

  • Testing and qualityTreat a green build as necessary, not sufficient

    Ask whether something existing should have been reused, and whether a related workflow is now broken.

    Link to this note

  • Testing and qualityRun broad checks before marking a ticket done

    Eleven tickets marked done and several reopened taught me this the expensive way.

    Read the deep diveLink to this note

  • Testing and qualityRun lint and format only on files you changed

    A repo-wide formatter creates a diff nobody can review.

    Link to this note

  • Testing and qualityGate the whole set behind one verify command

    Schema validation, drift check, audits, lint, types, tests, build. If it is green, it is shippable.

    Link to this note

  • Delivery and leadershipAgree requirements in writing, with priorities

    Numbered, prioritised items agreed before development. It removes most late surprises.

    Read the deep diveLink to this note

  • Delivery and leadershipGive every project the same docs vault

    A standard structure means any engineer, client or agent knows where to look.

    Link to this note

  • Delivery and leadershipUpdate the docs in the same commit as the code

    Docs written later are fiction.

    Link to this note

  • Delivery and leadershipKeep a traceability matrix

    Requirement to ticket to page. It answers 'where is that feature' in a minute.

    Link to this note

  • Delivery and leadershipTurn architectural rules into CI checks

    A rule in a document drifts. A failing build does not.

    Link to this note

  • Delivery and leadershipWrite a rich description on every ticket

    Two to four sentences in the past tense: what was done, for whom, what was resolved, the outcome. Never a bare title.

    Link to this note

  • Delivery and leadershipEstimate with ranges and name the assumptions

    A single number is a promise you cannot keep.

    Link to this note

  • Delivery and leadershipShow working software early

    A preview deployment beats a status meeting.

    Link to this note

  • Delivery and leadershipReport honestly

    What is done, what is risky, what is not yet verified.

    Link to this note

  • Delivery and leadershipReview for correctness, then security, then fit

    Style belongs to the linter.

    Link to this note

  • Delivery and leadershipRun a retro on your own mistakes

    Trace each cause, compare with a better solution, and write the rule down.

    Read the deep diveLink to this note

  • Delivery and leadershipPair on the first task in a new area, then step back

    Ownership grows faster than instruction.

    Link to this note

  • Delivery and leadershipGive people end-to-end ownership of a module

    Including production support. It changes how they design.

    Link to this note

  • Delivery and leadershipSearch before you build

    Grep for the domain nouns across the whole tree. A module that does it may already exist.

    Link to this note

  • Delivery and leadershipPrefer changing the data flow to adding a validation exception

    Conditionals relocate edge cases. Deriving the value closes them.

    Link to this note

  • Delivery and leadershipFlag stale instead of recomputing everything

    A needs-resync flag is cheaper and more predictable than an expensive recompute on every save.

    Link to this note

  • Delivery and leadershipKeep work on the branch the owner names

    Branch hygiene is part of trust.

    Link to this note

  • Delivery and leadershipNever commit secrets, never force-push main

    Check status before staging. These two habits prevent most embarrassing incidents.

    Link to this note

  • AI and agentsGive agents a knowledge vault

    Projects, rules, decisions and a journal in plain files. Better context produces better output.

    Read the deep diveLink to this note

  • AI and agentsGive every repository one entry file

    A single document that routes an agent to the notes it needs, instead of loading everything.

    Link to this note

  • AI and agentsWire the same entry file into every tool

    Claude, Gemini, Copilot and Cursor then share identical context.

    Link to this note

  • AI and agentsSave corrections as rules

    A mistake an agent makes once should not be made twice.

    Link to this note

  • AI and agentsWrite skills for repeatable workflows

    A written procedure turns a fragile prompt into a dependable process.

    Link to this note

  • AI and agentsKeep a human in the loop at the review step

    The agent drafts the timesheet and the tickets. A person approves before anything is submitted.

    Link to this note

  • AI and agentsMake the agent say what it did and did not check

    Verification before claims, always.

    Link to this note

  • AI and agentsShow a dry-run plan before changing configuration

    Tool setup, database writes and secrets all need a visible plan first.

    Link to this note

  • AI and agentsNever let an agent push, or touch main, unprompted

    Commit and push only when asked, on the named branch.

    Link to this note

  • AI and agentsNo AI attribution in commits or pull requests

    The commit identity is the owner's. State it once and enforce it everywhere.

    Link to this note

  • AI and agentsKeep LLM calls on the server

    Keys and tenant data never reach the browser.

    Link to this note

  • AI and agentsReview personal data before sending it to an AI service

    Treat the model provider as a sub-processor and record it.

    Link to this note

  • AI and agentsRun LLM work off the critical path

    Draft agendas, summarise orders and generate documents asynchronously.

    Link to this note

  • AI and agentsUse OCR and vision where it saves typing

    KYC and document flows benefit, with confidence thresholds and a human fallback.

    Link to this note

  • AI and agentsExpose systems to agents through MCP, with limits

    Calendar, mail and ticket access within defined permissions.

    Link to this note

  • AI and agentsSeparate observation, inference and unknowns in analysis

    Evidence with provenance beats confident guesses, for people and for agents.

    Link to this note

  • Privacy and complianceEstablish the lawful basis before collecting data

    Contract, legal obligation, legitimate interests or consent. Document it.

    Read the deep diveLink to this note

  • Privacy and complianceCollect only what you need

    No just-in-case columns. Review every new field against a purpose.

    Link to this note

  • Privacy and complianceKeep a retention table

    Per data type: how long, and why. Financial records six years, audit logs seven, unconverted leads six months.

    Link to this note

  • Privacy and complianceAutomate expiry, or schedule a purge

    A retention period nobody enforces is not a policy.

    Link to this note

  • Privacy and complianceBuild data subject rights as endpoints

    Access, rectification, erasure, portability and objection, within the legal window.

    Link to this note

  • Privacy and complianceShow each role only the data it needs

    Staff see their own data, managers their team, admins their tenant.

    Link to this note

  • Privacy and complianceNever expose sensitive derived data to the wrong role

    Cost rates, margins and notes get their own response classes.

    Link to this note

  • Privacy and complianceStrip personal data from logs

    Ids in logs, details in the database, access controlled.

    Link to this note

  • Privacy and complianceKeep an append-only audit log

    Tenant-scoped, immutable, retained for the required period.

    Link to this note

  • Privacy and complianceRecord sub-processors and what each receives

    Cloud, email, payments and AI vendors, with the data they see.

    Link to this note

  • Privacy and complianceRehearse the breach checklist

    Scope, contain, assess, notify the regulator within 72 hours if high risk, notify people, and write it all down.

    Link to this note