Phase B: Headless CMS + Unified Frontend Architecture

Status: Pending Phase A completion
Timeline: 6-9 months
Risk Level: MEDIUM
Budget: [Budget TBD] (freelance) or team composition based on client needs Prerequisites: Phase A completed

📋 Quick Reference

Executive Summary
Phase B Overview
Planning & Architecture
Technology Stack
Deployment Strategy
API Contracts
Budget & Cost Breakdown
Infrastructure Costs
Dependencies & Assumptions
Out of Scope (Phase B)
Risks & Mitigations (Phase B)
Acceptance Criteria (Definition of Done)
KPIs & Targets
Milestones and Go/No-Go Gates
Roles & Responsibilities (RACI)
Document Updates

Executive Summary

Decouple presentation from WordPress by introducing a Turborepo monorepo with Next.js (web) and Expo (mobile) sharing TypeScript packages, powered by a Laravel API adapter. Maintain the WordPress CMS while achieving ~70% code reuse, improved performance (API p95 < 200ms; web LCP < 2s), and mobile reach.

Phase B Overview

Goal: Decouple frontend from WordPress while keeping WordPress as the content management system. Build modern web and mobile applications that consume content via APIs.

Why This Phase?

Modern user experience across all platforms
Better performance (SSG/ISR with Next.js)
Mobile apps (iOS/Android) from single codebase
API-first architecture
Validate headless approach before full migration
WordPress still familiar to editorial team

What Changes:

New web frontend (React/Next.js)
New mobile apps (Expo + React Native)
Laravel API layer
WordPress becomes content-only
Progressive rollout possible

What Stays the Same:

WordPress admin interface
Editorial workflow
Content structure
Content in WordPress database

Planning & Architecture

Technical Architecture Decision

Technology	Pros	Cons	Recommendation
Next.js (React)	SEO-friendly (SSR/SSG), Large ecosystem, ISR for dynamic content	Learning curve, Complex setup	⭐ RECOMMENDED for web
Expo + React Native	JavaScript, Code sharing with web, Large ecosystem	Performance issues, Native modules	⭐ RECOMMENDED for mobile

Monorepo Strategy: Next.js + Expo with Shared Packages

Why This Architecture?

✅ Best of Both Worlds: Next.js SSR/SEO for web + Native mobile performance
✅ Maximum Code Reuse: Share API clients, types, utilities, and UI components (70-80%)
✅ TypeScript Everywhere: Type-safe across all platforms
✅ Tailwind CSS: Consistent styling with Tailwind (web) and NativeWind (mobile)
✅ Custom Data Fetching: RTK Query-inspired implementation for full control
✅ Independent Optimization: Each platform optimized without compromise

Stack Overview

TURBOREPO MONOREPO:
┌─────────────────────────────────────────────────────────────┐
│  apps/                                                      │
│  ├── web/          (Next.js 14+ App Router)                 │
│  │   ├── SSR/SSG for SEO                                    │
│  │   ├── Tailwind CSS                                       │
│  │   └── Deploys to Vercel                                  │
│  │                                                          │
│  └── mobile/       (Expo + React Native)                    │
│      ├── iOS/Android native apps                            │
│      ├── PWA for mobile web                                 │
│      ├── NativeWind (Tailwind)                              │
│      └── Deploys via EAS                                    │
├─────────────────────────────────────────────────────────────┤
│  packages/         (Shared Code - Module-Based)             │
│  ├── global/        → Global utilities, hooks, store       │
│  ├── auth/          → Authentication & authorization       │
│  ├── blog/          → Blog content & comments              │
│  └── media/         → Media management                      │
└─────────────────────────────────────────────────────────────┘
              ↓
    Laravel API (WordPress as headless CMS)

Framework Comparison

Approach	Pros	Cons	Decision
Turborepo Monorepo (Next.js + Expo)	Next.js SSR/SEO, Native mobile perf, Share code via modules, TypeScript everywhere, Independent optimization	Slightly more setup	⭐ SELECTED
Single Expo App (Web + Mobile)	One codebase	Poor SEO, Limited web optimization, No SSR	❌ Not suitable
Separate Repos	Complete independence	Code duplication, Harder to maintain	❌ Too much duplication
Native Apps Only	Best performance	No code sharing, 3x dev time	❌ Too expensive

Module Responsibility Structure

Module Type	Scope	Contents	Location
Global Module	Cross-cutting concerns	Global utilities, hooks, store, styles	`packages/global/`
Auth Module	Authentication	Auth API, hooks, providers, utilities	`packages/auth/`
Blog Module	Content management	Blog API, components, types, utils	`packages/blog/`
Media Module	Media management	Media API, file handling	`packages/media/`

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    CONTENT LAYER                            │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │          WordPress (Headless CMS)                    │   │
│  │  - Admin interface                                   │   │
│  │  - Content creation                                  │   │
│  │  - Media management                                  │   │
│  │  - User management                                   │   │
│  └───────────────────┬──────────────────────────────────┘   │
└────────────────────────┼────────────────────────────────────┘
                         │ Direct Integration (Acorn)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  APPLICATION LAYER                          │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Laravel API Gateway                     │   │
│  │  - Business logic                                    │   │
│  │  - Analytics                                         │   │
│  │  - Caching                                           │   │
│  └──────────────────────┬───────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────┘
                          │ JSON REST API
              ┌───────────┼───────────┬─────────────┐
              │           │           │             │
              ▼           ▼           ▼             ▼
      ┌──────────┐  ┌──────────┐  ┌────────┐  ┌─────────┐
      │   Next   │  │  Expo    │  │  iOS   │  │ Android │
      │   Web    │  │  Mobile  │  │  App   │  │   App   │
      └──────────┘  └──────────┘  └────────┘  └─────────┘

Technology Stack

Backend Architecture

Laravel (Acorn): Tightly coupled with WordPress backend
WordPress as Headless CMS: Content management and publishing only
Redis caching: For performance optimization
Direct Database Access: Seamless integration with WordPress data

Web Frontend (Next.js)

Framework: Next.js 14+ with App Router
Styling: Tailwind CSS
Data Handling: Optimized fetching strategies
SEO: Comprehensive metadata management

Mobile (Expo + React Native)

Framework: Expo + React Native
Native Features: Push notifications, offline support
UI Consistency: Shared design system with web

Deployment Strategy

See: Infrastructure & DevOps

Web (Vercel): preview deployments for PRs, prod on main merge
API (Laravel): CI (lint, unit, feature), deploy to staging, E2E, manual prod gate
Mobile (Expo EAS): release channels, OTA updates for minor fixes

API Contracts

OpenAPI spec: api/openapi.yaml
Postman: api/postman_collection.json
Browser viewer: api/index.html
Versioning: URL-based (/api/v1), 6-month deprecation policy
Rate limiting: 100 rpm public, 300 rpm authenticated

Budget & Cost Breakdown

Role	Hours	Rate	Notes
Senior Backend Developer	480	[TBD]	[TBD]
Senior Frontend Developer	560	[TBD]	[TBD]
Mobile Developer	640	[TBD]	[TBD]
DevOps Engineer	160	[TBD]	[TBD]
QA Engineer	240	[TBD]	[TBD]
Project Manager	320	[TBD]	[TBD]
Total Budget			[Budget TBD]

Infrastructure costs: [Client-specific infrastructure cost]/mo (varies based on scale and requirements)

Production Builds

Using EAS (Expo Application Services):

iOS and Android native app builds
Automated App Store and Play Store submission
OTA updates without app store review
Cost: [Client-specific infrastructure cost]/month (EAS subscription)

Web Deployment (Vercel):

Automatic deployments from Git
Preview deployments for PRs
Edge functions and serverless functions
Analytics and performance monitoring
Cost: [Client-specific infrastructure cost]/month (Hobby plan)

Infrastructure Costs

Total Monthly Cost: [Client-specific infrastructure cost]/mo

Vercel (web): [Client-specific cost]
EAS (mobile builds): [Client-specific cost]
Laravel API hosting: [Client-specific cost]

Dependencies & Assumptions

Phase A completed and stable for ≥ 2 months
WordPress remains content source; no content migration
API endpoints conform to OpenAPI spec
Team capacity available (backend + web + mobile)

Out of Scope (Phase B)

Full Laravel CMS replacement
Editorial admin changes
Large-scale content migrations

Risks & Mitigations (Phase B)

Risk	Likelihood	Impact	Mitigation
WordPress API latency	Medium	Medium	Aggressive caching (Redis), edge caching
Mobile complexity	Medium	Medium	Ship minimal viable features first; OTA updates
SEO changes (web)	Low	High	SSR/ISR, pre-launch SEO checks, sitemaps
API instability	Medium	Medium	Contract-first (OpenAPI), contract tests

Acceptance Criteria (Definition of Done)

API endpoints deployed and validated against OpenAPI contract
Next.js site deployed with SSR/ISR and SEO metadata passing checks
Expo apps built; basic flows (browse, article, search) work on iOS/Android
Shared packages (global, auth, blog, media) in monorepo with ~70% reuse
Monitoring in place (APM, error tracking) with baseline SLOs

KPIs & Targets

API p95 latency: < 200ms
Web LCP: < 2.0s on 4G/slow CPU
Mobile TTI: < 3.0s (cold start)
Cache hit ratio: > 80%
Session duration: > 3 minutes

Milestones and Go/No-Go Gates

Timeline Snapshot (9 months)

M1-2 : Architecture & Planning      [########]
M2-5 : Laravel API                   [######################]
M3-6 : Next.js Web                   [######################]
M4-7 : Expo Mobile                   [######################]
M7-8 : Integration & E2E             [########]
M8-9 : Beta & Launch                 [########]

Go/No-Go Gates

End of M2: Architecture approved + API contracts frozen
End of M5: API feature-complete + staging reliability
End of M8: E2E pass + SLOs met (go for beta)

Roles & Responsibilities (RACI)

Deliverable	Responsible	Accountable	Consulted	Informed
API Adapter & Services	Backend Dev	Tech Lead	DevOps, QA	PM
Web App (Next.js)	Frontend Dev	Tech Lead	Designer, QA	PM
Mobile App (Expo)	Mobile Dev	Tech Lead	Backend, QA	PM
Shared Packages	Frontend/Mobile	Tech Lead	Backend	PM
Observability & CI/CD	DevOps	Tech Lead	Backend/Frontend	PM

Document Updates

Date	Version	Changes	Author
2025-10-09	1.1	Added risks, acceptance, KPIs sections	AI Assistant
2025-10-09	1.0	Initial Phase B documentation	AI Assistant

Redis cache: [Client-specific infrastructure cost]
CDN: [Client-specific infrastructure cost]
Push notifications: Included with Expo

Alternative Approaches Comparison

Native vs Cross-Platform

Approach	Development Time	Code Reuse	Team Size Needed
Native Apps (Swift + Kotlin)	2-3x longer	0% (separate codebases)	2-3 developers
React Native + Expo	1x	70-80% (single codebase)	1-2 developers
Web Only (PWA)	0.5x	N/A	1 developer

React Native + Expo Benefits

Feature	Benefit
Development	iOS + Android + Web from one codebase
Team Learning Curve	JavaScript/TypeScript (existing skill)
Code Sharing	High (types, utils, API client, components)
OTA Updates	Built-in (Expo Updates)
App Store Submission	Automated (EAS Submit)
Web Support	Excellent (production-ready PWA)

Key Advantages (70-80% Code Reuse)

1. Best SEO

Next.js SSR/SSG ensures optimal Google rankings

2. Maximum Code Reuse (70-80%)

70-80% shared via TypeScript modules including types, utilities, API clients, and business logic

3. Single Language Stack

Backend: PHP (Laravel)
Web: TypeScript (Expo Web PWA)
Mobile: TypeScript (React Native + Expo)
All JavaScript/TypeScript - no context switching

4. Team Efficiency

React developers work on web and mobile independently
Share components where possible
Faster onboarding for new developers
Single skill set for entire frontend

5. Ecosystem

npm packages work (mostly)
React ecosystem is huge
More Stack Overflow answers
Active community support

Timeline

Month 1-2: Foundation

Set up Turborepo monorepo structure
Configure shared packages
Establish development workflows
Implement core API endpoints

Month 2-4: Web Application

Build Next.js page templates
Implement SSR/ISR strategies
Develop component library
Optimize for SEO and performance

Month 4-6: Mobile Application

Create Expo app structure
Implement native features
Develop shared UI components
Setup push notifications

Month 6-7: Testing & QA

Comprehensive functional testing
Performance benchmarking
Accessibility validation
Cross-platform compatibility

Month 7-8: Deployment

Staging environment setup
Gradual rollout strategy
Monitoring configuration
Editorial team training

Success Metrics

Technical Targets

API Response Time: < 200ms (p95)
Web Page Load: < 2s (LCP)
Mobile App Launch: < 3s
Cache Hit Rate: > 80%
Test Coverage: > 70%

User Experience Targets

Session Duration: > 3 minutes
Bounce Rate: < 50%
Mobile App Rating: > 4.5 stars
Return Users: > 40%

Business Targets

Maintain SEO rankings
Increase newsletter signups by 20%
Grow mobile traffic share by 30%
Maintain ad revenue during transition

Editorial Workflow

Content Management

WordPress remains editorial interface
No changes to publishing process
Existing plugins and workflows preserved
Media management unchanged

Training Requirements

Basic API concept overview
Frontend preview capabilities
Analytics dashboard orientation
Troubleshooting common issues

Phase B Deliverables

✅ Laravel API Layer

Business logic encapsulation
Analytics integration
Caching implementation
Direct WordPress integration

✅ Next.js Web Application

Modern responsive frontend
SEO-optimized page templates
Performance budget compliance
Progressive enhancement strategy

✅ Expo Mobile Applications

iOS native app
Android native app
Push notification system
Offline content support

✅ Operational Foundation

Deployment pipelines
Monitoring setup
Documentation suite
Training materials

Risks & Mitigation

Risk	Mitigation Strategy
WordPress integration complexity	Leverage Acorn for tight coupling
Editorial team disruption	Maintain WordPress CMS unchanged
Mobile app store rejection	Strict guideline compliance
Performance bottlenecks	Aggressive caching strategy
Budget overruns	Phase-based delivery approach

Last Updated: 2025-10-09