# Blog Migration Architecture

**Last Updated:** 2026-01-09

Technical architecture for migrating the WordPress blog to static pages, including build process, routing, data storage, and deployment requirements.

## Overview

This document outlines the technical architecture for migrating the WordPress blog to static pages, focusing on static site generation, data storage, routing, and deployment.

## Architecture Approach

### Static Site Generation

**Recommended Approach**: Static site generation (SSG)

**Benefits**:

- Fast page loads
- Better SEO
- Lower hosting costs
- Improved security
- Better performance

**Options**:

- **Next.js**: React-based SSG
- **Gatsby**: React-based SSG
- **11ty**: JavaScript-based SSG
- **Hugo**: Go-based SSG
- **Jekyll**: Ruby-based SSG

**Recommendation**: Next.js (aligns with existing project structure)

## URL Structure

### Current WordPress URLs

```
/insights/                          (Blog index)
/insights/lexikon/                  (Lexikon archive)
/insights/ratgeber/                 (Ratgeber archive)
/insights/inside-ordio/             (Inside Ordio archive)
/insights/{category}/{slug}/        (Single posts)
```

### Migration URL Strategy

**Option 1: Maintain Exact URLs** (Recommended)

- Preserve current URL structure
- No redirects needed
- SEO-friendly
- User-friendly

**Option 2: Optimize URLs**

- Simplify structure if needed
- Requires 301 redirects
- SEO consideration needed

**Recommendation**: Maintain exact URLs for SEO

## Routing Requirements

### Static Routes

**Index Route**: `/insights/`

- Static page: `insights/index.html`

**Category Routes**:

- `/insights/lexikon/` → `insights/lexikon/index.html`
- `/insights/ratgeber/` → `insights/ratgeber/index.html`
- `/insights/inside-ordio/` → `insights/inside-ordio/index.html`

**Post Routes**:

- `/insights/{category}/{slug}/` → `insights/{category}/{slug}/index.html`

### Dynamic Routes (If Needed)

**Next.js Example**:

```javascript
// pages/insights/[category]/[slug].js
export async function getStaticPaths() {
  // Generate paths for all posts
}

export async function getStaticProps({ params }) {
  // Fetch post data
}
```

## Data Storage Approach

### Option 1: JSON Files (Recommended)

**Structure**:

```
data/
├── blog/
│   ├── posts/
│   │   ├── lexikon/
│   │   │   └── post-slug.json
│   │   └── ...
│   ├── categories.json
│   ├── clusters.json
│   └── topics.json
```

**Benefits**:

- Version controlled
- Easy to edit
- Fast to read
- No database needed

### Option 2: Database

**Options**:

- SQLite (lightweight)
- PostgreSQL (if needed)
- Headless CMS (Contentful, Strapi)

**Consideration**: Only if dynamic content needed

### Option 3: Hybrid

**Approach**:

- JSON files for content
- Database for relationships/search

**Recommendation**: Start with JSON files, add database if needed

## Build Process

### Build Steps

1. **Data Preparation**

   - Extract content from WordPress
   - Transform to JSON format
   - Optimize images
   - Generate relationships

2. **Static Generation**

   - Generate index page
   - Generate category pages
   - Generate post pages
   - Generate sitemap

3. **Optimization**

   - Minify HTML/CSS/JS
   - Optimize images
   - Generate service worker (if PWA)

4. **Validation**
   - Check all links
   - Validate schema markup
   - Test responsive design
   - Performance testing

### Build Tools

**Next.js Build**:

```bash
npm run build
# Generates static files in .next/out/
```

**Custom Build Script**:

```javascript
// scripts/build-blog.js
const fs = require("fs");
const posts = require("./data/blog/posts.json");

// Generate pages
posts.forEach((post) => {
  generatePostPage(post);
});

generateIndexPage();
generateCategoryPages();
```

## Deployment Requirements

### Static Hosting Options

1. **Vercel** (Recommended for Next.js)

   - Automatic deployments
   - CDN included
   - Easy setup

2. **Netlify**

   - Static hosting
   - Form handling
   - Build hooks

3. **GitHub Pages**

   - Free hosting
   - Version controlled
   - Simple setup

4. **AWS S3 + CloudFront**
   - Scalable
   - Cost-effective
   - Full control

### Deployment Process

1. **Build**: Generate static files
2. **Test**: Validate locally
3. **Deploy**: Upload to hosting
4. **Verify**: Check live site
5. **Monitor**: Track performance

## Performance Optimization

### Image Optimization

**Requirements**:

- WebP format
- Responsive sizes
- Lazy loading
- Proper dimensions

**Tools**:

- Sharp (Node.js)
- ImageMagick
- Next.js Image component

### Code Optimization

**Requirements**:

- Minified CSS/JS
- Code splitting
- Tree shaking
- Bundle optimization

**Tools**:

- Webpack
- Terser
- PostCSS

### Caching Strategy

**Static Assets**:

- Long cache headers
- Versioned filenames
- CDN caching

**HTML Pages**:

- Short cache (1 hour)
- Revalidation on build
- CDN edge caching

## SEO Requirements

### Technical SEO

1. **Sitemap Generation**

   - XML sitemap
   - Submit to Google Search Console
   - Update on content changes

2. **Robots.txt**

   - Allow indexing
   - Disallow admin paths
   - Sitemap reference

3. **Schema Markup**

   - Article schema
   - BreadcrumbList schema
   - Organization schema

4. **Meta Tags**
   - Unique titles
   - Unique descriptions
   - Open Graph tags
   - Twitter Cards

### URL Preservation

**301 Redirects**:

- Map old URLs to new URLs
- Preserve link equity
- Update internal links

**Canonical URLs**:

- Set canonical tags
- Prevent duplicates
- Handle www/non-www

## Monitoring & Maintenance

### Analytics

**Required**:

- Google Analytics 4
- Google Search Console
- Performance monitoring

**Optional**:

- Custom event tracking
- User behavior analysis

### Content Updates

**Process**:

1. Edit JSON files
2. Rebuild site
3. Deploy updates
4. Verify changes

**Automation**:

- CI/CD pipeline
- Automated builds
- Automated deployments

## Migration Checklist

### Pre-Migration

- [ ] Extract all content
- [ ] Transform to JSON format
- [ ] Download all images
- [ ] Map all URLs
- [ ] Generate redirect map

### Migration

- [ ] Set up build process
- [ ] Generate static pages
- [ ] Optimize images
- [ ] Generate sitemap
- [ ] Test all pages

### Post-Migration

- [ ] Deploy to staging
- [ ] Verify all links
- [ ] Test performance
- [ ] Submit sitemap
- [ ] Monitor analytics

## Related Documentation

- [Migration Template Requirements](MIGRATION_TEMPLATE_REQUIREMENTS.md) - Template specifications
- [Migration Content Structure](MIGRATION_CONTENT_STRUCTURE.md) - Data structure requirements
- [Migration Strategy](MIGRATION_STRATEGY.md) - High-level migration approach
- [Migration Requirements](MIGRATION_REQUIREMENTS.md) - Content/media/SEO requirements