# Docs API design conventions used across syntaqx projects, and the reference for the public syntaqx API. ## API - [API reference](https://www.syntaqx.com/docs/api): interactive reference for the public syntaqx API - [OpenAPI spec](https://www.syntaqx.com/openapi.json): OpenAPI 3.2 document describing every endpoint - [API root](https://api.syntaqx.com): index of endpoint URLs - [Health check](https://api.syntaqx.com/healthz) - [Versioning & deprecation](https://www.syntaqx.com/docs/api-design/versioning): Api-Version header versions, breaking-change rules and Deprecation/Sunset headers ## Start Here - [The Playbook](https://www.syntaqx.com/docs/playbook): How to read the playbook, the principles behind every standard in it, and a map of the whole book, from HTTP fundamentals to leading the team. ## Fundamentals - [REST & HTTP Verbs](https://www.syntaqx.com/docs/fundamentals/rest-http-verbs): What GET, QUERY, POST, PUT, PATCH and DELETE promise to clients, caches and retries, and why breaking those promises causes real outages. - [Time & Date Formats](https://www.syntaqx.com/docs/fundamentals/time): RFC 3339 instants in UTC, local wall-clock times with IANA zones for future events, ISO 8601 durations, and iCalendar rules for anything recurring. - [Identifier Conventions](https://www.syntaqx.com/docs/fundamentals/identifier-conventions): UUID v7 as the default key, when integers, v4, v5 or ULIDs are the better choice, and what each format reveals, costs, and breaks when you get it wrong. - [Addresses & Geocoding](https://www.syntaqx.com/docs/fundamentals/addresses): Capturing, standardizing, validating and geocoding addresses, what vendor licenses let you store, and keeping postal city, service point and jurisdiction apart. - [Phone Numbers & Email Addresses](https://www.syntaqx.com/docs/fundamentals/phones-and-emails): Phone numbers in E.164 via libphonenumber, email accepted broadly and compared with care, ownership proven, and what was typed kept beside every key. - [Text & Unicode](https://www.syntaqx.com/docs/fundamentals/text-and-unicode): UTF-8 everywhere, four ways to measure a string, NFC for storage, case folding, locale-aware collation, confusables, bidi controls and database encodings. ## Product - [Discovery & User Research](https://www.syntaqx.com/docs/product/discovery): Finding problems worth solving before a problem statement: weekly customer contact, interviews about past behavior, assumption tests and small usability tests. - [Problem Statements & Acceptance Criteria](https://www.syntaqx.com/docs/product/problem-statements): Problem statements that set the frame, acceptance criteria that state outcomes and leave room for the solution, and hearing the pain behind a request. - [Backlogs](https://www.syntaqx.com/docs/product/backlogs): One backlog for features, bugs and tech debt, sized to what the team can build, with stale items closed on a schedule and important ideas left to come back. - [Roadmaps & Capacity](https://www.syntaqx.com/docs/product/roadmaps): Roadmaps that commit to problems and outcomes, not dated feature lists, with a fixed share of capacity engineering spends on debt, upgrades and improvements. - [Release Stages](https://www.syntaqx.com/docs/product/release-stages): Internal, alpha, beta and general availability as gates: who gets access at each stage, what each one promises, and what must be true before the next. ## Development - [Decisions & Design Docs](https://www.syntaqx.com/docs/development/design-docs): How much process a decision deserves, a named decider and a date, disagree and commit, and design docs and ADRs that keep the reasoning findable later. - [Repositories & Local Development](https://www.syntaqx.com/docs/development/repositories): One repository per product, trunk-based development with short branches, one command from clone to running, and formatters and linters CI enforces. - [Commits, PRs & Code Review](https://www.syntaqx.com/docs/development/commits-and-reviews): Conventional Commits, small squash-merged pull requests with a real description, and code reviews that are fast, labeled, and focused on what matters. - [Code Ownership](https://www.syntaqx.com/docs/development/code-ownership): Every service and directory has an owning team: CODEOWNERS for reviews, a catalog entry for operations, and a README that gets anyone running in one command. - [Documentation](https://www.syntaqx.com/docs/development/documentation): Docs as code in the repository, reviewed and checked in CI, sorted by Diátaxis, API reference generated from OpenAPI, and every page owned and kept fresh. - [Dependencies & Upgrades](https://www.syntaqx.com/docs/development/dependencies): Lockfiles, SemVer, small continuous upgrades, an LTS runtime policy, vetting new dependencies, and supply-chain safeguards like provenance and pinned CI. - [Build vs Buy & Vendors](https://www.syntaqx.com/docs/development/build-vs-buy): Buy what isn't your differentiator, total cost both ways, vendor evaluation and security review, exit plans, third-party risk, sprawl, open source and renewals. - [Tech Debt](https://www.syntaqx.com/docs/development/tech-debt): Treat tech debt like a loan: know which kind you took on, track the interest you pay, budget a steady share to repay it, and modernize with strangler figs. - [AI-Assisted Development](https://www.syntaqx.com/docs/development/ai-assisted-development): Working with AI coding agents: a person owns every change, review follows measured risk, standards live in the repo, CI enforces them, nothing ships unverified. ## Architecture - [Service Boundaries](https://www.syntaqx.com/docs/architecture/service-boundaries): Where to draw lines in a system: start with a modular monolith, split only for a reason, give every piece of data one owner, and never share a database. - [Retries & Timeouts](https://www.syntaqx.com/docs/architecture/retries-and-timeouts): When to retry, how long to wait, and when to give up: timeouts on every call, exponential backoff with jitter, retry budgets, and what is safe to retry. - [Events & Async Messaging](https://www.syntaqx.com/docs/architecture/events): Publishing and consuming events reliably: the transactional outbox, idempotent consumers, partition keys for ordering, CloudEvents, and schema evolution. - [Background Jobs](https://www.syntaqx.com/docs/architecture/background-jobs): Moving work out of the request: small idempotent jobs, retries with backoff and dead letters, scheduling without overlap, visibility, and shutting down cleanly. - [Application Caching](https://www.syntaqx.com/docs/architecture/application-caching): When a cache earns its place, the patterns for filling and invalidating one, surviving stampedes and cold starts, and what a cache must never be trusted with. - [Realtime Connections](https://www.syntaqx.com/docs/architecture/realtime-connections): Pushing changes to connected clients: an edge and routing tier, auth on connect, heartbeats, fan-out, resume and catch-up, and surviving reconnect storms. - [Waiting Rooms & Admission Control](https://www.syntaqx.com/docs/architecture/admission-control): Admitting users at the rate a system can serve: capacity per scope, queues with ceilings, honest wait estimates, signed admission tokens and fairness. - [Multi-Tenancy](https://www.syntaqx.com/docs/architecture/multi-tenancy): Serving many customers from one system safely: choosing an isolation model, enforcing tenant scope in the database, and keeping noisy neighbors in check. - [Replacing a System](https://www.syntaqx.com/docs/architecture/replacing-systems): Moving off a legacy system or vendor: Strangler Fig, cutover options, crosswalks, suppressed side effects, reconciliation, rollback windows and exit plans. ## Database - [Database Naming Conventions](https://www.syntaqx.com/docs/database/naming-conventions): Naming and typing conventions for tables, columns, keys, constraints and indexes, so a schema is predictable enough to guess and safe to change. - [Transactions & Concurrency](https://www.syntaqx.com/docs/database/transactions-and-concurrency): What isolation levels really guarantee, stopping lost updates with optimistic or pessimistic locking, retrying serialization failures, and avoiding deadlocks. - [Database Performance](https://www.syntaqx.com/docs/database/performance): Measure before you optimize: reading query plans, designing indexes that earn their write cost, catching N+1 queries, pooling connections, and timeouts. - [Zero-Downtime Migrations](https://www.syntaqx.com/docs/database/zero-downtime-migrations): Changing a live schema without downtime: the expand and contract pattern, safe backfills, lock-aware DDL, and the order to ship code and migrations in. - [Effective Dating & History](https://www.syntaqx.com/docs/database/temporal-data): Valid time and recorded time, effective-dated rows and as-of queries in PostgreSQL ranges, versioned plans and prices, snapshots and scheduled changes. ## API Design - [API Design Principles](https://www.syntaqx.com/docs/api-design/principles): The rules every endpoint follows: resources and methods, bare JSON with metadata in headers, status codes that mean something, and a Request-Id on all of it. - [Naming Conventions](https://www.syntaqx.com/docs/api-design/naming-conventions): How API paths are named: plural kebab-case nouns, one level of nesting, IDs not names in URLs, actions as sub-resources, and no formats or versions in paths. - [Relationships & Expansion](https://www.syntaqx.com/docs/api-design/resource-relationships): Links between resources as their own sub-resources (PUT to link, DELETE to unlink), and related objects as IDs unless the client asks to expand them. - [API Authentication](https://www.syntaqx.com/docs/api-design/authentication): How API callers prove who they are: prefixed, hashed API keys, restricted by default, OAuth 2.0 for delegated access, scopes, and 401 vs 403 vs 404. - [Versioning & Deprecation](https://www.syntaqx.com/docs/api-design/versioning): Header-selected, date-named API versions, what counts as a breaking change, and announcing removals on the wire with the Deprecation and Sunset headers. - [Choosing an API Style](https://www.syntaqx.com/docs/api-design/api-styles): REST, GraphQL, gRPC and events: what each one optimizes for, what it costs, and how to pick by who the consumer is rather than by what's fashionable. - [GraphQL in Depth](https://www.syntaqx.com/docs/api-design/graphql): Designing a GraphQL schema that survives years of change: nullability, connections, mutation payloads, N+1, cost limits, authorization, caching and federation. - [SDK Design](https://www.syntaqx.com/docs/api-design/sdk-design): When to ship client libraries, generated versus hand-written, and the behavior every SDK should build in: retries, idempotency, pagination and errors. - [Webhooks](https://www.syntaqx.com/docs/api-design/webhooks): Signed, at-least-once webhook delivery: payload shape, signature verification, retry schedule, and how consumers should dedupe and process events. ## Requests & Responses - [JSON Field Conventions](https://www.syntaqx.com/docs/requests/json-conventions): How fields are named and typed in JSON bodies: snake_case, absent versus null, string enums, boolean prefixes, and safe handling of 64-bit numbers. - [Error Responses](https://www.syntaqx.com/docs/requests/error-responses): One error shape for every failure, status codes that carry the outcome, and the 400 vs 422 and 403 vs 404 calls clients branch on to recover. - [Idempotency](https://www.syntaqx.com/docs/requests/idempotency): Safe retries for any write with the Idempotency-Key header: how keys are stored and replayed, and what happens on conflicting or concurrent requests. - [Pagination](https://www.syntaqx.com/docs/requests/pagination): Cursor pagination by default, page numbers only for small stable lists, metadata in the Link header, and why offsets break on data that keeps changing. - [Filtering & Sorting](https://www.syntaqx.com/docs/requests/filtering-and-sorting): Query parameter conventions for filtering and sorting collections: field filters, range operators, sort=-created_at, allowlists, and when to use QUERY. - [HTTP QUERY](https://www.syntaqx.com/docs/requests/http-query): Supporting RFC 10008's QUERY method today: one query model behind GET, QUERY and a POST fallback, plus caching, CORS, and where the ecosystem still falls short. - [Caching & Conditional Requests](https://www.syntaqx.com/docs/requests/caching): Cache-Control, ETags and conditional requests: cheap revalidation with 304, safe concurrent updates with If-Match and 412, and Vary on Api-Version. - [Rate Limiting](https://www.syntaqx.com/docs/requests/rate-limiting): Why every endpoint is rate limited, what to key limits on, the headers that report them, enforcing them in Redis, and staying up when the limiter fails. - [Long-Running Operations](https://www.syntaqx.com/docs/requests/long-running-operations): Work that outlives a request: 202 Accepted with an operation resource to poll, Retry-After pacing, webhooks on completion, cancellation, and result retention. - [Bulk Operations](https://www.syntaqx.com/docs/requests/bulk-operations): Batch endpoints that create or update many resources in one call: size limits, per-item results, partial failure, idempotency, and when to go async. - [HTTP Compression](https://www.syntaqx.com/docs/requests/http-compression): Accept-Encoding and Vary, gzip, Brotli and zstd trade-offs, precompressed static assets, dictionaries, BREACH, and capping decompressed request bodies. ## Frontend - [Accessibility](https://www.syntaqx.com/docs/frontend/accessibility): WCAG 2.2 AA as the baseline: semantic HTML first, keyboard and focus, contrast, reduced motion, and testing that goes beyond what automated tools can catch. - [Web Performance](https://www.syntaqx.com/docs/frontend/web-performance): Core Web Vitals targets measured from real users, performance budgets enforced in CI, and the handful of habits that keep pages fast: less JavaScript first. - [Design Tokens & Theming](https://www.syntaqx.com/docs/frontend/design-tokens): Named, semantic design tokens as the only source of color, type and spacing, so light and dark themes are one redefinition away and can never drift apart. - [Forms & Validation](https://www.syntaqx.com/docs/frontend/forms): Native inputs first, validation that waits until people are done, server errors mapped onto fields, accessible error messages, and forms that never lose work. - [Error & Empty States](https://www.syntaqx.com/docs/frontend/error-states): Designing every view's loading, empty, error, partial and success states up front, with messages that explain what to do, retries, and no blank pages. - [Internationalization](https://www.syntaqx.com/docs/frontend/internationalization): Building software that can be translated and localized: externalized messages with ICU plurals, Intl formatting, locale choice, RTL layouts, and Unicode traps. - [SEO](https://www.syntaqx.com/docs/frontend/seo): Search engine optimization for engineers: crawling, indexing controls, canonicals, sitemaps, structured data, rendering, redirects, migrations and AI search. - [Link Previews & Social Cards](https://www.syntaqx.com/docs/frontend/link-previews): How a page looks when shared, unfurled or installed: Open Graph, X Cards, each unfurler's rules, oEmbed, generated images, icons, the manifest and theme color. - [Mobile Apps](https://www.syntaqx.com/docs/frontend/mobile-apps): Building iOS and Android apps: native or cross-platform, an API that serves old versions, push, deep links, secure storage, OAuth, store rules and startup. ## Building Blocks - [Audit Trails](https://www.syntaqx.com/docs/building-blocks/audit-trails): Recording who did what, when and why: typed actors, before and after values, same-transaction capture, snapshots, tamper evidence, access logs and exports. - [Data Retention & Deletion](https://www.syntaqx.com/docs/building-blocks/data-retention): How long data is kept and how it is removed: soft vs hard delete, retention windows, GDPR erasure next to append-only financial records, and backups. - [Custom Fields](https://www.syntaqx.com/docs/building-blocks/custom-fields): Per-tenant custom fields: JSONB with a definitions table, validation, indexing, option lists, changing definitions, limits, and exposing them everywhere. - [Rules as Data](https://www.syntaqx.com/docs/building-blocks/rules-as-data): Policies that vary by jurisdiction, channel and date as versioned, sourced data: stages, final checks, precedence, stored deadlines and decision records. - [Workflows & State Machines](https://www.syntaqx.com/docs/building-blocks/workflows): Business processes that outlive a request: explicit states guarded by the database, durable engines vs a jobs table, sagas, timers and human approvals. - [Matching, Merging & Many Sources](https://www.syntaqx.com/docs/building-blocks/record-linkage): Reconciling one real thing reported by many sources: observations, per-field survivorship, crosswalks, match-before-create, reversible merges and overrides. - [Search](https://www.syntaqx.com/docs/building-blocks/search): Product search: Postgres full-text and trigrams first, when to add a search engine, keeping it in sync, relevance, tenant filtering, hybrid search and quality. - [Imports & Exports](https://www.syntaqx.com/docs/building-blocks/imports-and-exports): Spreadsheet import as a product feature: encodings, mapping, row-level errors, dry runs, re-import and undo, plus safe CSV and XLSX exports and portability. - [Third-Party Integrations](https://www.syntaqx.com/docs/building-blocks/integrations): Being a client of other companies' APIs: connections per tenant, OAuth with PKCE, token refresh races, sync with cursors and webhooks, their limits. - [Notifications & Consent](https://www.syntaqx.com/docs/building-blocks/notifications): Sending email, texts and push safely: a consent ledger per contact point and purpose, one outbound gate, send-time re-checks, templates, and the message log. - [File Uploads](https://www.syntaqx.com/docs/building-blocks/file-uploads): Uploads straight to storage on a scoped credential, resumable protocols, checks on what arrived, hostile files, and a gate before a file is usable. - [Media Compression](https://www.syntaqx.com/docs/building-blocks/media-compression): Lossless and lossy coding, the pipeline image and video codecs share, generation loss, formats by content class, perceptual metrics, and what encoding costs. - [Generated Documents](https://www.syntaqx.com/docs/building-blocks/generated-documents): Receipts, invoices, statements and contracts as PDFs: renderers compared, templates as code, background rendering, numbering, PDF/A, PDF/UA and delivery. - [Offline-First Sync](https://www.syntaqx.com/docs/building-blocks/offline-sync): Apps that work without a network: a scoped local store, commands in a device outbox, attachments apart, two clocks, and conflict rules decided per command type. - [Location Tracking & Geofences](https://www.syntaqx.com/docs/building-blocks/location-tracking): Positions with accuracy, mobile sampling limits, geofence arrival with dwell and hysteresis, ETAs, safe tracking links, and consent and retention. - [Reservations & Holds](https://www.syntaqx.com/docs/building-blocks/reservations-and-holds): Selling scarce slots and inventory: holds that expire on read, caps per holder, idempotent confirmation, and a database that refuses double-booking. - [Automated Risk Decisions](https://www.syntaqx.com/docs/building-blocks/risk-scoring): Rules and models that decide about people: score bands with a human middle, decision records, late labels, holdouts, error costs, fail-open or closed, appeals. - [Trust & Safety](https://www.syntaqx.com/docs/building-blocks/trust-and-safety): Moderation for any product where people post, chat or trade: policies, report queues, automated detection with review, penalties, appeals and reporting duties. - [Weighing Competing Objectives](https://www.syntaqx.com/docs/building-blocks/weighing-objectives): Folding many goals into one solver score: levels or weighted sums, hard and soft constraints, money as the unit, integer scaling, replay and explanations. - [LLM Features](https://www.syntaqx.com/docs/building-blocks/llm-features): Summaries, extraction, classification, drafts and answers inside a product: structured outputs, retrieval, evals as tests, latency, cost and fallbacks. - [AI Agents in the Product](https://www.syntaqx.com/docs/building-blocks/ai-agents): Agents that act for customers and operators: narrow tools, typed results, decisions in code, identity checks, handoff, evals, auditing and the law. ## Security - [Threat Modeling](https://www.syntaqx.com/docs/security/threat-modeling): A lightweight threat model for every new service or trust boundary: four questions, a data flow diagram, a STRIDE pass, and mitigations tracked as work. - [Authentication & Sessions](https://www.syntaqx.com/docs/security/authentication): How people sign in and stay signed in: passwords per NIST, passkeys, MFA, recovery, server sessions over browser JWTs, and stopping credential stuffing. - [Choosing an Identity Provider](https://www.syntaqx.com/docs/security/identity-providers): Hosted platforms, self-hosted servers and in-app libraries for sign-in: Auth0, Clerk, WorkOS, Cognito, Keycloak, FusionAuth, Better Auth, and how to choose. - [SSO & Identity Federation](https://www.syntaqx.com/docs/security/sso-and-federation): Signing people in through someone else's identity provider: OIDC with PKCE, validating ID tokens, SAML for enterprises, per-tenant SSO, SCIM and logout. - [Authorization](https://www.syntaqx.com/docs/security/authorization): Deciding what an authenticated caller may do: RBAC, ABAC and relationship-based models, where checks belong, object-level access, and testing deny-by-default. - [API Security](https://www.syntaqx.com/docs/security/api-security): The OWASP API Security Top 10 (2023), risk by risk, and the playbook practice that prevents each one, so security is designed in rather than bolted on. - [Security Headers & CSP](https://www.syntaqx.com/docs/security/security-headers): The response headers every site should send, a strict Content Security Policy, and how to roll CSP out safely with Report-Only mode before enforcing it. - [Sensitive Data](https://www.syntaqx.com/docs/security/sensitive-data): Handling card data and PII: keep PCI scope small with tokenization, never log secrets, redact by default, and treat access to sensitive data as an event. - [Encryption at Rest](https://www.syntaqx.com/docs/security/encryption-at-rest): Disk, database and field encryption and what each stops: envelope encryption, KMS or HSM, rotation jobs, crypto-shredding, blind indexes and key-use logs. - [Support Access & Internal Tools](https://www.syntaqx.com/docs/security/support-access): How staff reach customer data safely: delegation over impersonation, read-only by default, reasons, banners, time limits, approvals and internal consoles. - [Infrastructure & Employee Access](https://www.syntaqx.com/docs/security/infrastructure-access): How engineers reach production: SSO for every tool, zero trust over VPNs, device posture, cloud roles, short-lived credentials, just-in-time and break-glass. - [Vulnerability Management](https://www.syntaqx.com/docs/security/vulnerability-management): Finding and fixing vulnerabilities faster than they're exploited: remediation targets by risk, CVSS with EPSS and KEV, SBOMs, and patching by redeploying. - [Securing Software Updates](https://www.syntaqx.com/docs/security/software-updates): An updater that survives a hostile network: TUF's threat model, keys split by role, signed monotonic manifests, verified chunks and deltas, and staged rollout. - [AI & LLM Security](https://www.syntaqx.com/docs/security/ai-security): Building with LLMs and agents safely: the OWASP Top 10 for LLM Applications, why prompt injection is unsolved, and designing so it can't do damage. ## Money - [Money & Amounts](https://www.syntaqx.com/docs/money/amounts): How monetary amounts are represented: integer minor units, an explicit ISO 4217 currency on every amount, and rounding rules that never lose a cent. - [Payment States & Ledgers](https://www.syntaqx.com/docs/money/payment-states): Explicit state machines for financial objects, append-only records, and a double-entry ledger, so every balance can be explained and nothing is ever edited. - [Multi-Currency & FX](https://www.syntaqx.com/docs/money/multi-currency): Charging in one currency and settling in another: who takes the FX risk, locking a quoted rate, storing both amounts, refunds, and checkout conversion. - [Subscriptions & Recurring Billing](https://www.syntaqx.com/docs/money/subscriptions): Subscription states, billing periods and anchors, idempotent renewals, proration, dunning, cancellation, and the automatic renewal laws that govern all of it. - [Usage-Based Billing & Metering](https://www.syntaqx.com/docs/money/usage-based-billing): Metering events, aggregation and rating, late events and period close, credits and commitments as a ledger, spend alerts, invoice evidence, and engines. - [Sales Tax & VAT](https://www.syntaqx.com/docs/money/sales-tax): Indirect tax as data: a tax code per item, tax as a quote until the invoice finalizes, engines, exemptions, sourcing, US nexus and VAT on digital sales. - [Accounting & Revenue Recognition](https://www.syntaqx.com/docs/money/accounting): What the product owes the books: deferred revenue as ledger facts, ASC 606 and IFRS 15 basics, breakage, accounting sync, month-end close and write-offs. ## Compliance - [PCI DSS](https://www.syntaqx.com/docs/compliance/pci-dss): What PCI DSS v4.0.1 demands of engineering: merchant and service provider levels, which SAQ or assessment you land on, and shrinking scope. - [SOC 2](https://www.syntaqx.com/docs/compliance/soc-2): SOC 2 as an engineer meets it: the Trust Services Criteria, Type 1 versus Type 2, and how reviews, pipelines and on-call become the evidence auditors test. - [GDPR & Privacy](https://www.syntaqx.com/docs/compliance/gdpr): GDPR as a design constraint: lawful bases, controllers and processors, data subject rights, transfers, 72-hour breach notice, and how each maps onto a system. - [HIPAA](https://www.syntaqx.com/docs/compliance/hipaa): HIPAA for engineers: covered entities and business associates, the BAA chain, what the Security Rule asks of a system, breach deadlines, and de-identification. - [Calls, Texts & Email](https://www.syntaqx.com/docs/compliance/consumer-contact): The law behind contacting customers: TCPA consent and revocation, calling hours, AI voices and disclosure, call recording, CTIA texting rules and CAN-SPAM. - [Electronic Signatures & Records](https://www.syntaqx.com/docs/compliance/electronic-signatures): E-signatures for engineers: ESIGN and UETA, consumer consent, embedded or remote signing, signing evidence, versioned click-through terms and retention. - [Children's Privacy & Age Assurance](https://www.syntaqx.com/docs/compliance/childrens-privacy): Building for children: COPPA and its 2025 amendments, parental consent, the UK Children's Code, age assurance, state app-store laws and data minimization. - [Open-Source Licenses](https://www.syntaqx.com/docs/compliance/open-source-licenses): License families and what triggers them in SaaS and shipped software, SPDX, scanning in CI, an allow and deny policy, attribution, CLAs, and deal diligence. ## Quality - [Quality Strategy](https://www.syntaqx.com/docs/quality/strategy): What quality means, why it's the whole team's job and not a gate, what quality engineers are for, shift-left and shift-right, and risk-based test depth. - [Testing Strategy](https://www.syntaqx.com/docs/quality/testing): The test pyramid and why it has that shape, what each test type covers, real databases over mocks, deterministic fixtures, and zero tolerance for flaky tests. - [Automated Testing](https://www.syntaqx.com/docs/quality/automated-testing): Choosing test tools, end-to-end tests that survive redesigns, page objects vs helpers, property and snapshot tests, suite speed, and failure artifacts. - [Manual & Exploratory Testing](https://www.syntaqx.com/docs/quality/exploratory-testing): What people catch that scripts can't, chartered exploratory sessions, heuristics, bug bashes, acceptance testing, and when manual work earns a place. - [AI-Assisted Testing](https://www.syntaqx.com/docs/quality/ai-assisted-testing): Agents that drive a real browser to explore, find UI and UX gaps, and write bug reports, and how every confirmed finding becomes an automated test. - [Test Data & Environments](https://www.syntaqx.com/docs/quality/test-data): Where tests run and why shared staging decays, seeding, synthetic data over production copies, third-party sandboxes, isolation, and test accounts in prod. - [Visual & Cross-Platform Testing](https://www.syntaqx.com/docs/quality/cross-platform-testing): A browser and device matrix from real usage with support tiers and version floors, desktop OS differences, device clouds, mobile checks and visual regression. - [Load & Performance Testing](https://www.syntaqx.com/docs/quality/load-testing): Performance budgets tied to SLOs, the test types and when to run each, realistic traffic, capacity headroom, and the measurement trap that hides slow responses. - [Defects & Triage](https://www.syntaqx.com/docs/quality/defects): A good bug report, severity and priority as separate axes, triage that keeps the backlog honest, a regression test for every fix, and escaped-defect reviews. - [Release Readiness](https://www.syntaqx.com/docs/quality/release-readiness): Readiness as pipeline gates, exit criteria by risk tier, when a go/no-go earns its place, the release checklist, the first hour, and when to freeze code. - [Quality Metrics](https://www.syntaqx.com/docs/quality/metrics): Quality metrics worth tracking (change fail rate, escaped defects, flake rate, time to detect), the ones that mislead, and mutation testing. ## Delivery - [CI & Continuous Deployment](https://www.syntaqx.com/docs/delivery/ci-pipelines): Fast, trustworthy CI with parallel jobs and real services, then every merge to main deployed on its own, and what must be true before that is safe. - [Feature Flags & Progressive Rollout](https://www.syntaqx.com/docs/delivery/feature-flags): Separating deploy from release: flag types and lifetimes, OpenFeature for vendor-neutral evaluation, percentage and canary rollouts, kill switches, and cleanup. - [Deployment Strategies](https://www.syntaqx.com/docs/delivery/deployment-strategies): Recreate, rolling, blue-green, canary and dark launches: how each one rolls back, what it costs, and why the database is usually the real constraint. - [Where to Run It](https://www.syntaqx.com/docs/delivery/where-to-run): Choosing compute: a platform first, managed containers next, Kubernetes only with a platform team, and what functions, VMs and metal cost to own in people. - [Containers & Immutable Infrastructure](https://www.syntaqx.com/docs/delivery/containers): Why you rebuild and redeploy the whole artifact instead of maintaining servers, and how to build container images that are small, patched, signed and safe. - [Infrastructure as Code](https://www.syntaqx.com/docs/delivery/infrastructure-as-code): Infrastructure declared in code and changed by review: remote locked state, plan and apply from CI, drift detection, modules, and secrets kept out of state. - [Mobile Releases](https://www.syntaqx.com/docs/delivery/mobile-releases): Shipping mobile apps when you can't roll back: release trains, phased rollouts, flags, minimum versions, health gates, signing, beta tracks and OTA rules. ## Observability - [Observability](https://www.syntaqx.com/docs/observability/overview): Request IDs on every response, the three signals and the IDs that join them, bounded metrics beside wide events, and a map of the Observability section. - [Logs](https://www.syntaqx.com/docs/observability/logs): Structured JSON logs, levels with meaning, trace correlation, the OpenTelemetry logs model and bridges, what never to log, sampling noise, and retention. - [Metrics](https://www.syntaqx.com/docs/observability/metrics): Instrument types, temporality, histograms that aggregate, RED and USE, cardinality and its bill, exemplars, recording rules, and pull versus push. - [Tracing & Sampling](https://www.syntaqx.com/docs/observability/tracing): Spans, kinds, status and attributes, what deserves a span, tracing through queues, batches and webhooks with span links, and head and tail sampling. - [Instrumenting with OpenTelemetry](https://www.syntaqx.com/docs/observability/opentelemetry): API and SDK, zero-code agents and the Kubernetes Operator, resources, failing open, semantic conventions, OTLP, propagation, signal status and GenAI spans. - [Running the OpenTelemetry Collector](https://www.syntaqx.com/docs/observability/collector): Deployment patterns, an annotated agent and gateway config, distributions and ocb, queues and retries, monitoring, securing, and managing a fleet with OpAMP. - [Errors & Profiling](https://www.syntaqx.com/docs/observability/errors-and-profiling): Error tracking with grouping, releases, symbols and PII scrubbing, and continuous profiling from pprof to eBPF and OpenTelemetry's profiles signal. - [Frontend & Synthetic Monitoring](https://www.syntaqx.com/docs/observability/frontend-and-synthetic): Core Web Vitals from real users, traces that start in the browser, synthetic checks from several regions, and health checks that tell Kubernetes the truth. - [Dashboards & Alerts](https://www.syntaqx.com/docs/observability/dashboards-and-alerts): Service dashboards as code with deploy markers, alerts on symptoms and burn rates, routing, runbooks, alert fatigue, silences and testing alerts. ## Operations - [Environments & Configuration](https://www.syntaqx.com/docs/operations/environments): One build everywhere: what each environment is for, config validated at boot, secrets in a manager and never the repo, rotation built in, and who deploys where. - [Kubernetes Operations](https://www.syntaqx.com/docs/operations/kubernetes): Running services on Kubernetes without the classic outages: requests and limits, probes, disruption budgets, graceful shutdown, secrets, GitOps and upgrades. - [SLOs & Error Budgets](https://www.syntaqx.com/docs/operations/slos): Picking SLIs that reflect what users feel, setting SLO targets, spending error budgets deliberately, and alerting on burn rate instead of raw thresholds. - [On-Call & Runbooks](https://www.syntaqx.com/docs/operations/on-call): A sustainable on-call rotation: who carries the pager, paging and escalation, written handoffs, a runbook for every alert, and time budgeted to drive toil down. - [Incidents & Postmortems](https://www.syntaqx.com/docs/operations/incident-response): Running an incident: declare early, a commander who doesn't debug, mitigate before diagnosing, update on a clock, then a blameless postmortem that sticks. - [Disaster Recovery](https://www.syntaqx.com/docs/operations/disaster-recovery): Recovery targets set from business impact, backups you've actually restored, the four DR strategies and their cost, and infrastructure rebuilt from code. - [Cost & FinOps](https://www.syntaqx.com/docs/operations/cost-and-finops): Cloud cost as an engineering input: unit economics, an owner for every dollar, budgets and anomaly alerts, the few levers that matter, and free-tier cliffs. - [Customer Support Operations](https://www.syntaqx.com/docs/operations/customer-support): Running support as a system: channels, tickets with states and context, classify and route, macros, bots that hand off, escalation, metrics and QA. ## Telemetry & Analytics - [Event Design & Instrumentation](https://www.syntaqx.com/docs/telemetry/event-design): What to track and why: questions before events, object_action names, properties and context, versioned schemas, tracking plans as code, and identity stitching. - [Collecting Events](https://www.syntaqx.com/docs/telemetry/collection): Getting events from devices and servers to the warehouse: batching SDKs, retries with event IDs, two clocks, sampling, page lifecycle, CDPs, late data and cost. - [Consent & Privacy in Telemetry](https://www.syntaqx.com/docs/telemetry/consent-and-privacy): Analytics within the rules: consent before device storage, gating SDKs, opt-out signals like GPC, minors, minimizing, pseudonymous IDs, retention and deletion. - [Product Analytics](https://www.syntaqx.com/docs/telemetry/product-analytics): What product analytics answers and how: funnels, cohorts and retention curves, active users and stickiness, segments, attribution, north stars and pitfalls. - [Experimentation & A/B Testing](https://www.syntaqx.com/docs/telemetry/experimentation): Running A/B tests you can trust: units and hashing, sample size, peeking and sequential tests, sample ratio checks, guardrails, CUPED, interference and ethics. ## Data Platforms - [Separating Production from Analytics](https://www.syntaqx.com/docs/data/separating-production-and-analytics): Why analysts never query production primaries, where read replicas stop helping, and how CDC, events, contracts and reverse ETL cross the boundary safely. - [Warehouses, Lakes & Lakehouses](https://www.syntaqx.com/docs/data/warehouses-and-lakes): From Hadoop to cloud warehouses and open table formats: what Iceberg, Delta Lake and Hudi each provide, Parquet and ORC, and how I choose where data lives. - [Running a Cloud Warehouse](https://www.syntaqx.com/docs/data/cloud-warehouses): Operating Snowflake, BigQuery and Redshift: how each bills compute, workload isolation, table layout, caches, loading, recovery windows, spend and sharing. - [Real-Time Analytical Databases](https://www.syntaqx.com/docs/data/analytical-databases): ClickHouse, Druid, Pinot, StarRocks and DuckDB: how columnar storage and vectorized execution work, where real-time OLAP beats a warehouse, and update costs. - [Streaming & Event Processing](https://www.syntaqx.com/docs/data/streaming): Logs, partitions and consumer groups in Kafka, Kinesis, Pulsar and Redpanda; event time, windows, watermarks, state and exactly-once in Flink and Spark. - [Data Pipelines & Analytics](https://www.syntaqx.com/docs/data/data-pipelines): Moving production data into analytics without breaking either: CDC, ELT, tested transformations, replayable pipelines, contracts and one definition per metric. - [Modeling Analytical Data](https://www.syntaqx.com/docs/data/data-modeling): Shaping warehouse data people can trust: grain, facts and dimensions, conformed dimensions, slowly changing history, dbt layers, semantic layers and tests. - [Data Science & ML Platforms](https://www.syntaqx.com/docs/data/data-science-platforms): Running data science without breaking production: notebooks, reproducibility, feature stores and skew, experiment tracking, model registries, serving and drift. - [Data Governance & Access](https://www.syntaqx.com/docs/data/data-governance): Knowing what data you hold and who can see it: owners, catalogs and lineage, PII tags, masking and row-level security, quality contracts, erasure and cost. ## Leadership - [Hiring & Interviews](https://www.syntaqx.com/docs/leadership/hiring): Hiring engineers on evidence: define the bar first, structured interviews with rubrics, work samples over puzzles, and independent feedback before debriefs. - [Onboarding](https://www.syntaqx.com/docs/leadership/onboarding): Getting a new engineer to a merged change in week one: access ready on day one, a buddy, a written 30/60/90 plan, real starter tasks, and on-call by stages. - [1:1s & Feedback](https://www.syntaqx.com/docs/leadership/one-on-ones): Running 1:1s that belong to the report, giving feedback that's specific and timely with situation, behavior and impact, and having the hard conversations early. - [Career Ladders](https://www.syntaqx.com/docs/leadership/career-ladders): Written levels described by scope and impact, equal IC and management tracks, staff and principal archetypes, and promotions that recognize sustained work. - [Performance Reviews](https://www.syntaqx.com/docs/leadership/performance-reviews): Performance reviews with no surprises: continuous feedback, evidence against the ladder, calibration that checks bias, and humane handling of underperformance. - [Team Structure](https://www.syntaqx.com/docs/leadership/team-structure): Designing teams on purpose: Conway's law, stream-aligned teams that own services end to end, platforms run as products, and cognitive load as the sizing limit. - [Growing Managers](https://www.syntaqx.com/docs/leadership/growing-managers): Growing engineering managers: management as a career change, not a promotion, a new manager's first 90 days, coaching managers, and the way back to IC. - [Communication & Meetings](https://www.syntaqx.com/docs/leadership/communication): Written by default, async first, meetings that earn their place, decision logs, status updates that lead with the ask, chat norms and working across time zones. - [Measuring Engineering](https://www.syntaqx.com/docs/leadership/measuring-engineering): Engineering metrics that improve the system, not rank people: DORA, SPACE and DevEx, developer surveys, PR flow, and measuring AI-assisted work honestly.