Docs/How WP2Astro Works

How WP2Astro Works

Understanding the technical architecture behind WP2Astro's cloud-based development platform.

WP2Astro is a complete platform for building Astro sites in the cloud. Unlike traditional development tools, everything runs in your browser using GitHub Codespaces. This guide explains how the system works under the hood.

Architecture Overview

WP2Astro operates on a cloud-first architecture:

User Dashboard
    ↓
GitHub Repository Creation
    ↓
Codespace Provisioning
    ↓
Browser-Based IDE
    ↓
Vercel Deployment

Let's explore each component in detail.

Component 1: User Dashboard

The WP2Astro dashboard is your control center.

What It Manages

Projects: View all your Astro sites
Codespaces: Start, stop, and manage development environments
Deployments: Monitor and manage Vercel deployments
GitHub Integration: Connect and manage GitHub access

[screenshot of the dashboard]

Project Cards

Each project shows:

Repository name and visibility (public/private)
Codespace status (Off, Starting, Running)
Deployment status (Building, Live, Failed)
Quick actions (Content Editor, Dev Mode, GitHub link)

Codespace Management

The dashboard tracks your GitHub Codespace usage:

Total codespaces: How many you've created
Active codespaces: Currently running
Plan limits: Based on your GitHub account (Free, Pro, Team)

Component 2: GitHub Repository Creation

When you create a project, WP2Astro automatically sets up a complete GitHub repository.

Repository Structure

your-project/
  .devcontainer/
    devcontainer.json      # Codespace configuration
  .github/
    workflows/
      deploy.yml           # CI/CD for Vercel
  src/
    pages/                 # Astro pages
    content/               # Blog posts (MDX)
    layouts/               # Page templates
    components/            # Reusable components
    styles/                # Global CSS
  public/                  # Static assets
  astro.config.mjs         # Astro config
  package.json             # Dependencies
  tsconfig.json            # TypeScript config

What's Pre-Configured

Development Setup:

Node.js 20.x
Astro latest version
TypeScript support
Tailwind CSS (optional)
MDX support for blog posts

Build Configuration:

Optimized production builds
Image optimization
CSS minification
Static site generation

Git Setup:

Initial commit with project structure
.gitignore configured properly
Branch protection (optional)

Repository Visibility

You choose when creating the project:

Public: Anyone can see the code
Private: Only you have access (requires GitHub account with private repos)

Component 3: GitHub Codespaces

The core of WP2Astro's cloud development experience.

What is a Codespace?

A codespace is a complete development environment running in the cloud:

Virtual machine with 2-4 CPU cores
4-8 GB RAM
Linux-based OS (Ubuntu)
Node.js, npm, and Git pre-installed
Astro development server ready to run

Codespace Lifecycle

1. Created (Initial Setup)
   - 30-60 seconds to provision
   - Dependencies installed
   - Dev server starts
   ↓
2. Available (Ready to Use)
   - IDE accessible in browser
   - Live preview running
   - File watching active
   ↓
3. Idle (Inactive)
   - Auto-stops after 4 hours
   - Preserves all files and changes
   ↓
4. Shutdown (Stopped)
   - Not consuming resources
   - Can be restarted anytime
   ↓
5. Deleted (Removed)
   - Frees up quota
   - Code still in GitHub

How Resources Are Allocated

GitHub Free Tier:

120 core-hours/month
15 GB storage
Example: 2-core machine = 60 hours of active use

GitHub Pro Tier:

180 core-hours/month
20 GB storage
Example: 2-core machine = 90 hours of active use

Auto-Stop Feature:

Codespaces automatically stop after 4 hours of inactivity
You can manually stop them sooner
Stopping doesn't delete your work

Codespace Configuration

WP2Astro configures codespaces via .devcontainer/devcontainer.json:

{
  "name": "Astro Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "postCreateCommand": "npm install && npm run dev",
  "forwardPorts": [4321, 8080],
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

What This Does:

Uses official Node.js 20 image
Installs dependencies on creation
Starts Astro dev server automatically
Forwards ports for preview and WebSocket
Includes GitHub CLI for git operations

Component 4: Browser-Based IDE

The WP2Astro IDE runs entirely in your browser.

IDE Architecture

Browser Tab
    ↓
WebSocket Connection
    ↓
Codespace (port 8080)
    ↓
File System & Dev Server

Features

File Management:

File tree navigation
Create, rename, delete files
Multi-file tabs
Drag and drop support

Code Editor:

Monaco Editor (VS Code engine)
Syntax highlighting
Auto-completion
Error detection
Multi-cursor editing

Live Preview:

Real-time preview panel
Auto-refresh on save
Responsive viewport switching
Console for debugging

Terminal Access:

Full bash terminal
Run npm commands
Git operations
Install packages

[screenshot of IDE interface]

Two Editing Modes

Content Editor (Simple)

Focused interface for content creators:

WYSIWYG editor for markdown
Frontmatter editor
Image uploads
Auto-save
No code required

[screenshot of content editor]

Perfect for: Blog posts, pages, content updates

Dev Mode (Advanced)

Full-featured development environment:

Monaco code editor
File tree with all project files
Terminal access
Git integration
Component builder
Media manager

[screenshot of dev mode]

Perfect for: Development, customization, advanced features

Communication Protocol

The IDE uses WebSocket for real-time communication:

// Example message flow
IDE → Codespace: { action: 'read', path: 'src/pages/index.astro' }
Codespace → IDE: { success: true, content: '...' }

IDE → Codespace: { action: 'write', path: '...', content: '...' }
Codespace → IDE: { success: true }

IDE → Codespace: { action: 'terminal', command: 'npm run build' }
Codespace → IDE: { output: '...' }

Auto-Save Feature

Changes are automatically saved:

You type in the editor
After 500ms of inactivity, content is saved
File written to codespace filesystem
Astro dev server detects change
Preview updates automatically

No manual save needed!

Component 5: Vercel Deployment

WP2Astro integrates with Vercel for hosting.

Deployment Flow

1. Connect Vercel Account
   - Authenticate with Vercel
   - Grant repository access
   ↓
2. Setup Deployment
   - Link GitHub repository
   - Configure build settings
   - Set environment variables
   ↓
3. Initial Deploy
   - Vercel builds your site
   - Deploys to global CDN
   - Site goes live (~2-3 minutes)
   ↓
4. Automatic Updates
   - Changes in IDE auto-save
   - Commits pushed to GitHub
   - Vercel detects changes
   - New deployment triggered
   - Site updates (~2 minutes)

[screenshot of Vercel connection modal]

Build Configuration

Vercel automatically detects Astro projects:

// Detected settings
Build Command: npm run build
Output Directory: dist
Install Command: npm install
Node Version: 20.x

Deployment Status

Monitor deployments from the dashboard:

Building: Vercel is compiling your site
Live: Successfully deployed ✓
Failed: Build error (check logs)

[screenshot of deployment status]

How Auto-Deployment Works

You edit a file in the IDE
File auto-saves (500ms debounce)
WP2Astro commits change to GitHub
GitHub webhook notifies Vercel
Vercel pulls latest code
Build runs in Vercel's cloud
New version deployed to CDN

No manual deployment needed!

Optional: WordPress Import

If you choose to import WordPress content, here's what happens:

Import Process

1. Upload WordPress XML Export
   ↓
2. Parse WordPress Data
   - Extract posts, pages, media
   - Parse HTML content
   - Extract metadata
   ↓
3. Transform Content
   - Convert HTML to Markdown
   - Generate frontmatter
   - Process images
   ↓
4. Generate Astro Files
   - Create MDX files in src/content/blog/
   - Copy images to public/
   - Update references
   ↓
5. Commit to Repository
   - Add all generated files
   - Push to GitHub
   - Ready to edit!

What Gets Converted

Posts:

WordPress Post → MDX File
    - Title → frontmatter.title
    - Content → Markdown body
    - Date → frontmatter.publishDate
    - Author → frontmatter.author
    - Categories → frontmatter.categories
    - Tags → frontmatter.tags
    - Featured Image → frontmatter.image

Media:

WordPress Media Library → public/ directory
    - Downloads all images
    - Preserves filenames
    - Updates all references
    - Optimizes for Astro

Pages:

WordPress Page → src/pages/*.astro
    - Converts to Astro pages
    - Maintains hierarchy
    - Updates internal links

Performance Optimizations

WP2Astro applies several optimizations:

Build-Time Optimizations

Static Site Generation: All pages pre-rendered
Image Optimization: Automatic resizing and format conversion
CSS Minification: Smaller stylesheets
JavaScript Bundling: Optimized code splitting
Asset Compression: Gzip/Brotli enabled

Runtime Optimizations

Zero JavaScript: Astro ships minimal JS
Lazy Loading: Images load on scroll
Preloading: Critical resources prioritized
CDN Delivery: Vercel's global edge network

Result

Lighthouse Score: 95-100 typical
First Contentful Paint: < 1 second
Time to Interactive: < 2 seconds
Total Page Size: 50-200 KB typical

Security & Privacy

What We Store

User email and hashed password
GitHub OAuth token (encrypted)
Vercel API token (encrypted)
Project metadata (names, URLs)

What We DON'T Store

GitHub credentials (use OAuth)
WordPress credentials (never requested)
File contents (only in your GitHub repo)
Personal data beyond necessary

Data Flow

All sensitive operations happen securely:

Your Browser → HTTPS → WP2Astro API → HTTPS → GitHub/Vercel

All connections encrypted (TLS 1.3)
Tokens stored encrypted at rest
No plain-text secrets
OAuth for all third-party access

Development vs Production

Development (Codespace)

Runs Astro dev server (npm run dev)
Hot module replacement enabled
Fast rebuilds (50-200ms)
Source maps for debugging
Not optimized for size

Production (Vercel)

Static HTML generated (npm run build)
Fully optimized assets
Minified and compressed
Image optimization applied
Global CDN distribution

Comparison to Traditional Development

Traditional Way

Install Node.js → Install npm → Clone repo → npm install →
Configure environment → Run dev server → Make changes →
Commit → Push → Setup deployment → Deploy

Time: 30-60 minutes to setup Requirements: Local machine, technical knowledge

WP2Astro Way

Sign up → Connect GitHub → Create project → Start editing

Time: 5 minutes to start Requirements: Just a browser

Next Steps

Now that you understand the architecture:

Learn about the IDE features
Explore Content Migration (optional)
Setup Vercel Deployment
Dive into Advanced Features

Technical Resources

For developers who want to go deeper:

Quick Start

Content Migration