The How is the engine room. It is where the Who, What, and Why are translated into actual systems. And it is about more than diagrams. A good How chapter reads like a story: it introduces the actors, describes the conditions, and shows how each piece fits together.
What you define here
- Component architecture and data flows
- System behaviours and responsibilities
- Integration touchpoints and interface contracts
- Infrastructure responsibilities and constraints
- User-centred workflows and implementation sequencing
- Failure modes, recovery strategies, observability
- Security design baked in from the start
- Core data models and persistence logic
- Performance tuning and cost awareness
Benefits of a strong How
- Enables parallel development
- Builds confidence across technical and non-technical teams
- Reduces costly ambiguity and rework
- Supports onboarding and continuity
- Forms the backbone of test and deployment planning
- Encourages smart use of infrastructure to control operational cost
1. Start with the story
Narrate what happens when a user engages with your system. Follow an actual flow and explain how each part supports that journey.
"When a new consultant logs into the portal via Firebase Auth, their session token is used by the React frontend to retrieve their profile through the API gateway. The gateway, running in Kubernetes, proxies the request to a Go microservice that fetches data from MySQL via GORM. Access is validated against a policy engine before project data is returned."
That is not just a diagram caption. It demonstrates thinking, empathy, and credibility.
2. Architectural overview
A simple context diagram showing entry points, core services, integrations, and the hosting environment:
[ Mobile App (Flutter) ]
|
[ Frontend (React/Next.js) ] --> [ API Gateway ] --> [ Go Microservices ]
|
[ MySQL via GORM ]
|
[ Firebase / Redis / Kafka / 3rd Party APIs ]
Add callouts for ingress, service mesh, container-to-container security, and observability pipelines.
3. Component breakdown
A template we use for each component:
Component: [Name]
Type: [Service | Library | Function | External API]
Tech Stack: [e.g. Go, GORM, MySQL, Docker, K8s, Firebase]
Owner: [Team / Domain]
Responsibility: [What it does and why it matters to the user]
Inputs: [HTTP / gRPC / Event]
Outputs: [Event | DB Update | External call]
Security: [TLS / JWT / OAuth / Policy scope]
Performance: [Caching, timeouts, load control]
Failure Handling: [Retry, fallback, circuit breaker]
4. Data modelling from first principles
Design models around use cases. Start with flows, derive entities, validate against outcomes. Prefer normalisation but allow denormalised views where performance needs it.
For a timesheet system the entities are User, Timesheet, TimesheetEntry, Approval, Project. A minimal GORM example:
type Timesheet struct {
ID uint
UserID uint
Status string
SubmittedAt *time.Time
Entries []TimesheetEntry `gorm:"foreignKey:TimesheetID"`
}
Design relational integrity up front. Embed constraints in the schema. Use field-level encryption where required. Standardise audit fields (created, updated, deleted) across tables. Cache frequently-read objects (sessions, permissions, project metadata) in Redis with clear expiry and a graceful fallback to the database.
5. Security by design
- Auth via Firebase or OAuth2
- Enforce least privilege through roles and scopes
- Separate internal service mesh from public APIs
- TLS everywhere, no exceptions
- Threat model each component
- Security acceptance criteria in story tickets
Infrastructure security tactics:
- Container images scanned (Trivy, Snyk)
- Kubernetes network policies restricting service-to-service traffic
- Secrets injected via K8s secrets or Vault
- SAST and DAST in the CI/CD pipeline
6. Integration contracts
| System | Purpose | Interface | Security | Observability | Fail strategy |
|---|---|---|---|---|---|
| Firebase Auth | Identity | Token issue / verify | OAuth2, HTTPS | Audit logs | Block + alert |
| Notification Service | Email / SMS | gRPC | mTLS | Prometheus metrics | Retry with backoff |
| Stripe | Payments | HTTPS + webhook | Key + IP allowlist | SIEM logs | Dead-letter queue |
7. Performance and cost awareness
Practical patterns we default to:
- Redis in front of MySQL to reduce read load
- A CDN for static assets (React/Next.js bundles)
- GORM preloads to avoid N+1 queries
- Asynchronous queues (Kafka, NATS) for heavy operations
- Rate limiting on user-heavy APIs
Cost tip: use resource limits and horizontal pod autoscaling to prevent over-provisioning. Design endpoints so they do not need compute they are not using.
8. Process flow
Narrate the path a request takes:
- Request starts at Flutter or Next.js
- Auth token checked against Firebase
- Request routed via API gateway to the right service
- Go business logic hits GORM for DB access
- Frequently-used data hits Redis first
- Events emitted to Kafka for async work
- Response returned, observed, logged
Add per-scenario flow diagrams for the critical paths.
9. Failure modes worth planning for
A How that only describes the happy path is a How that will surprise you in production.
Three categories of failure deserve explicit thought during design, not in the retro.
- Transient. The database is briefly unreachable. The third-party API returns a 503. A network partition lasts ninety seconds. Respond with retries, circuit breakers, and idempotent operations. Do not respond with user-facing errors that require support tickets to explain.
- Partial. The payment service is down but the rest of the system is fine. Timesheet submission still works, expense claims still work, payroll export queues up. Design services so they degrade rather than collapse.
- Silent. The worst kind. A job fails but the monitor does not fire. A queue grows unbounded. A cron job stops running six months ago and no one noticed because the downstream impact took a quarter to show up. Counter these with end-to-end synthetic checks, dead-letter queue alerts, and "heartbeat" jobs for anything scheduled.
A good How assigns each component an explicit failure mode table: what does it do when a dependency is slow, when it is down, when it returns unexpected data, when it is under load. Answering those four questions for each service is unglamorous and load-bearing.
10. Design justification table
| Choice | Reason | User impact |
|---|---|---|
| Go + GORM | High performance, strong typing | Faster API, lower latency |
| Flutter | Cross-platform mobile | One codebase, consistent UX |
| MySQL | Reliable relational DB | Solid audit trail and reporting |
| Redis cache | Reduce DB load | Instant data load for common actions |
| Containers in K8s | Scalability, isolation, recovery | Faster deploys, safer updates |
| Firebase Auth | Offloaded identity | Faster onboarding, secure access |
Summary
A good How reads like a guided tour of your solution. Not a spec. A demonstration of engineering empathy. Done well it:
- Builds confidence in stakeholders
- Reduces ambiguity for implementers
- Connects technology to the people who use it
- Optimises for performance without over-engineering
Do not just say what tech you are using. Say why, say how it fits together, and say how it helps the user.
Tech choices worth defending
A quick word on picking technology. The How document is where the team's prejudices show up. The good ones, like preferring boring tech, are worth keeping. The bad ones, like following trends, are worth catching.
Useful tests to apply to any technical choice:
- Who else on the team can operate this? If the answer is "one person", you have picked a bus factor, not a technology.
- How will we hire for this in two years? The hot framework today is the legacy stack tomorrow. Pick things with depth.
- What does failure look like? If the answer starts with "well, in theory", you do not know yet. Find out before production does.
- What is the cost profile at ten times the current load? Scaling is cheap on a napkin and expensive in a bill.
- Can a new engineer be productive in this in a week? If not, every hire costs a month of ramp-up. Multiply that by future headcount to price the choice.
None of this rules out adopting new technology. It does rule out adopting it for aesthetic reasons. The How is where you get to defend the choices. If you cannot defend them on those five dimensions, revisit them.
