Act as a principal software architect. Design an architecture for [SYSTEM OR FEATURE] using [CURRENT STACK AND DEPLOYMENT ENVIRONMENT]. The required user and system behaviors are [FUNCTIONAL REQUIREMENTS]. The non-functional constraints are [SCALE, SLO, SECURITY, COMPLIANCE, AND BUDGET]. Existing systems, data sources, and integration limits are [CURRENT STATE AND CONSTRAINTS]. First, state up to 3 clarifying questions only if one of those required inputs is missing. Otherwise produce a technical design document of 1,200–1,800 words with these exact sections: 1. Scope and explicit non-goals. 2. Assumptions and open questions, each marked by impact. 3. Proposed architecture: components, responsibilities, data ownership, trust boundaries, and request/data flows. Include a Mermaid component diagram and a numbered sequence for the critical path. 4. APIs and events: key endpoints or topics, authentication/authorization, idempotency strategy, versioning, error contracts, and example payloads using fictional data. 5. Data model and lifecycle: source of truth, identifiers, retention/deletion needs, indexes, consistency choice, migrations, and backfill plan. 6. Reliability: timeouts, retries with jitter, dead-letter or recovery path, rate limits, observability, disaster recovery, and behavior when dependencies fail. 7. Security: least privilege, secrets, encryption, audit trail, abuse cases, and PII handling. 8. Trade-offs: compare the chosen approach with two viable alternatives and say why each loses under these constraints. 9. Delivery plan: vertical slices, tests, rollout, feature flags, rollback, and operational ownership. Include concise TypeScript interfaces or pseudocode only where they clarify a contract or a hard edge case; make it runnable-looking but do not pretend it was executed. Do not invent vendor capabilities, internal systems, metrics, or compliance approvals. Before answering, run two self-checks: trace every requirement to a component or an explicit non-goal, and list the three highest-risk failure modes with detection and mitigation. Flag decisions that need security, privacy, platform, or legal review.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [SYSTEM OR FEATURE] | Describe the product capability or system being designed. | a self-service CSV import feature for customer contacts |
| [CURRENT STACK AND DEPLOYMENT ENVIRONMENT] | List languages, frameworks, cloud, data stores, and deployment constraints already in use. | TypeScript, Next.js, Node workers, Postgres, S3-compatible storage, Kubernetes on AWS |
| [FUNCTIONAL REQUIREMENTS] | Provide the required user flows, system behaviors, integrations, and acceptance criteria. | users upload CSV files up to 250 MB, map columns, validate rows, fix errors, and import contacts without duplicates |
| [SCALE, SLO, SECURITY, COMPLIANCE, AND BUDGET] | State expected volume, reliability targets, security needs, regulatory limits, and cost boundaries. | 500 imports per day; 99.9% API availability; tenant isolation; GDPR deletion support; under $2 per large import |
| [CURRENT STATE AND CONSTRAINTS] | Describe legacy systems, data sources, deadlines, team capabilities, and dependencies that shape the design. | contacts are in Postgres; email uniqueness is tenant-scoped; imports must not block the web request; two engineers have six weeks |
How to use
- Paste the prompt with the actual requirements, including constraints that make an elegant design impractical.
- Check that each requirement has an owner component, data owner, and failure behavior.
- Have the security and platform owners review the trust boundaries, permissions, rollback, and retention decisions.
- Follow up with: “Now turn the delivery plan into six engineering tickets with acceptance tests and dependency order.”
Variations
Architecture review
Use when a proposed design already exists.
Review this architecture for [SYSTEM]: [DESIGN OR DIAGRAM]. Assess it against [REQUIREMENTS AND CONSTRAINTS]. Return a severity-ranked table of risks covering correctness, scaling, data consistency, security, operations, and cost. For each, cite the exact design element, explain the failure path, and propose the smallest viable change. Then list the five questions that must be answered before approval. Do not assume missing controls exist.
API contract
Use when teams need an implementation-ready interface.
Design an API contract for [CAPABILITY] used by [CLIENTS]. Constraints: [AUTH, SCALE, DATA RULES, AND COMPATIBILITY NEEDS]. Return endpoint or event definitions, TypeScript request/response types, status and error codes, pagination/filtering semantics, idempotency behavior, authorization matrix, versioning policy, and three edge-case examples. Use fictional values. Flag choices requiring product or security approval; do not fabricate upstream service behavior.
Migration plan
Use when changing a data model or replacing a service.
Create a zero- or low-downtime migration plan from [CURRENT SYSTEM] to [TARGET SYSTEM] for [DATA AND TRAFFIC]. Known constraints: [CONSISTENCY, RETENTION, SCALE, AND DEADLINE]. Return phases, read/write ownership per phase, backfill method, validation queries or checks, dual-write risks, monitoring, rollback criteria, and final cleanup gates. Do not recommend deleting the old path until data correctness and rollback windows are verified.
Tips
- Write the SLO in terms of a measurable user journey, such as “99% of imports complete within 10 minutes,” rather than saying the system must be fast.
- Force a decision on source of truth for each entity; ambiguous ownership creates duplicate updates and difficult incident recovery.
- Ask for idempotency and retry behavior wherever a request can be repeated by a browser, queue, webhook, or operator.
- Treat diagrams as summaries, not evidence: critical paths also need concrete timeout, authorization, and dependency-failure behavior.
FAQ
Can AI choose my architecture for me?
It can surface options and make trade-offs explicit, but the team accountable for security, operations, and product outcomes must make the decision.
Should I ask for code in an architecture prompt?
Ask for small contract examples or tricky-path pseudocode. A full implementation can hide unresolved data ownership or failure-mode decisions.
What inputs matter most?
The critical path, expected volume, reliability target, data sensitivity, current systems, and delivery constraints usually change the recommended design most.