What should a tech stack diagram include?
Layers and boundaries
A useful diagram starts with the user-facing layer, such as a web app or mobile client. Next, show the backend services, the databases, and any background workers. Group items by layer so a reader can see the boundaries between the browser, the server, and the data store.
Mark what is hosted where. A diagram that shows the app running on a single server tells a different story than one with separate services for auth, email, and storage. Include third-party services like payment processors or analytics, since they can affect data flow and cost.
Client apps and the platforms they run on. Backend services and APIs. Databases, caches, and queues. External services and where they are hosted.
Keep it readable
Limit the diagram to what a new engineer needs on day one. Extra detail belongs in separate diagrams. Use consistent shapes and colors, and add a legend when the picture uses more than a few symbols.
Date the diagram and note the version it reflects. Stacks change quickly, and an undated picture can mislead new team members about what is running in production today. Store the source file in the repository so it can be updated along with the code.
Common mistakes
- Drawing every internal function instead of the main components.
- Leaving out third-party services that store user data.
