Multi-Frontend FraiseQL Blog Platform

A comprehensive reference implementation showcasing FraiseQL's capabilities across 6 different frontend frameworks in a single monorepo.

Project Status: Phase 1 - Monorepo Foundation IN PROGRESS ✓

Current Progress: Phase 1 - 75% complete (9/12 cycles done) Timeline: Completing Phase 1 by end of Day 6 Critical Blockers (CR-1-4): All resolved ✓

This repository uses phase-based development with TDD cycles. Infrastructure is being built sequentially with detailed planning.

👉 See .phases/README.md for the complete implementation plan 👉 See PHASE-1-PROGRESS.md for current Phase 1 status 👉 See MONOREPO-QUICK-START.md for developer setup

Planned Features

• ✅ 6 Frontend Frameworks: React, Vue, Svelte, Astro, Angular, Vanilla HTML/CSS/JS
• ✅ FraiseQL Backend: Full GraphQL API with Keycloak OAuth/OIDC
• ✅ Real Data: 10K blog posts, users, and comments from velocitybench
• ✅ Dual-Pane UI: Left side shows blog interface, right side shows:
  • GraphQL query inspector
  • Real-time Cascade invalidation visualization
• ✅ Authentication: Keycloak integration with 6 OAuth providers
• ✅ E2E Testing: Unified Playwright test suite across all 6 apps
• ✅ Production Deployment: All frontends + backend live at unique domains

Project Structure

fraiseql-blog/
├── .phases/                  # Implementation phases (TDD cycles)
│   ├── README.md
│   ├── phase-01-monorepo-foundation.md
│   ├── phase-02-backend-api.md
│   ├── phase-03-shared-packages.md
│   ├── phase-04-frontend-implementations.md
│   ├── phase-05-e2e-testing.md
│   ├── phase-06-deployment.md
│   ├── phase-07-documentation.md
│   └── phase-08-finalize.md
│
├── apps/                     # Frontend applications (6 frameworks)
│   ├── react-blog/
│   ├── vue-blog/
│   ├── svelte-blog/
│   ├── astro-blog/
│   ├── angular-blog/
│   └── vanilla-blog/
│
├── packages/                 # Shared packages
│   ├── shared-types/         # GraphQL generated types
│   ├── shared-graphql/       # URQL client + queries/mutations
│   ├── shared-config/        # TypeScript, ESLint, Vite configs
│   └── test-utils/           # Playwright page objects
│
├── e2e/                      # E2E test suite
│   ├── tests/
│   ├── fixtures/
│   └── playwright.config.ts
│
└── docs/                     # (To be created during Phase 7)
    ├── ARCHITECTURE.md
    ├── API.md
    ├── adr/                  # Architecture Decision Records
    └── frontends/            # Framework-specific guides

Technology Stack

• Monorepo: pnpm + Turborepo
• Package Manager: Bun (for speed)
• Build Tool: Vite (all frameworks)
• GraphQL Client: URQL (12KB, framework-agnostic)
• Testing: Playwright (unified E2E tests)
• Styling: Tailwind CSS (consistent across all apps)
• Backend: FraiseQL (with Keycloak)
• Database: PostgreSQL
• CI/CD: GitHub Actions + Turborepo caching

Quick Start (After Phase 1)

# Install dependencies
bun install

# Start all dev servers
pnpm dev

# Start single app
pnpm dev:react   # or :vue, :svelte, :astro, :angular, :vanilla

# Run tests
pnpm test         # All tests
pnpm test:e2e     # E2E tests only

# Build all apps
pnpm build

# Lint all packages
pnpm lint

Implementation Timeline

Sequential phases for focused development:

1. Phase 1: Monorepo Foundation (1 week)
2. Phase 2: Backend API & Keycloak (2 weeks, parallel with Phase 1)
3. Phase 3: Shared Packages (4 days)
4. Phase 4: Frontend Implementations (3 weeks, sequential)
   • React (4 days)
   • Vue (4 days)
   • Svelte (3 days)
   • Astro (3 days)
   • Angular (4 days)
   • Vanilla (3 days)
5. Phase 5: E2E Testing (1 week)
6. Phase 6: Deployment (3-5 days)
7. Phase 7: Documentation (1 week)
8. Phase 8: Finalize (1 week)

Total: 6-8 weeks

Key Design Decisions

Why these 6 frameworks?

• React: Most popular, reference implementation
• Vue: Progressive enhancement, gentle learning curve
• Svelte: Truly reactive, compiler-based
• Astro: Static-first, islands architecture
• Angular: Opinionated, enterprise-scale
• Vanilla: Framework-agnostic foundation

Why URQL?

• 12KB bundle (vs Apollo 39KB)
• Framework-agnostic with adapters for all 5 frameworks
• Excellent DevX with normalized caching
• Simple to understand and extend

Why Playwright?

• Unified test suite across all frameworks
• Better parallelization than Cypress
• Excellent DevX with headed debugging
• Strong trace/screenshot capabilities

Dual-Pane Inspector Feature

The unique Cascade Invalidation Visualization shows:

Left Pane: Normal blog interface

• Post list or post detail
• Comments section
• Forms for creating/editing

Right Pane - Section 1: GraphQL Inspector

• Last executed query/mutation
• Query variables
• Response JSON with syntax highlighting
• Execution time

Right Pane - Section 2: Cascade Visualization

• Animated flow showing:
  1. User action (create comment)
  2. GraphQL mutation sent
  3. Server-side effects
  4. Cache invalidation cascades
  5. Dependent queries invalidated
  6. UI re-renders with new data
• Real-time performance metrics

This demonstrates FraiseQL's power in cache management and query optimization.

Architecture Overview

User Interaction
    ↓
App UI (React/Vue/Svelte/Astro/Angular/Vanilla)
    ↓
URQL GraphQL Client
    ↓
Dual-Pane Inspector (captures request)
    ↓
FraiseQL Server
    ├── GraphQL Resolver
    ├── Keycloak Auth
    └── Cascade Invalidation Tracker
    ↓
PostgreSQL Database
    ↓
Response → Cascade Visualization
    ↓
Cache Update → UI Re-render

Monorepo Benefits

• Code Reuse: Shared GraphQL queries, mutations, types
• Consistent Testing: One E2E test suite for all 6 apps
• Shared Configuration: ESLint, TypeScript, Vite configs
• Efficient Building: Turborepo caching, parallel builds
• Developer Experience: pnpm dev starts all apps
• Easy Onboarding: New devs see all patterns in one place

Contributing

See CONTRIBUTING.md (created in Phase 7) for guidelines.

Documentation

• Setup: See .phases/README.md and individual phase files
• API: See future docs/API.md (Phase 7)
• Frameworks: See docs/frontends/ (Phase 7)
• Architecture: See docs/ARCHITECTURE.md (Phase 7)

License

Apache 2.0 - See LICENSE file

Status

• Phase planning complete
• Phase 1: Monorepo Foundation
• Phase 2: Backend API & Keycloak
• Phase 3: Shared Packages
• Phase 4: Frontend Implementations
• Phase 5: E2E Testing
• Phase 6: Deployment
• Phase 7: Documentation
• Phase 8: Finalization

Ready to start? See .phases/phase-01-monorepo-foundation.md for the first phase details.