~/study/architect-guidanceReviewed

Software Architect Guidance

Turn the systems you already understand into decisions other people can review, challenge, and build on.

Reading map

Evidence before another technology

Use what you have built

Begin with one familiar system: an approval workflow, an editor, a notification service, a capture pipeline, or a mobile shell.

Architecture practice means making constraints, alternatives, consequences, and verification visible; adding a new framework is only useful when it addresses a real constraint.

This is a public learning guide, not a personal performance assessment or a universal promotion rubric.

Scope is contextual; judgment is observable

The role and the evidence

Staff and Principal titles vary between organizations; assess the scope of decisions, collaboration, and outcomes rather than assuming a title has a fixed meaning.[1]

Will Larson describes four recurring archetypes: Tech Lead, Architect, Solver, and Right Hand; use them to discuss the work a team needs rather than as a mandatory career sequence.[1]

Competency → evidence → next exercise
CompetencyEvidence to look forPractice next
Quality attributesA measurable reliability or latency constraintWrite a stimulus, environment, response, and measurement
Trade-off analysisA decision with a defensible rejected alternativeCompare options against the same constraints
Decision writingA reviewed ADRRecord consequences and a revisit trigger
Domain modelingExplicit business invariants and ownershipMap bounded contexts and transaction boundaries
Distributed dataAn explanation of retries and consistencyTrace a duplicate event through the system
API designAn explicit contract and compatibility policySpecify errors, pagination, and idempotency
Frontend platformA shared component with owners and consumersWrite contribution and deprecation rules
SecurityA threat model with trust boundariesTest authorization and failure paths
OperationsA measured SLI and a response runbookExercise one dependency outage
InfrastructureAn IaC change and a recovery procedureReview drift, restore, and rollback
AI systemsA versioned evaluation datasetCompare quality, latency, and cost
InfluenceA design changed through peer feedbackDocument reviewers, disagreement, and adoption

A design document helps communicate a decision, but evidence of influence also includes adoption, feedback, and the operational outcome after rollout.

Read toward a concrete artifact

Build a usable knowledge base

Start with Fundamentals of Software Architecture for vocabulary, MADR for decision records, C4 for system boundaries, and The Staff Engineer’s Path for technical leadership.[4][2][3][5]

Use Designing Data-Intensive Applications as a reference for replication, partitioning, transactions, and streams when your current design raises those questions.[6]

  • Name domain invariants and bounded contexts before choosing service boundaries; a modular monolith can preserve separation without introducing network failure modes.
  • Use quality-attribute scenarios to compare options: identify who triggers an event, the operating conditions, the required response, and how to measure it.
  • Combine a risk review with a context diagram: mark failure points, rank their impact, and assign a mitigation owner.
  • Choose deeper reading on domain-driven design, evolutionary architecture, or team boundaries only when it changes the artifact you are writing.

Model state, boundaries, and ownership

Frontend is an architecture domain

Decisions worth making explicit
SurfaceDecisionVerification
EditorSeparate document state from the DOM; compare contenteditable, ProseMirror, and LexicalSelection, composition input, undo, and audio synchronization
CheckoutModel pending, confirmed, failed, and unknown outcomesDuplicate submits, timeouts, reconciliation, and retry with the same intent
Mobile shellCompare WebView, native UI, and bridge permissionsOrigin checks, identity handoff, and bridge input validation
Capture pipelineCompare Tauri and Electron using platform access and workload constraintsRepeatable throughput, frame loss, CPU use, and backpressure
Shared platformDefine ownership, versioning, and compatibility before orchestrationConsumer upgrade path, accessibility, and rollback

For payment-like actions, a disabled button improves the interface but server-side idempotency and reconciliation determine correctness when the result is uncertain.

Separate server state, shared client state, and local interaction state before choosing a library; neither a state library nor micro-frontends is a universal default.

SSE can deliver server updates while ordinary HTTP requests send commands; choose WebSocket when the interaction and connection requirements justify a bidirectional channel.[11]

Start with the database you actually operate

Make failure part of the design

For a MySQL-backed notification service, write the business change and an outbox row in the same transaction, then let a worker publish committed rows.[7]

A relay can publish twice if it crashes after delivery but before recording completion, so track event identity and make the consumer idempotent.[7]

  • Define row claiming or a lease so concurrent workers do not intentionally process the same work, and recover abandoned claims after a bounded interval.
  • Specify per-entity ordering, retry backoff with jitter, a retry limit, and a dead-letter queue with inspected replay and discard procedures.
  • Scope idempotency keys to the actor and operation, compare a canonical payload hash, reject key reuse with a changed payload, and define expiration and in-progress recovery.
  • For a raw SHA-256 digest in MySQL, BINARY(32) is an example representation; BYTEA is not a MySQL column type.

A direct polling worker does not require another queue; pg-boss requires PostgreSQL, while the Redis backend of BullMQ adds Redis, so choose those dependencies deliberately.[9][8][17]

Compare choreography with orchestration when a workflow spans services, and include compensation, partial failure, and operational ownership in the comparison.

Use expand-contract migrations with a backfill and a compatibility window, and combine dependency timeouts with a circuit breaker when repeated failures would otherwise cascade.

Measure before claiming improvement

Security and operations are design inputs

Draw a threat model with assets, trust boundaries, actor permissions, and abuse cases before selecting security controls.

For payment pages, consult PCI DSS script authorization, integrity, and inventory requirements; nonce-based CSP is one control, not a universal substitute for compliance assessment.[12]

Define an SLI population and measurement window before setting an SLO; a proposed latency threshold is a target until real measurements support it.[10]

  • Connect browser measurements, backend traces, and structured logs with request identifiers while redacting credentials and personal data.
  • Write a runbook with symptoms, an owner, mitigation, rollback, and recovery verification, then rehearse a dependency failure.
  • Review infrastructure as code for permission scope, secret handling, drift, backup restoration, cost, and safe deployment rather than rebuilding an existing stack merely to change tools.
  • Treat Kubernetes as an optional deployment exercise, with bounded resources, probes, and external secret handling, rather than proof of seniority.

In this repository, Amplify/CDK infrastructure, limited reader Web Vitals collection, and chat evaluation tooling already exist; their presence alone does not establish deployment coverage or improved production outcomes.

A demo is a starting point

AI systems need evidence too

Begin with the simplest workflow that meets the task, then add routing, parallelization, or agent autonomy only when evaluations justify the additional cost and failure modes.[14]

Compare RAG, long context, and fine-tuning against knowledge freshness, traceability, behavior, latency, and cost instead of treating them as interchangeable upgrades.

Choose one bounded experiment
ExerciseArtifactAcceptance evidence
Domain-document RAGRetrieval, chunking, and source-access decisionsA labeled dataset with answerability, citation accuracy, and retrieval failures
Read-only MCP toolTool contract, identity scope, and audit designAuthorization tests, adversarial output tests, and bounded calls
Chat evaluation loopImmutable prompt and dataset versionsA quality, cost, and latency comparison against the baseline

Use synthetic or explicitly shareable data, enforce permissions in the tool and data layers, and treat retrieved text as untrusted input rather than authority to execute instructions.

Problem → constraint → decision → evidence

Make the reasoning reviewable

A useful design document covers context, goals and non-goals, proposed interfaces and data, alternatives, risks, testing, rollout, rollback, and success criteria.

Use MADR for a focused decision record and C4 context or container diagrams for boundaries, then add a sequence or state diagram only where behavior needs explanation.[2][3]

Five reusable case-study shapes
SystemTrade-off to explainEvidence to include
Approval workflowExplicit routing vs. a general rules engineState transitions, invariants, permission boundaries
NotificationsSynchronous dispatch vs. durable asynchronous deliveryFailure sequence, duplicates, replay, operating cost
Transcript editorDocument model vs. implicit DOM stateComposition input, selection, synchronization tests
Screen captureNative access, portability, and processing costMeasurement method, workload, frame loss, bottleneck
Mobile shellNative capability vs. shared web deliveryBridge trust boundaries, authentication, recovery

Use public or synthetic examples and describe the method without publishing employer schemas, client identifiers, credentials, or private traffic data; a public app does not make its implementation public.

Make assumptions visible before drawing boxes

Practice the explanation

Use RADIO for frontend design: Requirements, Architecture, Data model, Interface, and Optimizations; agree on the interview's scope before selecting the depth of each step.[15]

For backend or full-stack practice, cover requirements, entities, interfaces, data flow, high-level design, and failure analysis without imposing a fixed time budget on every interview.

A repeatable practice rotation
SessionSystemDeep dive
1–2NotificationsDelivery guarantees and dead-letter replay
3–4Collaborative transcript editorConflict resolution, selection, and latency
5–6CheckoutIdempotency and uncertain outcomes
7–8Notification growthCapacity estimates, ordering, and operating cost
9–10Streaming transcriptionBackpressure, disconnects, and vendor failure
11–12Shared frontend migrationOwnership, compatibility, rollout, and rollback

An illustrative workload of 1 million daily users receiving 10 notifications each produces about 116 notifications per second on average; a 10× peak assumption gives about 1,160 per second and must be checked against observed traffic.

Start when you are ready; ship evidence each phase

A sustainable growth roadmap

Use one shared budget of 6 hours per week: 2 hours for writing, 2 hours for targeted reading, 1 hour for implementation, and 1 hour for practice.

The milestones below are suggestions, not delivery promises; narrow or extend a phase when review, access, or real work consumes the available time.

Relative milestones within the same weekly budget
PhaseFocusReviewable output
Weeks 1–2Document a familiar decisionOne ADR and one system context diagram
Months 1–3Publish, review, and reviseOne case study, a risk review, and peer feedback
Months 4–6Deepen one failure-prone pathAn outbox experiment or reliability exercise with measurements
Months 7–12Choose one infrastructure or AI gapA recovery drill or an evaluation-backed demo
Months 13–18Lead a decision with other peopleA reviewed proposal, adoption evidence, and rollout results
Months 19–24Consolidate and teachRevisited decisions, a retrospective, and a talk or article

Choose a certification only when its skills match your work or a verified role requirement; check the provider for current exam names, availability, and fees.

Separate source facts from suggested practice

Sources and verification boundaries

The references below support specific concepts; the exercises, sequence, and completion criteria are editorial recommendations rather than requirements imposed by those sources.

This edition removes personal scoring, application strategy, salary comparisons, speculative release forecasts, and unverified claims about company interview expectations.

Read foundational books alongside practical documentation, and consult the AWS Well-Architected Framework to review operational excellence, security, reliability, performance, cost, and sustainability.[13]

Recheck mutable documentation when implementing a technique, and validate privacy, contracts, and applicable regulation for the actual system rather than treating this guide as a compliance opinion.

  1. [1]Will Larson · Staff archetypes
  2. [2]MADR · Markdown Architectural Decision Records
  3. [3]Simon Brown · C4 model
  4. [4]Richards & Ford · Fundamentals of Software Architecture, 2nd edition
  5. [5]Tanya Reilly · The Staff Engineer’s Path
  6. [6]Kleppmann & Riccomini · Designing Data-Intensive Applications, 2nd edition
  7. [7]AWS · Transactional outbox pattern
  8. [8]MySQL · BINARY and VARBINARY
  9. [9]pg-boss · Introduction
  10. [10]Google SRE Workbook · Implementing SLOs
  11. [11]MDN · Using server-sent events
  12. [12]PCI SSC · Payment Page Security and Preventing E-Skimming
  13. [13]AWS · Well-Architected Framework
  14. [14]Anthropic · Building effective agents
  15. [15]GreatFrontEnd · The RADIO Framework
  16. [16]Neal Ford · Architectural Katas
  17. [17]BullMQ · Introduction and storage backends
↑ Back to top