**Scalable Server-Side Architecture — designing robust, performant services for modern applications.** The backend is where business logic lives, where state is owned, and where every promise made to a frontend or partner is either kept or broken. This page describes how we approach API design, backend stack selection, and the operational properties that make services trustworthy at scale.
The backend is two architectural concerns wearing one name. The API is the contract — what consumers can do, what they can't, what they get when they ask, what they get when something fails. The backend is the implementation — the language, the framework, the data access, the integrations that fulfil the contract. Conflating them produces APIs whose shape was decided by the database schema, frameworks chosen by familiarity rather than fit, and a contract that breaks every time the implementation evolves.
Treating them separately — designing the API as a product whose lifecycle outlasts any backend implementation, choosing the stack as an engineering decision with five-year consequences — produces services that consumers can rely on and teams can evolve. Java/Spring, Node.js, Python, Go, .NET each have their place; the discipline is matching the choice to the workload, the team, and the integration profile.
Consumers — internal teams, external partners, mobile apps that ship to app stores — couple to API contracts. A breaking change in the contract requires every consumer to follow, which means the API's design quality and evolution discipline determine the speed at which the system as a whole can move. Treating the API as a first-class product with an owner, a contract, a versioning policy, and a deprecation cycle is what separates services that survive five years from services that everyone has to coordinate around forever.
OpenAPI Specification — the de facto standard for describing REST APIs in machine-readable form, enabling contract-first design and automated tooling across the lifecycle.
Java/Spring, Node.js, Python, Go, and .NET each have engineering trade-offs (concurrency model, ecosystem maturity, performance ceiling, library breadth). They also have organisational consequences — the talent market in your region, the salaries those engineers command, the tools they expect, the patterns they bring. Picking a stack on technical merit alone, without weighing the hiring and operational consequences, leaves the architecture defensible on paper but undeliverable in practice. The right stack is the one where the technical fit and the team profile align.
Stack Overflow Developer Survey — annual global telemetry on language adoption, satisfaction, and salary that informs hiring-market decisions.
A stateless service can be replicated, load-balanced, and replaced trivially because every instance is interchangeable. A stateful service has identity — instance N holds state instance M does not — and scaling it requires partitioning, replication, leader election, and a coordination story that is itself complex. The architectural pattern is to push state outward: into databases, caches, queues, and explicit stateful components designed for the property. The application services that orchestrate the work are stateless, and that statelessness is what enables them to scale horizontally without architectural drama.
The Twelve-Factor App — III. Config and VI. Processes — the canonical articulation of stateless, environment-configured services that scale horizontally without coordination.
An API contract — OpenAPI schema, gRPC proto, GraphQL SDL, AsyncAPI specification — is a declarative description of what an API offers and what consumers can rely on. Contract-first design starts with the schema, generates server stubs and client libraries from it, and treats the schema as the source of truth. Code-first design starts with handler code and produces a schema afterward, often via reflection or annotations. The two approaches produce visibly similar artefacts but very different evolutionary properties: contract-first APIs are reviewed before implementation, validated against versioned consumers in CI, and surfaced as documentation that is authoritative because it generated the implementation. Code-first APIs are reviewed at PR time, drift from documentation by the second commit, and produce schemas that are accurate today and stale tomorrow.
OpenAPI Specification — the canonical schema language for HTTP APIs that makes contract-first design practical. gRPC and GraphQL provide the equivalents for binary RPC and graph-traversal APIs respectively, with the same contract-first discipline applied to their respective transports.
The first time a team needs observability is during an incident, which is the worst time to discover the logs are unstructured, the traces are missing, the metrics don't include the dimensions the question requires. Wiring observability into services from the first commit — structured logging with request correlation, distributed traces across service boundaries, metrics with the right cardinality, semantic conventions for fields — is what turns "I think it's slow" into "the p99 of the auth endpoint regressed 3 days ago after deployment v2.4.1." The cost of doing this from day one is small; the cost of retrofitting it is enormous.
OpenTelemetry — the CNCF standard for distributed tracing, logs, and metrics with instrumentation libraries across every major language and framework.
Authentication at the edge, authorisation at the service, input validation at the handler, rate limiting at the gateway, secrets management at the runtime, audit logging at the data layer — each is a separate concern with its own threat model and its own enforcement point. Treating security as "we have an API gateway with auth" leaves every layer below the gateway depending on the gateway being correct, present, and not bypassed. Layered defence — where every component validates its inputs and authorises its callers — is what makes the system resilient to single-point failures in the security architecture.
OWASP API Security Top 10 — the canonical industry catalogue of API-specific security risks, with practical guidance for each.
The diagram below shows the canonical backend topology: an API gateway handling edge concerns (authn, rate limiting, TLS); stateless service tiers behind the gateway with internal authn/authz; a backing-services layer (databases, caches, message brokers) holding state; observability instrumentation as a cross-cutting concern; secrets management and IAM as distinct services.
The API shape mirrors the database schema, exposing internal structure to consumers. Database refactors become breaking API changes; API consumers learn implementation details that should have been hidden.
API contracts are designed for consumer needs and use cases. The database schema is an implementation detail; consumers see resources and operations matched to their workflow, not tables and joins.
Picking the same stack for every service because that's what the team knows. When a workload genuinely requires different characteristics (high I/O concurrency, ML serving, cryptographic performance), the wrong stack is paid for in operational complexity and engineering effort over years.
Match the stack to the workload, with explicit polyglot boundaries. The default is one stack for most things; the exceptions are deliberate and documented, not accidental.
State held in application servers, with sticky load-balancer sessions to keep clients pinned to the same instance. Scaling horizontally becomes impossible because new instances can't serve in-flight sessions; deployment becomes painful because every restart sheds state.
Statelessness with explicit external state. Sessions in Redis, in-flight context in queues, durable state in databases. Application instances are interchangeable; deployment is routine.
A dedicated "observability sprint" added when the SLO conversation starts. The instrumentation is partial, the dimensions miss the questions that matter, and the team's instinct is to instrument by reaction rather than by design.
Observability is part of every service from the first commit. Logging conventions, trace propagation, and metric naming are standard library calls — not optional decoration.
The API gateway enforces authentication; everything behind it implicitly trusts the caller. A misconfigured gateway, a compromised internal service, or a misused service-account token bypasses the entire security model.
Layered authentication and authorisation. Every internal call is authenticated; every authorisation decision happens at the data or operation level it protects, not at the network edge.
Contract-first design forces the integration conversation upstream of code; the resulting API is shaped by consumer needs, not by whichever endpoint was easiest to expose.
Consumers know what to expect; deprecations follow announce-dual-run-sunset; the team's commitment to the contract is what makes external consumers willing to integrate.
The choice is defensible to a CTO joining in two years; polyglot is bounded and deliberate, not accidental; migration plans exist for stacks the team commits to.
Sessions, in-flight transactions, and conversation context live in backing services; instances are interchangeable for deployment, scaling, and replacement.
Consumers know which operations are safe to retry; idempotency keys are first-class contract elements; internal retry handlers assume duplicate delivery.
Logs are JSON; correlation IDs propagate across service boundaries; semantic conventions are consistent across services so cross-service queries actually work.
OpenTelemetry instrumentation is a library default, not an opt-in; traces span the request lifecycle without per-team integration projects.
Service-to-service authn (mTLS, signed tokens) is the norm; authorisation decisions happen at the protected operation, not at the network edge.
Vault or cloud-native KMS; secrets are injected at runtime; rotation is automated; no secrets in committed environment files or container images.
The questions security, compliance, and incident response need answers to are pre-answered by the audit log structure; the schema is treated as a public contract.
Other substantive pages in the library that link here: