EPIC: Complete Migration from Fresh (web) to SolidStart (web-next)

[dahlia]

Overview

Hackers' Pub is currently transitioning from a Fresh + Preact stack (web/) to a modern SolidStart + Solid.js + GraphQL + Relay stack (web-next/). While basic pages like profiles and some settings have been implemented in web-next, the majority of functionality still resides in the legacy web implementation.

This EPIC tracks the complete migration of all pages and functionality from web/ to web-next/ while maintaining URL compatibility and feature parity.

Goals

• Migrate all existing pages from Fresh to SolidStart
• Maintain complete URL compatibility
• Achieve feature parity with the legacy implementation
• Implement proper GraphQL + Relay integration for all data fetching
• Maintain internationalization support using Lingui
• Ensure all functionality works seamlessly in the new stack

Migration Status

✅ Already Implemented

• User profiles (/@username)
• Profile sub-pages (articles, notes, shares, followers)
• Basic settings pages
• Authentication (sign in/up)
• Home page
• Static pages (CoC, markdown guide)
• Notifications page

🔄 In Progress

• Following page (/@username/following)

❌ Needs Migration

Core Content Pages

• Post/Article Detail Pages
  • /@username/[idOrYear]/[slug]/index — Post detail view
  • /@username/[idOrYear]/[slug]/edit — Post editing
  • /@username/[idOrYear]/[slug]/reactions — Post reactions
  • /@username/[idOrYear]/[slug]/shares — Post shares
  • /@username/[idOrYear]/[slug]/quotes — Post quotes
  • /@username/[idOrYear]/index — Year/ID based post listing

Draft Management

• Draft System
  • /@username/drafts — Draft listing
  • /@username/drafts/[draftId] — Draft detail/edit
  • Draft creation and publishing workflow

Social Features

• User Interactions
  • Follow/Unfollow functionality
  • Block/Unblock functionality
  • Post reactions (like, dislike, etc.)
  • Post sharing and unsharing
  • Quote posts functionality

Search & Discovery

• Search System
  • /search — Global search page
  • /tags/[tag] — Tag-based content discovery: web-next: Implement /tags/[tag] #140
  • Search functionality integration

Administrative

• Admin Panel
  • /admin — Admin dashboard
  • /admin/invitations — Invitation management

Settings (Extended)

• Advanced Settings
  • /@username/settings/invite — Invite management: web-next: Invitations in the settings #145
  • /@username/settings/language — Language preferences
  • /@username/settings/passkeys — Passkey authentication: web-next: migrate passkey feature #141
    • Passkey management interface
    • Passkey creation/verification
    • Passkey revocation

Invitation System

• Invite Management
  • /@username/invite — Invite generation
  • /@username/invite/[id] — Specific invite management
  • Invite deletion functionality

Open Graph Images

• OG Image Generation
  • /@username/og — User profile OG images
    • User avatar integration
    • Bio text rendering with markup support
    • Multi-language text support
  • /@username/[idOrYear]/[slug]/ogimage — Article/Post OG images
    • Article title and content preview
    • Author information display
    • Multi-language content support
    • Language-specific OG images (?l=lang parameter)
  • OG Image Infrastructure
    • Satori HTML-to-SVG conversion
    • Resvg SVG-to-PNG rendering
    • Multi-language font loading (Noto Sans family)
    • Content-based caching with SHA-256 hashing
    • Drive/storage integration for image persistence
    • GraphQL integration for OG image URLs

GraphQL Integration

• REST API → GraphQL Migration
  • Post/Article Data: Replace /api/posts/* endpoints with GraphQL queries/mutations
    • Post lookup by IRI (ActivityPub integration)
    • Post media handling
    • Poll/voting system
    • Article content retrieval
  • User Interactions: Replace /api/mention with GraphQL
    • User mention autocomplete/typeahead
    • Actor search functionality
  • Content Processing: Replace /api/preview with GraphQL
    • Markup preview rendering
    • Real-time content processing

Backend Services (Non-GraphQL)

• RSS/Atom Feeds
  • /@username/feed.xml — User RSS feeds
  • /@username/feed.xml?articles — Article-only feeds
  • Feed generation with proper caching
• SEO Services
  • /robots.txt — Search engine crawler rules
  • /sitemaps.xml — Automatic sitemap generation
  • SEO metadata optimization

Specialized Pages

• Community Features
  • Invitation Tree (/tree)
    • Display hierarchical invitation relationships
    • Show user avatars, names, and usernames in tree structure
    • Include invitation count for each user
    • Support privacy setting to hide from invitation tree
    • Implement tree visualization with proper CSS styling
    • Handle users who opted out of the tree display
    • Sort users chronologically by account creation
    • GraphQL schema for invitation relationships
    • Mutation for toggling hideFromInvitationTree setting
  • Multi-language post support (/@username/[idOrYear]/[slug]/[lang])

Technical Requirements

GraphQL Schema

• Define comprehensive GraphQL schema for all entities
• Implement Relay-compatible pagination
• Add proper authentication/authorization
• Support for real-time updates where applicable

Data Migration

• Ensure all existing data remains accessible
• Maintain backward compatibility for URLs
• Preserve SEO rankings and external links

Performance & UX

• Implement proper loading states
• Add error boundaries and error handling
• Ensure mobile responsiveness
• Maintain or improve page load performance

Testing

• Unit tests for all new components
• Integration tests for critical user flows
• E2E tests for complete user journeys
• Accessibility testing compliance

Success Criteria

1. Functional Parity: All features available in web/ are replicated in web-next/
2. URL Compatibility: All existing URLs continue to work without redirects
3. Performance: Page load times are equal to or better than legacy implementation
4. Accessibility: Maintains or improves accessibility standards
5. SEO: No degradation in search engine rankings
6. User Experience: Seamless transition for existing users

Timeline

This migration should be completed in phases, with each major feature area tackled as a separate milestone. Priority should be given to:

1. Phase 1: Core content pages (posts, articles)
2. Phase 2: Social features and interactions
3. Phase 3: Administrative and advanced features
4. Phase 4: GraphQL integration and backend services
5. Phase 5: SEO, feeds, and optimization

Definition of Done

• All URLs from legacy web/ implementation work in web-next/
• Feature parity achieved across all pages
• GraphQL schema supports all data requirements
• Internationalization works for all migrated pages
• Performance benchmarks meet or exceed legacy implementation
• All tests pass (unit, integration, E2E)
• Documentation updated for new stack
• Legacy web/ directory can be safely removed