Architecture Prompts for Better Documentation

Learn how to use AI prompts effectively to create and maintain high-quality architecture documentation in Knowledge AI.

Why Architecture Documentation Matters

Architecture documentation is the foundation of any successful project, but it's often:

• Outdated - Changes faster than documentation can keep up
• Incomplete - Missing crucial context and decisions
• Scattered - Spread across wikis, docs, and tribal knowledge
• Hard to Find - Buried in folders or poorly organized

Knowledge AI + AI assistants like Claude can help solve these problems.

Essential Architecture Prompts

1. System Overview Generation

When starting a new architecture document:

Based on my existing notes and documentation, help me create a comprehensive system architecture overview that covers:

1. High-level system components and their relationships  
2. Data flow between major services
3. Key architectural decisions and their rationale
4. Integration points with external systems
5. Scalability and performance considerations

Please reference specific notes from my knowledge base where relevant and suggest [[wikilinks]] to connect related concepts.

2. Decision Documentation

For architectural decision records (ADRs):

Help me document an architectural decision about [SPECIFIC TOPIC]. 

Create an ADR that includes:
- **Context**: What situation led to this decision?
- **Decision**: What was decided and why?
- **Consequences**: What are the positive and negative outcomes?
- **Alternatives**: What other options were considered?

Reference any existing documentation about [RELATED SYSTEMS] and create wikilinks to relevant concepts like [[system architecture]], [[performance requirements]], etc.

3. Documentation Gap Analysis

To find missing documentation:

Review my current architecture documentation and identify gaps. Look for:

1. Undocumented systems or components mentioned in passing
2. Missing decision rationale for major choices  
3. Integration points without proper documentation
4. Performance or scaling assumptions that aren't explained
5. Security considerations that need more detail

For each gap, suggest specific documents I should create and how they should connect to existing notes via [[wikilinks]].

Documentation Patterns That Work

The Hub-and-Spoke Pattern

Create a central [[System Architecture]] document that links to specialized pages:

# System Architecture

## Overview
Our system follows a microservices architecture with...

## Core Components
- [[API Gateway]] - Handles routing and authentication
- [[User Service]] - Manages user accounts and profiles  
- [[Data Pipeline]] - Processes and transforms data
- [[Storage Layer]] - Database and caching strategies

## Cross-Cutting Concerns
- [[Security Architecture]]
- [[Monitoring and Observability]]  
- [[Deployment Strategy]]

Decision Trees

Document decision processes with interconnected pages:

# Technology Decisions

## Database Choice
We evaluated several options for our primary database:

### Requirements
- [[Scalability Requirements]] - Must handle 100k+ users
- [[Consistency Needs]] - Strong consistency for financial data
- [[Performance Targets]] - Sub-100ms query response times

### Options Considered  
- [[PostgreSQL Evaluation]] - Traditional RDBMS approach
- [[MongoDB Evaluation]] - Document database option
- [[Cassandra Evaluation]] - Distributed database solution

### Final Decision: [[PostgreSQL Implementation]]

AI-Assisted Maintenance

Regular Documentation Review

Monthly prompt for keeping docs current:

Review my architecture documentation from the past month and help me:

1. Identify any new systems or components that need documentation
2. Update existing docs based on recent changes or decisions
3. Find broken or outdated [[wikilinks]] that need fixing
4. Suggest new connections between related concepts

Focus on documents tagged with #architecture and check for references to recent projects or initiatives.

Onboarding Documentation

Generate developer onboarding materials:

Create a developer onboarding guide that helps new team members understand our system architecture. Include:

1. **Getting Started** - Essential concepts and terminology
2. **System Map** - Visual guide to major components  
3. **First Tasks** - Hands-on exercises to explore the system
4. **Deep Dive Topics** - Links to detailed technical documentation

Reference our [[System Architecture]], [[Development Environment Setup]], and [[Code Standards]] documentation. Create a logical flow with [[wikilinks]] between sections.

Best Practices for AI-Generated Architecture Docs

1. Start with Context

Always provide the AI with background:

• What type of system you're building
• Scale and performance requirements
• Team size and expertise
• Technology constraints

2. Use Consistent Terminology

Maintain a [[Glossary]] of terms and reference it:

# Glossary

**Service Mesh**: Our [[Istio]] implementation that handles service-to-service communication
**Event Store**: The [[Apache Kafka]] cluster used for [[Event Sourcing]]
**API Gateway**: Our [[Kong]] instance that manages external API access

3. Connect Everything

Use [[wikilinks]] extensively to show relationships:

• Link decisions to requirements
• Connect components to their documentation
• Reference related patterns and practices

4. Include Visuals

Prompt for diagram descriptions that can be turned into actual diagrams:

Describe the data flow through our system in a way that would make a good sequence diagram. Include:
1. User actions and entry points
2. Service interactions and API calls  
3. Database operations and side effects
4. Response flow back to the user

Format this as steps that could be converted to a Mermaid diagram.

Common Architecture Documentation Types

System Context Diagrams

• Purpose: Show system boundaries and external interactions
• Wikilinks: Connect to [[Stakeholders]], [[External APIs]], [[Compliance Requirements]]

Component Diagrams

• Purpose: Detail internal system structure
• Wikilinks: Link to [[Service Documentation]], [[API Specs]], [[Database Schemas]]

Deployment Diagrams

• Purpose: Show how components are deployed and scaled
• Wikilinks: Connect to [[Infrastructure]], [[DevOps Processes]], [[Monitoring]]

Sequence Diagrams

• Purpose: Illustrate interactions over time
• Wikilinks: Reference [[User Stories]], [[API Documentation]], [[Error Handling]]

Templates for Common Scenarios

Microservice Documentation Template

# [Service Name]

## Purpose
What this service does and why it exists.

## Dependencies
- [[Database Name]] - Primary data storage
- [[External API]] - Third-party integration  
- [[Message Queue]] - Async communication

## API Reference
- [[API Documentation]] - Full endpoint details
- [[Authentication]] - How to authenticate requests
- [[Rate Limits]] - Usage restrictions and quotas

## Operations
- [[Deployment Guide]] - How to deploy this service
- [[Monitoring]] - Key metrics and alerts
- [[Troubleshooting]] - Common issues and solutions

Integration Documentation Template

# [System A] ↔ [System B] Integration

## Overview
Brief description of why these systems need to integrate.

## Architecture
- [[Data Flow Diagram]] - How data moves between systems
- [[Authentication]] - How systems authenticate with each other
- [[Error Handling]] - What happens when things go wrong

## Implementation
- [[API Contracts]] - Detailed interface specifications  
- [[Data Mapping]] - How data structures translate
- [[Configuration]] - Required settings and parameters

## Operations
- [[Health Checks]] - How to verify the integration is working
- [[Troubleshooting Guide]] - Common issues and solutions
- [[Performance Monitoring]] - Key metrics to track

---

Pro Tip: The key to great architecture documentation is consistency and connectivity. Use AI to maintain consistency in structure and language, while [[wikilinks]] create the connectivity that makes your knowledge base truly intelligent.