Eternity - Personal Website Monorepo

Project Introduction

Eternity is a personal website monorepo built on Astro and Cloudflare edge infrastructure. It consists of two sub-applications — a main portfolio site and a world-lore documentation site — managed through pnpm workspaces and Turborepo, deployed entirely on Cloudflare Pages and Workers.

Core Philosophy

• Edge-First Architecture: All content served from Cloudflare's edge network (D1, R2, KV) for global low-latency access

• Content Ownership: Full admin editor with TipTap rich text, eliminating dependency on third-party CMS

• World-Building as Documentation: The documentation site doubles as an interactive world-lore experience with zone-based navigation, 3D maps, and atmospheric effects

My Responsibilities

As the sole developer of the project, I am responsible for:

System Architecture Design

• Designed monorepo structure with two Astro apps, two Cloudflare Workers, and shared packages

• Architected D1 database schema for both sites (pages with hierarchical depth, root content tables, sync logs)

• Designed bidirectional content sync pipeline between local and remote D1 instances

Core Feature Implementation

• Main Site: Full portfolio site with projects, updates, links, about/contact pages, and i18n (zh-tw/en)

• Documentation Site: Six-zone world-lore reader (history, echoes, visuals, concepts, storage, portal) with specialized readers per zone

• Admin Editor: TipTap-based three-column editor (entry list | editor | inspector) for both sites

• Asset Management: Isolated R2 buckets per site with media library, image picker, and upload pipeline

• Content Sync: Bidirectional D1 sync with conflict detection, soft-delete propagation, and R2 asset synchronization

Design System

• Implemented dual-theme system (Quartz for main site, zone-specific themes for documentation site)

• Built interactive elements: 3D pie map, portal transitions, zone atmospheres, boot animations

• Zone-specific background effects: text particles (history), echo ripples (echoes), light pillars (visuals), digital rain (concepts)

Core Features

1. Dual-Site Monorepo Architecture

• apps/root (Main Site): Astro 5.x + React + Tailwind, static output with SSR admin pages (port 4320)

• apps/uep (Documentation Site): Astro 4.x + React + MDX, hybrid SSR + static output (port 4321)

• packages/config: Shared ESLint, Prettier, TypeScript, Tailwind configuration

• packages/ui: Shared UI components

2. Cloudflare Edge Data Layer

• D1 Database (eternity-content): Hierarchical page tables with parent_id/depth/page_type, plus 5 root content tables

• R2 Storage: Two isolated buckets — eternity-assets (docs site) and eternity-root-assets (main site)

• KV Storage (VISITOR_STATS): Visitor counter with per-page tracking

• content-api Worker: Full CRUD REST API with JWT authentication for write operations

3. Zone-Based Reader System

• Six zones with specialized React readers: HistoryReader, EchoesReader, VisualsReader, ConceptsReader, StorageReader

• Each zone has unique visual identity: custom transitions, background effects, boot animations

• Shared primitives: ReaderShell, ZoneStateDisplay, ZonePrevNext, contentVisibility, useZoneRouter

4. TipTap Admin Editor

• Three-column layout: entry tree sidebar, rich text editor, metadata inspector

• Mode-based dispatch: different editor bodies per zone/page type (echoes songs, visuals galleries, concepts structured data)

• Media library with R2 integration, image picker dialog, drag-and-drop support

5. Content Sync Pipeline

• pnpm sync — Interactive mode with diff preview and per-item confirmation

• pnpm sync:push / pnpm sync:pull — Batch sync with conflict resolution

• R2 asset sync with soft-delete tracking via deleted_assets table

• Area-scoped sync: --area history for selective synchronization

6. Internationalization

• Main site supports zh-tw (default) and en with pathname-based routing

• Localized content stored in D1, served through unified API layer

Technologies Used

Frontend

• Astro 5.x / 4.x: Static site generation with hybrid SSR

• React: Interactive components (readers, editors, maps)

• Tailwind CSS: Utility-first styling with custom design tokens

• TipTap: Rich text editor with custom extensions (dialogue nodes, page links)

• MDX: Markdown with embedded components for documentation

Backend / Infrastructure

• Cloudflare Workers: Edge-deployed API servers

• Cloudflare D1: SQLite-compatible edge database

• Cloudflare R2: S3-compatible object storage

• Cloudflare KV: Key-value store for visitor statistics

• Resend API: Transactional email for contact form

Build & Development

• Turborepo: Monorepo build orchestration

• pnpm Workspaces: Package management with workspace protocol

• Vitest: Unit and worker integration testing

• Playwright: E2E and stress testing

• GitHub Actions: CI/CD with automated tagging and deployment

Project Status

Current Version: v0.9.8-stable

• Main Site: Fully functional with admin editor, projects/updates/links management, i18n

• Documentation Site: All six zones implemented with specialized readers and editors

• Content API: Production-deployed with JWT auth, R2 asset management, sync endpoints

Testing Status

• Unit tests (Vitest) for frontend components and worker logic

• E2E smoke tests (Playwright) for critical user flows

• Stress and performance threshold tests

• Load testing for both local and staging environments

Development Challenges & Achievements

1. CMS Migration: From Keystatic to D1

Challenge: The original main site used Keystatic (file-based CMS), which created friction with Cloudflare deployment and couldn't support real-time editing.

Solution: Migrated entirely to Cloudflare D1 with a custom content-api Worker, building a full admin editor from scratch.

Achievements:

• Complete content ownership without third-party CMS dependency

• Real-time editing with live preview

• Bidirectional sync between local development and production

2. Zone-Specific Reader Architecture

Challenge: Each documentation zone (history, echoes, visuals, concepts, storage) has fundamentally different content models — prose, music, galleries, structured data, collections.

Solution: Built specialized readers per zone while extracting shared navigation primitives (ReaderShell, ZonePrevNext, useZoneRouter) to maintain consistency.

Achievements:

• Each zone maintains its unique reading experience

• Shared URL state management and transition system

• Unified admin editor with mode-based dispatch

3. Edge-First Data Architecture

Challenge: Traditional server-rendered sites suffer from cold start latency. Content needed to be globally available with minimal latency.

Solution: Deployed entire data layer on Cloudflare's edge (D1 + R2 + KV), with Workers handling API logic at the edge.

Achievements:

• Sub-100ms API response times globally

• Zero-cost static hosting for main site pages

• Isolated R2 buckets preventing cross-site asset contamination

4. Content Sync System

Challenge: Development requires local D1 access, but production data lives in remote D1. Changes need to flow both directions without conflicts.

Solution: Built a comprehensive sync system with diff detection, timestamp-based conflict resolution, soft-delete propagation, and R2 asset tracking.

Achievements:

• Interactive sync mode with per-item confirmation

• Area-scoped sync for targeted updates

• Deleted asset tracking preventing resurrection of removed files

Future Roadmap

Short-term Goals

• Interactive embeds in history content (entity marks, cross-zone references)

• Island runtime for floating interactive panels

Mid-term Goals

• Full-site search with command palette (Ctrl+K)

• Reading progress tracking and chapter gating

• Cross-zone music playlist

Long-term Goals

• Public beta release (v1.0.0)

• Plugin ecosystem for zone extensions

• Mobile-optimized reading experience

Project Highlights

Technical Innovation

• ✅ Edge-first architecture with Cloudflare D1/R2/KV as sole data layer

• ✅ Bidirectional content sync between local and remote D1 instances

• ✅ Zone-specific reader system with shared navigation primitives

Design Achievement

• ✅ Immersive world-building documentation with 3D maps and atmospheric effects

• ✅ Six unique zone experiences (text particles, echo ripples, light pillars, digital rain)

• ✅ Dual design system: Quartz (main site) + zone-specific themes (docs site)

Development Quality

• ✅ Comprehensive monorepo tooling (Turborepo + pnpm workspaces)

• ✅ Multi-layer testing (unit, worker integration, E2E, stress, load)

• ✅ CI/CD with automated tagging, sync-back, and deployment

Tech Stack: Astro, React, TypeScript, Tailwind CSS, Cloudflare Workers/D1/R2/KV, TipTap, Turborepo Monorepo Structure: 2 apps + 2 workers + 2 shared packages Deployment: Cloudflare Pages (4 projects) + Cloudflare Workers (2 services)