Technical Design
Technical design activities settle how the system will work: which technologies, what architecture, what data shape, and which decisions would be expensive to undo. They’re direct preparation for writing a design document, because architecture descriptions, technology evaluations, and design reviews are exactly the reasoning such a document asks you to write down and defend.
“Design is not just what it looks like and feels like. Design is how it works.” (Steve Jobs)
Analyze an Existing Codebase
Section titled “Analyze an Existing Codebase”Learn how the code you’re inheriting or contributing to is actually built, tested, and reviewed before you change any of it: a predecessor team’s repository, your partner’s codebase, or an open-source project you contribute to. Two to three hours, once, in your first weeks on the codebase: alone to learn a project, as a team for a formal audit. If your project starts from scratch, run it on an open-source project close to yours instead; the practices you find are the ones to adopt.
- Run it: fresh clone, follow their README or handoff document to a working build and a passing test run, and write down every step that failed or was undocumented.
- Read the process: CONTRIBUTING file, review rules, CI configuration, branch and release conventions, issue templates; for a predecessor team, their handoff document, retrospectives, and risk register.
- Map the state: which tests exist and pass, how old the dependencies are, what the last ten merged changes touched and who reviewed them, where the known debt sits.
- Decide first moves: what you adopt as is, what you change first and why, and what you won’t touch during the project.
A good output is an audit of the codebase you’re inheriting: how it builds, how it’s tested, how a change gets reviewed and released, what is undocumented, and what surprised you, ending with the first three changes you intend to make.
Choose a Storage or Technology
Section titled “Choose a Storage or Technology”Choose a database, storage technology, language, framework, or library by comparing two or three options against criteria your project sets, after running each one. Criteria written down before you compare give you the justification you’ll need when someone later asks why you didn’t pick another option.
- Assess requirements: write down what you need from the technology as criteria (e.g., performance, scalability, ease of use). For storage, add your data’s structure, volume, and usage patterns, and the read/write workload you expect.
- Shortlist options: pick two or three candidates and note each one’s strengths and weaknesses. For storage, compare relational (e.g., MySQL, PostgreSQL) and non-relational databases (e.g., MongoDB, Cassandra), as well as different ways to store data (offline, online, object stores, etc.).
- Run the quick-starts: work through each candidate’s “Quick Start” guide, and note the features that would help with specific concerns in your project.
- Compare: score each option in a comparison matrix against the criteria from the first step, plus how well it integrates with your existing project, its security features, and its community support.
- Decide: pick one and justify it against the project’s goals.
A good output is a comparison matrix of two or three options scored against your criteria, with what running each quick-start taught you and a justification for the one you chose; it maps directly onto the alternatives section of a design document.
Map Your Hard-to-Reverse Decisions
Section titled “Map Your Hard-to-Reverse Decisions”Sort your team’s upcoming decisions into the ones that deserve your attention and the ones that don’t, so you stop spending equal care on a database schema and a button color. Thirty minutes as a team, early in the project.
- List ten decisions: the next ten your team expects to make, written down before you classify any of them.
- Classify each: a hard-to-reverse decision is expensive or impossible to undo; an easy-to-reverse decision is cheap to change once you learn something. Typical hard-to-reverse decisions are database schema, authentication and authorization, deployment topology, data migrations, public API shape, licensing, third-party commitments, and anything touching user data you can’t regenerate. Typical easy-to-reverse decisions are most feature code, UI layout, internal module boundaries, and any library you could swap in a week.
- Assign a validator: for each hard-to-reverse decision, name who checks it and what they check before the team commits.
- Revisit once the project has moved on: which classifications were wrong? Treating an easy-to-reverse decision as hard to reverse costs you time; the opposite error costs you a week on a migration you can’t roll back.
Optionally, run this a second time with an AI agent and set the two outputs side by side, noting where they differ, because the comparison shows what the tool changed; either version can be the one you keep.
A good output is the list of upcoming decisions with the few hard-to-reverse ones marked; if eight of ten landed there, redo the classification.
Describe your Architecture
Section titled “Describe your Architecture”Draw the system your team is about to build, at the level of zoom your project partner can follow, and write one paragraph per box. One to two hours as a team, once at the start, then updated when the architecture changes.
- Pick a notation: a C4 context plus container diagram fits most projects; use 4+1 views only if your readers have distinct concerns. The Technical Design guide explains the options.
- Identify core components: list the major pieces (frontend, backend, database, external APIs, pipeline stages, data sources, firmware modules).
- Define interactions: show how components communicate (API calls, queues, file formats, data flows) and name the protocol on each edge.
- Mark the risky parts: which component is new to the team, which integration is unproven, and what you’ll spike first.
- State scalability, security, and performance assumptions: one line each, or “not a concern for this project” with the reason.
Optionally, run this a second time with an AI agent and set the two outputs side by side, noting where they differ, because the comparison shows what the tool changed; either version can be the one you keep.
Keep the diagram in your repository docs; it anchors the architecture section of any design document you write.
A good output is a diagram of the architecture and a brief explanation of each component and its role in the system.
Define your Database Schema
Section titled “Define your Database Schema”Design a structured database schema to organize and store your project’s data.
- Identify Entities: List all the key entities (e.g., users, orders, products) relevant to your project.
- Define Relationships: Determine how entities relate to each other (e.g., one-to-many, many-to-many).
- Create Tables and Fields: Design the tables and define attributes (fields) for each entity.
- Normalize Data: Ensure your schema minimizes redundancy through normalization.
- Performance: Index key fields for faster querying and optimize design for scalability.
- Security Measures: Plan data encryption, define access controls, and ensure proper handling of sensitive data (e.g., user passwords).
A good output is your database schema diagram with explanations of the relationships, key tables or objects, and fields. Explain how normalization was used, and which performance and security considerations you plan to implement. A schema configuration file (e.g., SQL query to create the tables) is a plus.
Proof-of-Concept
Section titled “Proof-of-Concept”Build a small-scale prototype or demo to test the feasibility of a specific idea, technology, or approach within your project.
- Define Key Assumptions: Identify the core concept or functionality that needs validation.
- Develop the Prototype: Create a minimal version focusing on the critical feature or technology.
- Test Feasibility: Evaluate the proof-of-concept to ensure the technology or idea works as intended.
A good output is the proof-of-concept itself and a brief write-up on its feasibility, challenges encountered, and potential next steps.
Designing for System Security
Section titled “Designing for System Security”Ensure the system is designed with robust security measures to protect data and user privacy.
- Identify Vulnerabilities: List potential security risks (e.g., data breaches, unauthorized access).
- Implement Best Practices: Plan for security measures such as encryption, authentication, and role-based access control.
- Secure Data: Outline how sensitive data will be protected both in transit and at rest.
- Compliance and Monitoring: Ensure the system meets security standards (e.g., GDPR, HIPAA) and establish regular monitoring for threats.
A good output is a security plan that details risks, countermeasures, and compliance strategies.
Apply the Privacy by Design (PbD) Guidelines
Section titled “Apply the Privacy by Design (PbD) Guidelines”Privacy by Design is a systems engineering approach developed by Ann Cavoukian, former Information & Privacy Commissioner of Ontario.
The seven foundational principles are:
- Proactive not reactive; preventive not remedial
- Privacy as the default setting
- Privacy embedded into Design
- Full functionality: positive-sum, not zero-sum
- End-to-end security: full lifecycle protection
- Visibility and transparency: keep it open
- Respect for user privacy: keep it user-centric
Read the principles in detail, then write a report that explains how your software implements each one, or what needs to be done to get there.
A good output is your project assessed against the seven principles, naming which already hold, which you’ll implement, and which don’t apply and why.
Optimizing System Performance
Section titled “Optimizing System Performance”Identify and address factors that influence system performance to ensure optimal operation under different loads.
- Define Performance Metrics: Identify key metrics like response time, throughput, and latency.
- Plan for Load Handling: Evaluate how the system will handle different levels of traffic (e.g., stress testing, load balancing).
- Optimize Code and Queries: Identify areas for improving efficiency (e.g., database indexing, caching).
- Monitoring and Scaling: Plan for performance monitoring tools and strategies for scaling.
A good output is a performance plan with identified bottlenecks and optimization strategies.
Peer Technical Design Review
Section titled “Peer Technical Design Review”Present your technical design document to another team, collect their written answers to five review questions, and log what you’ll do about each. The exchange is a rehearsal for a formal design review; the presentations guide covers what one is for. About 75 minutes for two or three teams in one room or on one call.
- Present: 10 minutes per team. Introduce the project first: the problem it solves, who it’s for, and what it runs in or connects to. Then walk the others through your design document, starting with the decision you’re least sure of, and answer their questions without defending the design yet.
- Review: 25 minutes, every team at once. Read the other team’s document (with three teams, the next team’s) and answer each question below in writing, naming the section each answer is about. Hand the answers over.
- Log: 20 minutes. Write each point the answers make as a comment, and give each a priority, 1 being the change you make first, or mark it declined with a one-line reason.
As a reviewer, answer these about the other team’s document:
- Could someone who hasn’t read the code follow how the system works from this document alone? Where did you get lost?
- Are the diagrams kept where they change with the document? Which part of the design needs a diagram it doesn’t have?
- Does the design solve the problem the team presented? Is a credible alternative missing for the decision the team is least sure of?
- What would break if the assumption the design rests on most changed?
- What single change would you make first?
If you have no design document yet, spend 20 minutes first on one page: the components, how they connect, what each is built with, and the decision you’re least sure of.
A good output is a log of the comments your design document received, each given a priority or declined with a reason.
Read a Book on Approaches to Software Design
Section titled “Read a Book on Approaches to Software Design”Take a look at a book about software design, and discuss in the context of your project. One good approach is that each team member skims several chapters, so that collectively you’ve examined the entire book. The books listed here are a starting point; you might find other interesting books worth reading.
Write up what you learned and how you’ll apply it to your project.
- Clean Architecture by Robert C. Martin
- Release It!: Design and Deploy Production-Ready Software by Michael T. Nygard
- A Philosophy of Software Design by John Ousterhout
- Software Design Decoded: 66 Ways Experts Think by Marian Petre and André van der Hoek
- Software Designers in Action: A Human-Centric Look at Design Work by Marian Petre and André van der Hoek
- Designing Secure Software: A Guide for Developers by Loren Kohnfelder
A good output is a written summary of what the team learned and the specific design decisions in your project it will change.