Guidelines
This is a collection of guidelines that we follow to build our projects. It's a living document, so please feel free to contribute to it.
Scopes
Breaking Changes
A breaking change is a cost we impose on every consumer of a package: they must read, understand, and act before they can take any other improvement we ship. That cost is sometimes worth paying. It is never free, and it is far more often avoidable than it first appears.
Feature Flags
Feature flags enable controlled rollout of new features, instant rollback capability, and decoupled deployment from feature activation. Every new feature must implement feature flags as part of our systematic approach to reducing production bugs.
MCP Server with OAuth
This guideline shows how to build a Model Context Protocol (MCP) server that authenticates MCP clients (Claude, Cursor, VS Code) with OAuth 2.1, using only ttoss packages. No external auth framework is required: @ttoss/http-server provides the Koa runtime, @ttoss/http-server-mcp provides both halves of MCP authorization, and @ttoss/auth-core provides the token primitives. Your app keeps its own user model, signing keys, and login UI — ttoss owns only the protocol mechanics.
OAuth Authorization Server — Issuing Tokens for Your Own App
This guideline covers an app acting as an OAuth 2.1 authorization server: it lets clients register, runs the login/consent flow against your existing user model, and issues access and refresh tokens. The spec mechanics (RFC 8414, 7591, 7636, 6749, 9728) live in a runner-agnostic engine — createOAuthHandlers in @ttoss/auth-core — that operates on plain request/response objects, so any runtime can host it. @ttoss/http-server-auth ships the Koa adapter, oauthServer(); an AWS Lambda or GraphQL runner would adapt the same engine. Your app keeps its user model, signing keys, and login UI behind hooks.
OAuth Client — Connecting to Third-Party Providers
This guideline covers an app acting as an OAuth client: it sends a user to a third-party provider (TikTok, Instagram, YouTube, Google, …), receives an access token on their behalf, stores it, and uses it later — including from background jobs where no user is present. It is the inverse of MCP Server with OAuth, where your app is the authorization/resource server that MCP clients authenticate against. Here a remote provider owns the tokens and your app is the one logging in.
RDS PostgreSQL
In this tutorial, we will configure an AWS RDS PostgreSQL cluster.
REST API
This document outlines the guidelines for building REST APIs.
Technical Debt
Technical debt is often viewed solely as a negative consequence of poor engineering. However, at ttoss, we view technical debt as a financial instrument: leverage. When used consciously, it allows us to ship faster and learn earlier. When accumulated unconsciously, it becomes entropy that grinds development to a halt.
Tests
This document outlines the guidelines for writing tests in ttoss packages.