# Architecture Decisions with AI Assistance
Architectural decisions shape the future of your codebase. Get them right, and you'll have a flexible, maintainable system. Get them wrong, and you'll spend months refactoring. The good news? AI can be a powerful ally in making these crucial choices—when you use it correctly.
This lesson teaches you how to leverage AI assistance for architectural decisions without falling into common traps like over-reliance on generated suggestions or accepting technically sound but contextually wrong solutions.
## Why Architecture Decisions Are Different
Before diving into AI-assisted techniques, let's understand why architecture decisions require a different approach than feature implementation.
### The Stakes Are Higher
Architectural choices have long-term consequences:
- **Hard to reverse**: Changing your authentication system or database later costs exponentially more
- **Team-wide impact**: Your decisions affect every developer who touches the codebase
- **Performance implications**: Early architectural mistakes can create bottlenecks that plague you for years
- **Security foundations**: Some vulnerabilities stem from fundamental architectural flaws
AI tools excel at generating code, but they can't fully understand your business constraints, team capabilities, or long-term roadmap. That's where you come in.
## The AI-Assisted Architecture Decision Framework
Here's a practical framework for making architecture decisions with AI assistance:
### 1. Define Your Constraints First
Before consulting AI, document your actual constraints. AI can help brainstorm, but you need to anchor the conversation in reality.
```markdown
# Architecture Decision Record (ADR) Template
## Context
- Team size: 4 developers (2 senior, 2 junior)
- Expected scale: 10K users in year 1, 100K in year 2
- Budget: $500/month infrastructure in year 1
- Compliance: HIPAA required
- Existing systems: PostgreSQL database, React frontend
- Team expertise: Strong in Python/Django, learning Go
## Decision Required
Choose real-time communication architecture for patient messaging
## Non-negotiable Requirements
- HIPAA compliant
- Must work with existing auth system
- Mobile app support required
```
Now when you ask AI for suggestions, you can reference these constraints explicitly. This prevents the common mistake of getting technically excellent solutions that don't fit your reality.
### 2. Use AI for Option Generation
AI shines at generating multiple approaches you might not have considered. Here's an effective prompt pattern:
```
I need to choose a real-time communication architecture for a HIPAA-compliant
patient messaging system. Current stack: Django backend, React frontend, PostgreSQL.
Constraints:
- Team of 4 (strong Python, learning Go)
- Budget: $500/month infrastructure
- Scale: 10K users year 1, 100K year 2
- Must integrate with existing Django auth
Generate 4 different architectural approaches, ranging from simplest to most
scalable. For each, provide:
1. Technology stack
2. Estimated complexity (1-10)
3. Monthly cost estimate
4. Scaling characteristics
5. HIPAA compliance considerations
```
This structured prompt prevents AI from jumping to a single "best" solution without exploring the design space.
### 3. Pressure-Test AI Suggestions
AI-generated architectures often look great on paper but have hidden issues. Here's how to validate them:
#### Ask About Failure Modes
```
For the WebSocket approach you suggested:
1. What happens when the WebSocket server crashes?
2. How do we handle message delivery guarantees?
3. What's our strategy if we hit connection limits?
4. How does this behave under network partitions?
5. What monitoring is essential?
```
AI responses to these questions reveal whether the suggested architecture is robust or naive.
#### Request Migration Paths
```
For each architecture option, describe:
1. How we'd migrate from our current polling-based system
2. Whether we can do a gradual rollout
3. How to roll back if problems occur
4. What data migration is required
```
If AI can't provide clear migration paths, the architecture might be more theoretical than practical.
#### Explore Edge Cases
```
What happens in this WebSocket architecture when:
1. A user has 50 browser tabs open
2. Network switches from WiFi to cellular mid-conversation
3. Server needs to restart for deployment
4. A message is sent while recipient is offline
5. We need to add read receipts later
```
## Practical Pattern: The Architecture Dialogue
Instead of asking AI for a complete architecture upfront, have a dialogue. Here's a real example:
### Round 1: Initial Options
**You:**
```
I'm building a job queue system for processing medical images (DICOM files, 50-500MB each).
We process about 1000 images/day now, expecting 10K/day within a year.
What are three fundamentally different architectural approaches, from
simplest to most complex?
```
**AI Response Summary:**
1. Simple: PostgreSQL-based queue with polling workers
2. Moderate: Redis + Bull queue with Node.js workers
3. Complex: RabbitMQ/SQS with microservices
### Round 2: Deep Dive on Leading Candidate
**You:**
```
Let's explore option 2 (Redis + Bull). Show me:
1. Actual code for the producer and consumer
2. How to handle worker crashes mid-processing
3. How to implement priority queues (urgent scans first)
4. Monitoring strategy
5. How this scales from 1K to 10K images/day
```
**AI Response with Code:**
```javascript
// producer.js
const Queue = require('bull');
const imageQueue = new Queue('image-processing', {
redis: { host: 'localhost', port: 6379 }
});
const jobOptions = {
attempts: 3,
backoff: {
type: 'exponential',
delay: 60000 // 1 minute
},
timeout: 600000 // 10 minutes
};
// Add job with priority
await imageQueue.add(
{ imageId: '12345', s3Path: 's3://bucket/image.dcm' },
{ ...jobOptions, priority: isUrgent ? 1 : 10 }
);
// consumer.js
const imageQueue = new Queue('image-processing');
imageQueue.process(5, async (job) => { // 5 concurrent workers
const { imageId, s3Path } = job.data;
try {
// Update progress for monitoring
await job.progress(10);
// Download from S3
const imageBuffer = await downloadFromS3(s3Path);
await job.progress(40);
// Process image
const results = await processDicomImage(imageBuffer);
await job.progress(80);
// Store results
await storeResults(imageId, results);
await job.progress(100);
return { imageId, status: 'complete' };
} catch (error) {
// Log will be preserved for failed jobs
console.error(`Failed to process ${imageId}:`, error);
throw error; // Will trigger retry
}
});
// Monitoring
imageQueue.on('failed', (job, err) => {
logToMonitoring('job_failed', { jobId: job.id, error: err.message });
});
imageQueue.on('stalled', (job) => {
logToMonitoring('job_stalled', { jobId: job.id });
});
```
### Round 3: Challenge the Approach
**You:**
```
What breaks first in this Redis + Bull architecture as we scale?
What's our single point of failure?
Show me how to make Redis highly available.
```
This iterative approach helps you understand the architecture deeply, not just copy-paste it.
## Real-World Decision: Database Selection
Let's walk through a complete architecture decision using AI assistance.
### Scenario
You're building a SaaS analytics platform. You need to choose a database for storing event data (click streams, page views, etc.).
### Step 1: Frame the Problem
```
I need to choose a database for an analytics platform. Requirements:
- Ingestion rate: 1M events/day (growing to 50M/day in year 2)
- Event data: JSON objects, 1-5KB each
- Query patterns:
* Real-time dashboards (last 24 hours)
* Historical analysis (aggregations over months)
* User-specific queries ("show me user X's journey")
- Retention: 2 years of data
- Budget: Must start cheap, can scale with revenue
- Team: Strong in Python, SQL; no specialized DB expertise
Compare 4 options: PostgreSQL, TimescaleDB, ClickHouse, and MongoDB.
For each, provide sample schema and a typical query.
```
### Step 2: Evaluate AI's Suggestions
AI will likely suggest all four are viable. Your job is to dig deeper:
```
For TimescaleDB (which looks promising):
1. Show me the actual schema for storing events
2. Write a query for "hourly active users in the last 30 days"
3. What's our data retention strategy to stay under 1TB?
4. How do we handle schema changes as events evolve?
5. What breaks if we don't partition correctly?
```
### Step 3: Prototype the Critical Path
```
Generate a Docker Compose setup with TimescaleDB that I can test locally.
Include:
1. TimescaleDB with appropriate extensions
2. A Python script to generate 100K realistic events
3. A Python script that runs 10 common queries
4. Basic monitoring to measure query performance
I want to validate this can handle our query patterns before committing.
```
This moves from theory to practice. You'll discover issues AI might not mention, like query performance quirks or operational complexity.
### Step 4: Document the Decision
Use AI to help create an Architecture Decision Record (see our [doc-generation](/lessons/doc-generation) lesson):
```
Create an ADR documenting our decision to use TimescaleDB over PostgreSQL,
ClickHouse, and MongoDB for our analytics platform.
Include:
- Context and requirements
- Options considered with pros/cons
- Decision rationale
- Consequences (both positive and negative)
- Migration plan from our current SQLite prototype
```
## Common Pitfalls to Avoid
### Pitfall 1: Accepting the First Suggestion
AI often defaults to popular, general-purpose solutions. Always ask for alternatives:
```
❌ "What database should I use for my app?"
✅ "Compare 4 database options for [specific use case], including at least
one unconventional choice. Explain tradeoffs."
```
### Pitfall 2: Ignoring Your Team's Skills
AI might suggest Kubernetes when your team has never used containers:
```
❌ Accepting: "Use Kubernetes for orchestration"
✅ Asking: "We've only used Heroku. What's the operational burden of moving
to Kubernetes? Show me what day-to-day operations look like."
```
### Pitfall 3: Optimizing for Problems You Don't Have
AI loves suggesting scalable architectures. But over-engineering kills startups:
```
❌ "Design a microservices architecture for my app"
✅ "I have 100 users. Design the simplest architecture that lets me ship
features fast. When would I need to evolve it?"
```
See our [when-not-to-use-ai](/lessons/when-not-to-use-ai) lesson for more on this.
### Pitfall 4: Skipping the Prototype
Architectural diagrams lie. Code doesn't:
```
Don't just ask for architecture diagrams. Ask for:
- Working code samples
- Docker Compose setups you can run locally
- Performance test scripts
- Failure simulation scenarios
```
## Advanced Technique: Competitive Analysis
Use AI to analyze how successful companies solve similar problems:
```
How do companies like Stripe, Datadog, and Segment handle high-volume
event ingestion and querying?
For each, explain:
1. Their likely architecture (based on public engineering blogs)
2. Why they chose that approach
3. What I can apply to my 1M events/day use case
4. What I should ignore because I'm not at their scale
```
This gives you battle-tested patterns without cargo-culting inappropriate solutions.
## Integration with Your Workflow
### Before Writing Code
Use AI for architecture decisions during planning:
1. **Spike phase**: Generate multiple options
2. **Prototype phase**: Create minimal working examples
3. **Decision phase**: Document choice in ADR
4. **Implementation phase**: Use AI for code generation (see [code-gen-best-practices](/lessons/code-gen-best-practices))
### During Code Review
Ask AI to review architectural implications:
```
Review this authentication implementation. Does it align with our
architecture decision to use JWT tokens with refresh token rotation?
Are there architectural concerns I should address before merging?
```
See our [review-refactor](/lessons/review-refactor) lesson for more review strategies.
### During Refactoring
When managing technical debt (see [managing-tech-debt](/lessons/managing-tech-debt)):
```
We chose SQLite initially but now have 50K users. Analyze our current
code and propose a migration path to PostgreSQL.
Show:
1. What changes at the architecture level
2. Step-by-step migration plan
3. How to test the migration
4. Rollback strategy
```
## Architecture Decisions Checklist
Before finalizing an AI-assisted architecture decision:
**✓ Constraints Documented**
- [ ] Team skills and size
- [ ] Budget and timeline
- [ ] Scale requirements (current and projected)
- [ ] Compliance and security requirements
- [ ] Integration constraints
**✓ Options Explored**
- [ ] Generated 3+ alternative approaches
- [ ] Included at least one "simple" option
- [ ] Understood tradeoffs of each
**✓ Validation Complete**
- [ ] Created working prototype
- [ ] Tested critical queries/operations
- [ ] Identified failure modes
- [ ] Estimated operational burden
- [ ] Planned migration path
**✓ Documentation**
- [ ] Created ADR with decision rationale
- [ ] Documented consequences (good and bad)
- [ ] Shared with team for feedback
**✓ Escape Hatches**
- [ ] Know how to rollback
- [ ] Identified next evolution point
- [ ] Monitoring in place to validate decision
## Connecting to Your Vibe Coding Practice
Architecture decisions set the foundation for everything else:
- **Project Planning**: Your architectural choices shape your roadmap (see [roadmap-planning](/lessons/roadmap-planning))
- **Component Generation**: Good architecture makes component generation more effective (see [component-generation](/lessons/component-generation))
- **Testing Strategy**: Architecture determines what testing approaches work (see [testing-strategies](/lessons/testing-strategies))
- **Team Workflows**: Scale your architecture decisions across team members (see [team-workflows](/lessons/team-workflows))
## Practice Exercise
Try this architecture decision with AI:
**Scenario**: You're building a multi-tenant SaaS where customers can upload files (documents, images) that need to be processed, stored, and served securely. You have 10 customers now, expect 100 in 6 months.
**Your Task**:
1. Use AI to generate 3 storage architecture options
2. For your chosen option, create a working prototype
3. Write an ADR documenting the decision
4. Identify what would force you to reconsider
Time box this to 4 hours. The goal is practice with the decision framework, not building a production system.
## Key Takeaways
1. **AI excels at generating options**, but you must evaluate them against your constraints
2. **Always prototype** before committing to an architecture
3. **Document decisions** so future you understands the rationale
4. **Architecture decisions compound**: Get early ones right to move faster later
5. **Don't over-engineer**: Choose the simplest architecture that meets your actual needs
Architecture decisions require judgment AI can't provide. But by using AI to explore options, pressure-test assumptions, and generate working prototypes, you'll make better decisions faster.
Next, explore [tech-spec-generation](/lessons/tech-spec-generation) to learn how to translate architectural decisions into detailed technical specifications that guide implementation.