# Architecture Documenter

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

- **Type:** Skill
- **Install:** `agentstack add skill-curiouslearner-devkit-architecture-documenter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CuriousLearner](https://agentstack.voostack.com/s/curiouslearner)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** https://github.com/CuriousLearner/devkit/tree/main/skills/architecture-documenter

## Install

```sh
agentstack add skill-curiouslearner-devkit-architecture-documenter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 aggressively, invalidate carefully
5. **Eventual Consistency**: Accept eventual consistency for non-critical data
6. **Fail Fast**: Return errors quickly rather than retry indefinitely
7. **Observability**: Comprehensive logging, metrics, and tracing

---

## Core Components

### Frontend Application

**Technology**: React 18 + TypeScript + Redux Toolkit

**Structure**:
```
client/
├── components/     # Reusable UI components
├── pages/          # Route-level pages
├── store/          # Redux state management
├── api/            # API client
├── hooks/          # Custom React hooks
└── utils/          # Utility functions
```

**Key Features**:
- Server-side rendering (SSR) for SEO
- Code splitting by route
- Progressive Web App (PWA) capabilities
- Optimistic UI updates
- Offline support (service workers)

**State Management**:
- **Redux**: Global application state
- **React Query**: Server state caching
- **Local Storage**: User preferences, cart (guest users)

**Performance Targets**:
- First Contentful Paint: 90

---

### API Gateway

**Technology**: Express.js + TypeScript

**Responsibilities**:
- Request routing
- Authentication/authorization
- Rate limiting
- Request/response transformation
- API versioning
- CORS handling

**Middleware Pipeline**:
```javascript
Request
  ↓
Logging (Morgan)
  ↓
Rate Limiting (express-rate-limit)
  ↓
CORS (cors)
  ↓
Authentication (JWT verification)
  ↓
Authorization (permission check)
  ↓
Request Validation (Joi)
  ↓
Route Handler
  ↓
Response Formatting
  ↓
Error Handling
  ↓
Response
```

**API Versioning Strategy**:
- URL versioning: `/api/v1/products`, `/api/v2/products`
- Maintain 2 versions simultaneously
- Deprecation warnings in headers
- 6-month sunset period for old versions

---

### Service Modules

#### Authentication Service

**Responsibilities**:
- User registration and login
- JWT token generation and validation
- Password reset flow
- OAuth integration (Google, Facebook)
- Multi-factor authentication (MFA)

**Database Schema**:
```sql
users (
  id UUID PRIMARY KEY,
  email VARCHAR UNIQUE NOT NULL,
  password_hash VARCHAR NOT NULL,
  email_verified BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

sessions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  token_hash VARCHAR NOT NULL,
  expires_at TIMESTAMP,
  created_at TIMESTAMP
)

oauth_accounts (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  provider VARCHAR NOT NULL, -- 'google', 'facebook'
  provider_user_id VARCHAR NOT NULL,
  access_token VARCHAR,
  refresh_token VARCHAR,
  UNIQUE(provider, provider_user_id)
)
```

**Security Measures**:
- Passwords hashed with Argon2id
- JWT tokens with 15-minute expiration
- Refresh tokens with 7-day expiration
- Rate limiting: 5 login attempts per 15 minutes
- Account lockout after 10 failed attempts
- MFA via TOTP (Google Authenticator)

#### Product Service

**Responsibilities**:
- Product CRUD operations
- Inventory management
- Search and filtering
- Product recommendations
- Category management

**Database Schema**:
```sql
products (
  id UUID PRIMARY KEY,
  merchant_id UUID REFERENCES users(id),
  name VARCHAR NOT NULL,
  description TEXT,
  price DECIMAL(10,2) NOT NULL,
  inventory_count INTEGER NOT NULL DEFAULT 0,
  category_id UUID REFERENCES categories(id),
  status VARCHAR DEFAULT 'draft', -- draft, active, archived
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

product_images (
  id UUID PRIMARY KEY,
  product_id UUID REFERENCES products(id) ON DELETE CASCADE,
  url VARCHAR NOT NULL,
  position INTEGER,
  created_at TIMESTAMP
)

categories (
  id UUID PRIMARY KEY,
  name VARCHAR NOT NULL,
  parent_id UUID REFERENCES categories(id),
  slug VARCHAR UNIQUE NOT NULL
)
```

**Search Implementation**:
- PostgreSQL full-text search with trigram indexes
- Elasticsearch for advanced features (planned)
- Caching: 5-minute TTL for product lists, 1-hour for individual products

**Performance Optimizations**:
- Database indexes on common query fields
- N+1 query prevention with eager loading
- Image CDN with automatic resizing
- Aggressive caching with Redis

#### Order Service

**Responsibilities**:
- Shopping cart management
- Order creation and processing
- Order status tracking
- Order history
- Invoice generation

**Database Schema**:
```sql
orders (
  id UUID PRIMARY KEY,
  customer_id UUID REFERENCES users(id),
  status VARCHAR NOT NULL, -- pending, paid, shipped, delivered, cancelled
  subtotal DECIMAL(10,2) NOT NULL,
  tax DECIMAL(10,2) NOT NULL,
  shipping DECIMAL(10,2) NOT NULL,
  total DECIMAL(10,2) NOT NULL,
  payment_id VARCHAR,
  shipping_address_id UUID REFERENCES addresses(id),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

order_items (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id) ON DELETE CASCADE,
  product_id UUID REFERENCES products(id),
  quantity INTEGER NOT NULL,
  price DECIMAL(10,2) NOT NULL,
  product_snapshot JSONB -- Product details at time of purchase
)

order_events (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id),
  event_type VARCHAR NOT NULL, -- created, paid, shipped, etc.
  metadata JSONB,
  created_at TIMESTAMP
)
```

**Order State Machine**:
```
pending → paid → processing → shipped → delivered
   ↓       ↓         ↓           ↓
   └───────┴─────────┴───────────┴──→ cancelled
```

**Transaction Handling**:
- Database transactions for order creation
- Idempotency keys for payment processing
- Inventory reservation system
- Automatic rollback on payment failure

#### Payment Service

**Responsibilities**:
- Payment intent creation
- Payment processing (via Stripe)
- Refund handling
- Payment method management
- Transaction history

**Integration with Stripe**:
```javascript
// Payment Intent Flow
1. Client requests payment intent
   ↓
2. Server creates Stripe PaymentIntent
   ↓
3. Client collects payment details
   ↓
4. Client confirms payment with Stripe
   ↓
5. Stripe webhook notifies server
   ↓
6. Server updates order status
```

**Webhook Security**:
- Stripe signature verification
- Idempotent webhook processing
- Async processing with job queue
- Retry logic for failed webhooks

**Database Schema**:
```sql
payments (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id),
  stripe_payment_intent_id VARCHAR UNIQUE,
  amount DECIMAL(10,2) NOT NULL,
  status VARCHAR NOT NULL, -- pending, succeeded, failed
  payment_method VARCHAR, -- card, bank_transfer
  metadata JSONB,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

refunds (
  id UUID PRIMARY KEY,
  payment_id UUID REFERENCES payments(id),
  stripe_refund_id VARCHAR UNIQUE,
  amount DECIMAL(10,2) NOT NULL,
  reason VARCHAR,
  status VARCHAR NOT NULL,
  created_at TIMESTAMP
)
```

---

## Data Architecture

### Database Design

**Primary Database**: PostgreSQL 14

**Schema Organization**:
- **public schema**: Core application tables
- **audit schema**: Audit logs and event sourcing
- **analytics schema**: Denormalized data for reporting

**Connection Pooling**:
```javascript
{
  max: 20,              // Max connections
  min: 5,               // Min connections
  idle: 10000,          // Close idle connections after 10s
  acquire: 30000,       // Max time to acquire connection
  evict: 1000           // Check for idle connections every 1s
}
```

**Backup Strategy**:
- Automated daily backups (RDS snapshots)
- Point-in-time recovery enabled (7-day window)
- Monthly backups retained for 1 year
- Backup tested quarterly

### Caching Strategy

**Redis Configuration**:
- Deployment: AWS ElastiCache (Redis 7.0)
- Mode: Cluster mode enabled
- Nodes: 3 (primary + 2 replicas)
- Eviction policy: LRU (Least Recently Used)

**Cache Patterns**:

1. **Cache-Aside** (Read-heavy data):
```javascript
async function getProduct(id) {
  // Try cache first
  let product = await cache.get(`product:${id}`);

  if (!product) {
    // Cache miss - fetch from database
    product = await db.products.findById(id);

    // Store in cache (1 hou

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** [CuriousLearner/devkit](https://github.com/CuriousLearner/devkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-curiouslearner-devkit-architecture-documenter
- Seller: https://agentstack.voostack.com/s/curiouslearner
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.