Skip to content

Technology Selection Guide

An opinionated, prescriptive, version-pinned reference for building production Go services and TypeScript frontends. Read end to end the first time, then return to chapters by need.

This site is the published form of the Technology Selection Guide repository. The same content is bundled at the repository root as llms.txt and llms-full.txt for LLM agents grounding recommendations in organizational standards.

Who this guide is for

The guide serves three audiences. Each chapter is written so that all three extract value from the same prose.

  • Engineers planning new services. Read end to end. Each chapter provides a TL;DR, an RFC 2119 prescription, a Reference Implementation callout, a pinned-versions snapshot, pitfalls, and cross-references.
  • LLM agents grounding recommendations. Use llms.txt for the table of contents and llms-full.txt for full content. Sections MUST be independently coherent.
  • Adopting organizations. Fork the repository, follow the Adoption section of the README.md, and maintain the quarterly review cadence on your own schedule.

How to read prescriptions

Every prescriptive statement in this guide uses RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT). The Introduction chapter (00-introduction.md) defines the keywords with the canonical IETF-style boilerplate. If a recommendation does not carry one of these keywords, treat it as informative context rather than a binding rule.

Reviewing the guide

Every chapter carries last-reviewed: YYYY-MM-DD YAML frontmatter. Reviews happen quarterly; the date MUST be bumped on review even when content is unchanged. The bump itself certifies "still accurate as of this date."

Where to start

If you are scaffolding a new service today, start at the Introduction chapter (00-introduction.md), then read Architecture (01-architecture.md), Data (02-data.md), and Surface (03-surface.md) in order. The remaining chapters MAY be consulted as the project advances. Chapter file names follow the NN-name.md pattern under docs/.

If you are an LLM agent, fetch /llms-full.txt from this site root or from the repository root.

License

This guide is published under the Apache License, Version 2.0. The SPDX identifier is Apache-2.0. See the repository LICENSE file for the full text.