architecture-documenter

What this skill does

# Architecture Documenter Skill

Document system architecture and technical design decisions for effective team communication and knowledge sharing.

## Instructions

You are a software architecture documentation expert. When invoked:

1. **Analyze System Architecture**:
   - Identify key components and services
   - Understand data flows and interactions
   - Map dependencies and integrations
   - Recognize architectural patterns
   - Assess scalability and reliability

2. **Create Architecture Documentation**:
   - System overview and context
   - Component diagrams and relationships
   - Data flow diagrams
   - Deployment architecture
   - Security architecture
   - Decision records (ADRs)

3. **Document Technical Decisions**:
   - What was decided
   - Why it was decided
   - Alternatives considered
   - Trade-offs made
   - Implementation details
   - Future considerations

4. **Use Visual Diagrams**:
   - System architecture diagrams
   - Sequence diagrams
   - Entity-relationship diagrams
   - Infrastructure diagrams
   - Network topology
   - State machines

5. **Maintain Living Documentation**:
   - Keep docs synchronized with code
   - Version architecture docs
   - Track evolution over time
   - Mark deprecated components
   - Update with lessons learned

## Architecture Documentation Templates

### System Architecture Document Template

```markdown
# E-Commerce Platform - System Architecture

**Version**: 2.3
**Last Updated**: January 15, 2024
**Status**: Current
**Authors**: Engineering Team
**Reviewers**: Alice (EM), Bob (Tech Lead)

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [System Context](#system-context)
3. [Architecture Overview](#architecture-overview)
4. [Core Components](#core-components)
5. [Data Architecture](#data-architecture)
6. [Infrastructure](#infrastructure)
7. [Security Architecture](#security-architecture)
8. [Scalability & Performance](#scalability--performance)
9. [Deployment](#deployment)
10. [Monitoring & Observability](#monitoring--observability)
11. [Future Considerations](#future-considerations)

---

## Executive Summary

### What This System Does

The E-Commerce Platform is a modern, cloud-native application that enables small to medium businesses to sell products online. It handles the complete e-commerce lifecycle from product catalog management to order fulfillment.

### Key Capabilities

- **Product Management**: Create, update, and manage product catalogs
- **Shopping Experience**: Browse products, search, filter, and compare
- **Checkout & Payments**: Secure checkout with multiple payment options
- **Order Management**: Track orders from placement to delivery
- **User Accounts**: Customer profiles, order history, preferences
- **Admin Dashboard**: Business analytics, inventory management

### System Scale

| Metric | Current | Target (6 months) |
|--------|---------|-------------------|
| Active Users | 5,000 businesses | 15,000 businesses |
| Products | 500,000 | 2,000,000 |
| Daily Orders | 10,000 | 50,000 |
| Monthly GMV | $2M | $10M |
| Peak RPS | 500 | 2,000 |
| Data Storage | 2 TB | 10 TB |

### Technology Stack Summary

- **Frontend**: React, TypeScript, Redux, Material-UI
- **Backend**: Node.js, Express, TypeScript
- **Database**: PostgreSQL (primary), Redis (cache)
- **Storage**: AWS S3
- **Hosting**: AWS (ECS, RDS, ElastiCache, CloudFront)
- **CI/CD**: GitHub Actions
- **Monitoring**: DataDog, Sentry

---

## System Context

### Business Context

**Problem We Solve**: Small businesses struggle with expensive, complex e-commerce solutions. Our platform provides an affordable, easy-to-use alternative.

**Target Users**:
- Small business owners (10-1000 products)
- Digital creators selling physical products
- Retail stores expanding online

**Business Model**: SaaS subscription ($29-$299/month) + transaction fees (2.9% + $0.30)

### System Boundary

```
┌─────────────────────────────────────────────────────┐
│                 E-Commerce Platform                 │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Customer │  │ Merchant │  │    Admin     │    │
│  │   Web    │  │Dashboard │  │   Portal     │    │
│  └──────────┘  └──────────┘  └──────────────┘    │
│                                                     │
│  ┌──────────────────────────────────────────────┐ │
│  │            Backend Services                   │ │
│  │  (Auth, Product, Order, Payment, etc.)       │ │
│  └──────────────────────────────────────────────┘ │
│                                                     │
│  ┌──────────────────────────────────────────────┐ │
│  │         Data & Storage Layer                 │ │
│  │     (PostgreSQL, Redis, S3)                  │ │
│  └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌─────────┐   ┌──────────┐   ┌──────────┐
   │ Stripe  │   │  SendGrid│   │  Shippo  │
   │ Payment │   │   Email  │   │ Shipping │
   └─────────┘   └──────────┘   └──────────┘
```

### External Dependencies

| Service | Purpose | SLA | Fallback Strategy |
|---------|---------|-----|-------------------|
| Stripe | Payment processing | 99.99% | Queue retries, manual processing |
| SendGrid | Email delivery | 99.95% | Alternative provider (AWS SES) |
| Shippo | Shipping labels | 99.9% | Manual label generation |
| AWS | Infrastructure | 99.99% | Multi-AZ deployment |
| Cloudflare | CDN/DNS | 99.99% | Direct origin access |

---

## Architecture Overview

### High-Level Architecture

```
                        Internet
                           │
                           ▼
                    ┌──────────────┐
                    │  Cloudflare  │ (CDN, DDoS protection)
                    └──────┬───────┘
                           │
                           ▼
                ┌──────────────────────┐
                │   AWS CloudFront     │ (Static assets)
                └──────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌──────────────┐
│    React      │  │  API Gateway  │  │    Admin     │
│   Frontend    │  │  (Express)    │  │   Portal     │
│  (CloudFront) │  │   (ALB+ECS)   │  │              │
└───────────────┘  └───────┬───────┘  └──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
   ┌─────────┐      ┌──────────┐      ┌──────────┐
   │  Auth   │      │ Product  │      │  Order   │
   │ Service │      │ Service  │      │ Service  │
   └────┬────┘      └────┬─────┘      └────┬─────┘
        │                │                  │
        └────────────────┼──────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
   ┌─────────┐     ┌─────────┐     ┌─────────┐
   │PostgreSQL│     │  Redis  │     │   S3    │
   │  (RDS)   │     │(ElastiCache)  │(Images) │
   └──────────┘     └─────────┘     └─────────┘
```

### Architecture Style

**Primary Pattern**: Modular Monolith (transitioning to Microservices)

**Rationale**:
- **Current**: Modular monolith provides simplicity while maintaining clear boundaries
- **Future**: Easy migration path to microservices as scale increases
- **Trade-off**: Accepts coupling cost for development velocity at current scale

### Key Architectural Principles

1. **Separation of Concerns**: Clear boundaries between modules
2. **API-First**: All features exposed via REST APIs
3. **Stateless Services**: No server-side session state (JWT-based auth)
4. **Caching Strategy**: Cache ag