Header Banner Image
Your
Trusted
Get Fully AWS Funded
Cloud Migration

Architecture / Solution Document Template

(All headings are H2; use H3 only when you really need sub-sections)

  1. Document Meta – Version, authors, date, status

  2. Context – Business need, existing pain points, constraints

  3. Goals & Non-Goals – Measurable outcomes; what’s explicitly out-of-scope

  4. High-Level Architecture – Diagram link + one-paragraph narrative

  5. Component Details

    • Purpose

    • Tech stack & key configs

    • Ownership

  6. Data Flow – Request / event journey, sequence or swim-lane diagram

  7. Deployment Topology – Environments, regions, HA/DR strategy

  8. Non-Functional Requirements – Perf, scalability, availability, security, cost targets

  9. Trade-offs & Alternatives – Shortlist + reasons rejected

  10. Operations – Monitoring, logging, alerting, runbooks, IaC modules

  11. Security & Compliance – AuthZ, secrets, audit, compliance mappings

  12. Risks & Mitigations – Top 3-5 items, likelihood, impact, action

  13. Open Questions – Items awaiting decision / PoC

  14. References – ADR IDs, tickets, repos, external specs

You are a senior solutions architect.  
Generate a Markdown **Architecture / Solution document** with H2 headings that strictly follow the 14-section outline below.  
Keep explanations concise (1–3 short paragraphs per section; tables where noted).  
If a field is missing in the INPUT, write “TBD”.

Outline  
1 Document Meta – Version, Author, Date, Status  
2 Context  
3 Goals & Non-Goals  
4 High-Level Architecture – one-paragraph overview + short diagram alt-text  
5 Component Details – table: Component | Tech | Purpose | Owner  
6 Data Flow – numbered steps  
7 Deployment Topology  
8 Non-Functional Requirements – table: Metric | Target  
9 Trade-offs & Alternatives  
10 Operations – monitoring, logging, IaC refs  
11 Security & Compliance  
12 Risks & Mitigations – table: Risk | Likelihood | Impact | Mitigation  
13 Open Questions  
14 References – ADR IDs, repos, tickets

### INPUT
<paste project summary, constraints, NFR targets, tech choices, owners, etc. here>

Example (condensed) — Real-Time Order Processing on AWS

  1. Meta – v1.0 • 2025-08-06 • Author: A. Architect • Status: Proposed

  1. Context


Current monolith struggles with >1 k orders/min spikes on promo days. Latency >3 s breaches SLA.

  1. Goals / Non-Goals

  • Goals: P95 <300 ms, scale to 10 k orders/min, zero downtime deploys.

  • Non-Goals: Rewrite payment gateway; leave legacy reporting unchanged.

  1. High-Level Architecture

Event-driven microservices on EKS; orders ingress via API GW → Kafka → services; state in Aurora MySQL.

  1. Component Details

Component

Tech

Notes

Owner

API Gateway

AWS APIGW

REST+WebSocket

Platform Team

Order Svc

NestJS, Typescript

idempotent, emits OrderPlaced

App Team

Inventory Svc

Go

Saga participant

App Team

Stream bus

MSK

3 × m5.large brokers

Platform Team

  1. Data Flow


1 . Client POST /orders → API GW
2 . Lambda authorizer → Kafka orders topic
3 . Order Svc validates & writes to Aurora
4 . Publishes order-placed event → Inventory Svc, Email Svc

  1. Deployment Topology

  • EKS: 3 × t3.large in 2 AZs, managed nodegroups

  • Aurora: multi-AZ writer + reader

  • MSK: 3 brokers, 3 AZ replication

  • Terraform modules in infra/eks, infra/msk, etc.

  1. NFRs

Metric

Target

Measure

Availability

99.95 %

per month

P95 latency

<300 ms

Prometheus histo

Cost ceiling

<$12 k/mo

AWS Cost Explorer

  1. Trade-offs & Alternatives

  • SQS vs Kafka – chose Kafka for replay & stream analytics.

  • Aurora vs DynamoDB – txn semantics & SQL reporting favored Aurora.

10. Operations

  • Prometheus + Grafana dashboards (orders_latency, kafka_lag).

  • Loki for logs; Alertmanager routes criticals to OpsGenie.

  • Runbooks in /runbooks/order-svc.md.

11. Security & Compliance

  • All IAM via AWS SSO; least-privilege roles.

  • Secrets in AWS Secrets Mgr, rotated every 30 d.

  • PCI DSS mapping table in annex.

12. Risks & Mitigations

Risk

Likelihood

Impact

Mitigation

Kafka broker loss

M

H

3-AZ + hourly snapshot

Aurora writer fail

L

H

Multi-AZ + auto-failover

13. Open Questions

  • Do we compress Kafka topics?

  • Will feature flags live in LaunchDarkly or custom table?

14. References
ADR-42 “Choose Kafka”, ADR-45 “Use Aurora MySQL” • Jira EPIC-123 • PoC repo git@github.com:dasmeta/order-poc

Use this skeleton as your editable template—swap tech, goals, and numbers as needed.