Technical Architecture - Blog Platform

This is the verbatim output from claude used as the architecture "prompt" to build the website...with Claude. I chose Option 1. 😁

Overview

This repository contains a lightweight blog platform designed for publishing markdown articles with minimal infrastructure overhead. The project is structured as a monorepo using NPM workspaces to manage multiple packages.

Repository Structure

blog/
├── packages/
│   ├── infrastructure/     # AWS CDK infrastructure code
│   ├── client/            # Frontend website
│   ├── backend/           # API services (Phase 2)
│   └── shared/            # Shared utilities and types
├── src/
│   └── articles/          # Markdown blog articles
├── package.json           # Root package.json with workspaces
├── TECHNICAL_ARCHITECTURE.md
└── README.md

NPM Workspaces Configuration

The root package.json will define workspaces:

{
  "name": "blog-monorepo",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "build": "npm run build --workspaces --if-present",
    "deploy": "npm run deploy --workspace=packages/infrastructure",
    "clean": "npm run clean --workspaces --if-present && rm -rf node_modules/.cache"
  }
}

Frontend Architecture Options

Option 1: Static Site with Build-Time Rendering

• Tech Stack: Vanilla HTML/CSS/JS + build-time markdown processor
• Markdown Processing: Using marked or markdown-it at build time
• Benefits: Zero runtime JS, fastest loading, SEO-friendly
• Implementation: Node.js build script that converts markdown to HTML

Option 2: Minimal Client-Side Rendering

• Tech Stack: Vanilla JS + lightweight markdown library
• Markdown Processing: marked (2.7kb gzipped) loaded on demand
• Benefits: Dynamic content loading, still very lightweight
• Implementation: Simple HTML shell with client-side routing

Option 3: Web Components Approach

• Tech Stack: Native Web Components + markdown processing
• Markdown Processing: Custom Web Components for content rendering
• Benefits: Reusable components, modern browser features, no framework overhead
• Implementation: Custom <markdown-article> component

Recommendation: Option 1 (Static Site) for Phase 1, with Option 2 as fallback for dynamic features.

AWS Infrastructure Architecture

Phase 1: Static Site Hosting

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Route 53  │────│ CloudFront   │────│ S3 Static Site  │
│   (DNS)     │    │ (CDN/Cache)  │    │ (HTML/CSS/JS)   │
└─────────────┘    └──────────────┘    └─────────────────┘
                            │
                   ┌─────────────────┐
                   │ S3 Articles     │
                   │ (Markdown)      │
                   └─────────────────┘

Core Services:

• S3 Buckets:
  • blog-static-site: Compiled HTML/CSS/JS assets
  • blog-articles: Raw markdown files
  • blog-assets: Images and media files
• CloudFront: Global CDN for fast content delivery
• Route 53: DNS management (optional, can use external DNS)
• Certificate Manager: SSL/TLS certificates

Phase 2: Dynamic API (Future)

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Route 53  │────│ CloudFront   │────│ S3 Static Site  │
│   (DNS)     │    │ (CDN/Cache)  │    │ (HTML/CSS/JS)   │
└─────────────┘    └──────────────┘    └─────────────────┘
                            │
                   ┌─────────────────┐    ┌─────────────────┐
                   │ API Gateway     │────│ Lambda Functions│
                   │ (REST API)      │    │ (Node.js)       │
                   └─────────────────┘    └─────────────────┘
                            │
                   ┌─────────────────┐
                   │ DynamoDB        │
                   │ (Metadata)      │
                   └─────────────────┘

Package Specifications

packages/infrastructure

• Technology: AWS CDK (TypeScript)
• Purpose: Infrastructure as Code
• Scripts:
  • build: Compile TypeScript
  • deploy: Deploy to AWS
  • destroy: Destroy AWS resources

packages/client

• Technology: Vanilla HTML/CSS/JS + build tools
• Purpose: Frontend website
• Scripts:
  • build: Process markdown and generate static site
  • dev: Local development server
  • clean: Remove build artifacts

packages/backend (Phase 2)

• Technology: Node.js + TypeScript
• Purpose: API services for dynamic features
• Scripts:
  • build: Compile and bundle for Lambda
  • test: Run unit tests
  • clean: Remove build artifacts

packages/shared

• Technology: TypeScript
• Purpose: Shared types and utilities
• Scripts:
  • build: Compile TypeScript declarations
  • clean: Remove build artifacts

Build and Deployment Pipeline

Development Workflow

1. Write articles in src/articles/ as markdown files
2. Run npm run build to generate static site
3. Run local dev server to preview changes
4. Commit changes to version control

Deployment Workflow

1. npm run build - Build all packages
2. npm run deploy - Deploy infrastructure and upload assets to S3
3. CloudFront invalidation (handled by CDK)

Commands Summary

• npm run build: Builds all packages that have a build script
• npm run deploy: Deploys infrastructure and uploads built assets
• npm run clean: Cleans all build artifacts across workspaces

Content Management

Article Structure

---
title: "Article Title"
date: "2024-01-01"
tags: ["tag1", "tag2"]
excerpt: "Brief description"
---

# Article content in markdown

Asset Management

• Images: Stored in src/articles/assets/ or referenced from S3
• Processing: Optimized during build process
• CDN: Served through CloudFront for global distribution

Performance Considerations

Frontend Optimizations

• Minimal JavaScript: Only essential functionality
• CSS Optimization: Minified and tree-shaken
• Image Optimization: WebP format with fallbacks
• Lazy Loading: Images and non-critical content

Infrastructure Optimizations

• CloudFront Caching: Aggressive caching for static assets
• S3 Transfer Acceleration: Faster uploads to S3
• Compression: Gzip/Brotli compression enabled

Security Considerations

Static Site Security

• HTTPS Only: All traffic over SSL/TLS
• Content Security Policy: Restrictive CSP headers
• CORS Configuration: Appropriate CORS settings

Infrastructure Security

• IAM Roles: Least privilege access
• S3 Bucket Policies: Restricted public access
• CloudFront Security Headers: Security-focused response headers

Development Environment

Prerequisites

• Node.js 18+ and npm
• AWS CLI configured
• AWS CDK CLI installed

Local Development

# Install dependencies
npm install

# Start development server
npm run dev --workspace=packages/client

# Build all packages
npm run build

# Deploy to AWS
npm run deploy

Future Enhancements (Phase 2)

1. Dynamic API Backend

   • Article search and filtering
   • Comment system
   • View analytics
   • Content management API

2. Enhanced Frontend Features

   • Client-side search
   • Progressive Web App (PWA)
   • Dark mode toggle
   • Reading progress indicator

3. Content Management

   • Admin interface
   • Draft article system
   • Scheduled publishing
   • Content versioning

This architecture provides a solid foundation for a fast, lightweight blog platform that can scale from simple static hosting to a more dynamic system as requirements evolve.