summercms-initial-research/.planning/research/SUMMARY.md

Project Research Summary

Project: SummerCMS - Scala/ZIO rewrite of WinterCMS Domain: Content Management Framework (CMF) Researched: 2026-02-04 Confidence: HIGH

Executive Summary

SummerCMS aims to rewrite WinterCMS, a mature PHP CMF, using Scala 3 and the ZIO ecosystem. Research confirms this is architecturally sound: ZIO HTTP 3.x, Quill 4.8.6, and Mill 1.0 provide a production-ready foundation for building a type-safe, high-performance CMF. The plugin architecture pattern from WinterCMS is well-understood and translates cleanly to ZIO's layer-based dependency injection.

The recommended approach follows WinterCMS's core patterns (plugin dependencies via manifests, YAML-driven backend forms, component-based frontend) while leveraging Scala's type safety to eliminate entire classes of runtime errors. ScalaTags + HTMX replaces WinterCMS's problematic Snowboard/Alpine.js frontend, providing server-rendered HTML with progressive enhancement. The ZIO effect system's compile-time guarantees ensure plugin interdependencies and database queries are validated before deployment.

Key risks are manageable but must be addressed explicitly: The most dangerous pitfall is the "Big Rewrite Anti-Pattern" - attempting full WinterCMS parity before shipping. Research shows successful rewrites deliver value in vertical slices rather than horizontal layers. Additional risks include ZIO's learning curve for PHP developers (40.5% onboarding slowdown), Quill compile-time explosion with large query counts, and plugin API lock-in if the extension mechanism is finalized before building real plugins. Mitigation strategies include freezing WinterCMS reference version, defining MVP as "build a new site" not "full parity," and building 3-5 diverse plugins before finalizing the plugin API.

Key Findings

Recommended Stack

The ZIO ecosystem has matured significantly in 2025-2026. All major dependencies have reached stable 1.0+ releases with production deployment patterns well-documented. The stack prioritizes developer experience and compile-time safety over bleeding-edge features.

Core technologies:

• Scala 3.3.7 LTS (language) - LTS stability for multi-year project, not bleeding-edge 3.8.x which requires newer JDKs
• ZIO 2.1.24 (effect system) - Binary compatibility guarantees in 2.x critical for plugin ecosystem; typed errors eliminate WinterCMS's exception chaos
• ZIO HTTP 3.8.1 (HTTP server) - Production-ready, Netty-based, native ZIO integration with OpenAPI generation for plugin APIs
• Quill 4.8.6 (database) - Compile-time SQL validation catches query errors before deployment; zio-sql/zio-jdbc deprecated per 2025 roadmap
• ScalaTags 0.13.1 (template) - Type-safe HTML generation, 4x faster than Twirl; integrates with HTMX for server-rendered interactivity
• htmx4s 0.3.0 (frontend) - Type-safe HTMX attributes replace WinterCMS's problematic Snowboard/Alpine.js frontend
• Mill 1.0.0 (build tool) - 3-7x faster than sbt, simpler model scales to hundreds of plugin modules
• ZIO Config 4.0.5 (configuration) - YAML/HOCON support with type-safe derivation for WinterCMS-style config files
• ZIO Schema 1.7.5 (serialization) - Critical for YAML-driven forms; schema describes fields, validation, automatic JSON codec derivation

Critical stack decision: Quill over alternatives because it's the only maintained ZIO database library (zio-sql deprecated). Compile-time query generation is essential for plugin stability but creates compilation challenges that must be addressed via module architecture (see Pitfalls #5).

Frontend strategy: HTMX as primary interaction model (server returns HTML fragments), Vue.js for complex admin UI widgets (media manager, form builder). This avoids WinterCMS's "messy" Snowboard+Alpine pattern while maintaining progressive enhancement.

Template engine hybrid: ScalaTags for core/admin (type-safe, developer maintains), Twirl for theme templates (familiar syntax for non-Scala developers). Open question: invest in Twig-to-ScalaTags compiler for WinterCMS theme compatibility?

Expected Features

WinterCMS reference implementation (19 Golem15 plugins) demonstrates the feature surface area. CMFs in 2025-2026 have converged on table-stakes features with differentiation through performance and API-first architecture.

Must have (table stakes):

• Plugin system with dependency resolution ($require equivalent)
• YAML-driven backend forms (fields.yaml, columns.yaml pattern)
• Component architecture for frontend (reusable UI elements with properties)
• Theme system with layouts/partials/pages
• User/Auth with RBAC permissions
• Content management (pages, posts, media library)
• Database/ORM layer with relations and migrations
• CLI tools for scaffolding (project setup, plugin creation)

Should have (competitive advantages):

• Type-safe plugin development - compile-time checks eliminate PHP's runtime failures
• HTMX+Vue modern frontend - better UX than WinterCMS without JavaScript fatigue
• Superior performance - JVM 10-100x faster than PHP baseline
• API-first architecture - REST/GraphQL built-in for headless use cases
• Compile-time SQL validation - Quill catches query errors before deployment

Defer (v2+):

• Real-time collaboration (WebSocket complexity, infrastructure requirements)
• Multisite/multi-tenant (complex data isolation, defer until core proven)
• AI integration beyond MVP (AI-assist content writing can wait)
• GraphQL by default (REST sufficient for v1, GraphQL as optional plugin)
• Visual page builders (complex, fragile; component-based approach simpler)

Critical feature dependencies discovered:

[Foundation] Database/ORM + User/Auth → Plugin System → Everything Else
[Core CMS] Plugin System → Theme System → Frontend Components
         Plugin System → Backend Admin → YAML Forms → Content Management
[Advanced] Content Management → Versioning → Workflow → Scheduling

Plugin System is the critical bottleneck - everything builds on it. Getting the plugin API right is THE architectural decision.

Architecture Approach

ZIO's layer-based architecture maps cleanly to CMF requirements. Effect system provides type-safe plugin lifecycle, resource safety for database connections, and explicit error handling replacing WinterCMS's exception chaos.

Layered architecture (bottom-up):

1. Data Layer - PostgreSQL via Quill, connection pooling, migrations
2. Core Services - Config, EventBus, AuthService, PluginRegistry
3. Domain Layer - Repositories (pure business logic, no effects)
4. HTTP Layer - Routes (public, admin, API), middleware stack
5. Application Layer - Plugin loading, theme rendering, component resolution

Major components:

1. Plugin System - Lifecycle management, dependency resolution, extension registry. Uses ZLayer for DI, event bus for plugin interactions, type classes for model extensions. Pattern: plugins define extensions via traits, core discovers and wires them.

2. Theme Engine - Template loading/rendering, asset management, layout composition. Parses YAML frontmatter from .htm files (WinterCMS compatibility), translates Twig-like syntax to ScalaTags, supports component embedding via {% component 'alias' %}.

3. Component System - Reusable UI elements with lifecycle (init, onRun), properties (YAML-defined), AJAX/HTMX handlers. Components register via plugin registerComponents, instantiated per-request, provide data to templates.

4. Admin Backend - YAML-driven forms/lists. fields.yaml → FormConfig case class with field definitions, validation rules, conditional visibility. ZIO Schema derives JSON codecs for API endpoints.

5. Database Layer - Quill for compile-time SQL, Repository pattern with ZIO effects. Each plugin defines migrations as versioned ZIO effects. Schema registry tracks versions.

6. Auth Service - JWT tokens, permission-based access control, middleware for protected routes. Separate backend admin auth from frontend user auth.

Request pipeline flow:

Request → RouteResolver (lookup page by URL)
       → ThemeResolver (load layout/template)
       → ComponentResolver (instantiate components, call onRun, gather data)
       → PageRenderer (merge layout + page + component data → HTML)
       → Response (with HTMX attributes for interactivity)

HTMX integration pattern: Components define handlers (e.g., onLoadMore) that become routes (POST /component/{alias}/onLoadMore). HTMX attributes (hx-post, hx-target) trigger handlers, server returns HTML fragments, HTMX swaps into DOM.

Build order based on dependencies:

• Phase 1 (parallel): Database Layer, Config Service, Event Bus
• Phase 2: Plugin System (blocks everything else)
• Phase 3 (parallel): Component System, Auth Service
• Phase 4: Theme Engine, Template Parser
• Phase 5: Request Pipeline, Routes
• Phase 6: Admin Backend, Form/List Widgets
• Phase 7: Core Plugins (User, Blog, Pages)

Critical architectural decision: Plugin extension mechanism. Research identifies three patterns WinterCMS uses:

1. Event-based extension (primary) - plugins emit/subscribe to typed events
2. Model extension via type classes - plugins add relations, attributes, behaviors
3. Form field injection - plugins extend FormDefinition via events

SummerCMS must support all three, but with type-safe APIs.

Critical Pitfalls

Research identified 23 pitfalls across four dimensions. Top 5 by severity:

1. The Big Rewrite Anti-Pattern - Attempting full WinterCMS parity before shipping. Successful rewrites deliver value in vertical slices, not horizontal layers. Mitigation: Define MVP as "build a new site" not "migrate complex WinterCMS site." Freeze WinterCMS reference version. Accept 80/20 rule: 80% of value from 20% of features. Document what's explicitly NOT in v1.0.

2. Plugin API Lock-in - Designing plugin API early but proving inadequate. Changing it later breaks all plugins. Mitigation: Study multiple plugin systems (WordPress, WinterCMS, Discourse, VSCode). Build 3-5 diverse plugins BEFORE finalizing API. Use semantic versioning from day 1. Design for extension points (hooks, filters, traits). Plan for plugin API v2 from the start.

3. ZIO Quill Compile-Time Explosion - Projects with many Quill queries see compile times grow exponentially (5+ minutes per query, 5GB+ heap). Mitigation: Split database layer into separate Mill module. Limit queries per file (10-15 max). Use scalacOptions += "-Yretain-trees". Configure CI with 8GB+ memory. Consider Doobie for complex query scenarios.

4. AI Agent Quality Debt - Research shows AI-assisted coding creates "substantial but transient velocity gains alongside persistent increases in technical debt." Mitigation: Mandatory human review for all AI code. AI agents work on tests FIRST, then implementation. Static analysis gates in CI (no warning increase allowed). Limit AI to well-defined, isolated tasks.

5. Scala Learning Curve for PHP Developers - Target users are "web developers who may not know Scala deeply" but codebase uses advanced ZIO patterns. 40.5% onboarding slowdown observed. Mitigation: Create "SummerCMS Style Guide" limiting advanced patterns. Use simple, explicit types over clever abstractions. Extensive inline documentation. "Stepping project" for new contributors.

Additional high-impact pitfalls:

• ZIO HTTP Client Performance - 2s initialization overhead, 300ms per-request without pooling. Must configure connection pooling at startup.
• YAML Parser Edge Cases - WinterCMS YAML has subtle behaviors (validation cascades, conditional visibility, translation lookups). Build comprehensive test suite from WinterCMS examples before implementation.
• Authentication Complexity - Auth seems simple until: password reset, account lockout, session management, remember-me, OAuth, JWT refresh, GDPR deletion, audit logging. Use battle-tested library, don't DIY.
• Migration Tool Neglect - Users can't adopt without migration from WinterCMS. Include migration as Phase 2/3 requirement, not post-launch. Test with 3-5 real WinterCMS sites during development.

Pitfall timeline:

• Phase 1: ZIO effect wrapping patterns, FiberFailure handling, layer architecture
• Phase 2: Database compile times, HTTP client pooling, auth security
• Phase 3: Plugin API stability, YAML edge cases
• All phases: AI quality gates, learning curve, scope discipline

Implications for Roadmap

Based on combined research, recommended phase structure prioritizes proving the foundation before expanding scope. Vertical slices over horizontal layers.

Phase 1: Foundation & Prototype

Rationale: Validate stack integration end-to-end before "real" development. Uncover tooling issues early.

Delivers:

• Working CLI → HTTP → Database → Response flow
• Mill build configured with proper modules
• ZIO layer architecture proven
• Basic ZIO patterns documented (effect wrapping, error handling)

Addresses:

• Pitfall #1 (Big Rewrite) - proves concept before expanding scope
• Pitfall #3 (Quill compilation) - establishes module architecture
• Pitfall #8 (ZIO environment misuse) - sets patterns early

Features: None user-visible. This is pure technical validation.

Duration: 2-3 weeks (assuming experienced Scala developer)

Research needs: NONE - standard prototype patterns

Phase 2: Plugin System Core

Rationale: Plugin System is the architectural bottleneck. Everything depends on it. Getting the API right is critical to avoid lock-in.

Delivers:

• Plugin discovery and lifecycle (register, boot, shutdown)
• Dependency resolution ($require equivalent)
• Event bus for plugin communication
• Extension registry (components, settings, permissions)
• Database migration system (per-plugin migrations)

Addresses:

• Pitfall #11 (Plugin API lock-in) - build plugins before finalizing
• Pitfall #9 (Iceberg underestimation) - this IS the hidden 90%
• Architecture component #2 - foundational system

Features (to build as validation):

• Create 3-5 test plugins demonstrating diverse use cases:
  • Simple plugin (FAQ, Quote)
  • Plugin with dependencies (Blog requires User)
  • Plugin extending core models
  • Plugin with scheduled tasks
  • Plugin with form field injection

Duration: 8-12 weeks (very high complexity)

Research needs: DEEP - plugin architecture patterns, WinterCMS extension mechanisms, dependency resolution algorithms

Phase 3: Database & Auth

Rationale: Builds in parallel on Phase 1 foundation. Auth required for backend. Database required for content.

Delivers:

• Repository pattern with ZIO effects
• Quill query layer with compile-time validation
• Model relations (hasMany, belongsTo)
• Migration runner (Flyway integration)
• JWT-based authentication
• Permission-based authorization
• User/role/permission models

Addresses:

• Pitfall #13 (Auth complexity) - use proven patterns
• Pitfall #2 (FiberFailure wrapping) - database error handling
• Stack: Quill, PostgreSQL, Flyway

Features:

• User registration/login
• Password reset flows
• Session management
• Basic RBAC permissions

Duration: 6-8 weeks (medium-high complexity)

Research needs: MEDIUM - Auth best practices, GDPR compliance checklist

Phase 4: Theme Engine & Components

Rationale: Requires Plugin System (Phase 2) for component registration. Proves frontend rendering works.

Delivers:

• Theme loading from filesystem
• YAML frontmatter parsing
• Layout/page/partial composition
• Component lifecycle (init, onRun, data)
• ScalaTags rendering
• HTMX integration (component handlers)

Addresses:

• Pitfall #12 (YAML edge cases) - test suite from WinterCMS
• Architecture component #3 (Theme Engine)
• Stack: ScalaTags, htmx4s

Features:

• Basic theme with layout
• 2-3 example components (BlogPosts, ContactForm)
• HTMX-driven pagination/filtering

Duration: 8-10 weeks (high complexity)

Research needs: MEDIUM - YAML parsing edge cases, component lifecycle patterns

Phase 5: Admin Backend & Forms

Rationale: Needs Plugin System (Phase 2), Auth (Phase 3), Components (Phase 4). This is the "visible" part that looks simple but is 90% hidden complexity.

Delivers:

• Backend authentication/authorization
• YAML-driven form rendering (fields.yaml)
• YAML-driven list rendering (columns.yaml)
• Form widgets (text, textarea, dropdown, relation, file upload)
• CRUD scaffolding for models
• Settings management UI

Addresses:

• Pitfall #12 (YAML parser edge cases) - comprehensive validation
• Pitfall #9 (Iceberg underestimation) - form field types, conditional visibility, widget loading
• Stack: ZIO Schema (form field validation)

Features:

• Admin dashboard
• User management CRUD
• Settings editor

Duration: 10-14 weeks (high complexity)

Research needs: DEEP - WinterCMS form/list patterns, widget system, validation cascades

Phase 6: Content Management

Rationale: Builds on all previous phases. Proves the system works for actual CMS use case.

Delivers:

• Pages plugin (hierarchical pages, slugs, SEO)
• Blog plugin (posts, categories, tags)
• Media library (upload, organize, image transforms)
• Rich text editor integration (TipTap/ProseMirror)
• Content versioning (basic)
• Draft/published workflow

Addresses:

• Features: Core CMS functionality (table stakes)
• Validates plugin API from Phase 2 works for real plugins

Features:

• Create/edit pages
• Create/edit blog posts
• Upload/manage media
• Basic workflow

Duration: 8-10 weeks (medium-high complexity)

Research needs: LOW - standard CMS patterns

Phase 7: Migration & Launch Prep

Rationale: Users can't adopt without migration path from WinterCMS.

Delivers:

• WinterCMS database import tool
• Theme compatibility analyzer
• Plugin mapping guide (which WinterCMS plugins → SummerCMS equivalents)
• Migration documentation
• Performance benchmarks
• Security audit

Addresses:

• Pitfall #14 (Migration tool neglect)
• Pitfall #27 (Defer security)

Features:

• CLI: summer migrate:wintercms <path>
• Migration validation/testing

Duration: 6-8 weeks

Research needs: LOW - data migration patterns

Phase Ordering Rationale

Dependency chain: Phase 1 (foundation) → Phase 2 (plugin system) is the critical path. Phases 3-4 can partially overlap once Plugin System API stabilizes. Phase 5 requires all previous. Phase 6 validates the platform. Phase 7 enables real adoption.

Vertical slice strategy: Each phase delivers something testable. Avoids "horizontal layers" anti-pattern (all DB, then all API, then all UI). Phase 2 builds complete plugins. Phase 4 renders complete pages. Phase 6 manages complete content.

Pitfall avoidance: Early phases address foundational pitfalls (ZIO patterns, plugin API, compile times). Later phases build on stable foundation. Migration deferred until core proven but included in v1.0 scope.

Scope discipline: MVP = Phase 1-6 (build a new site). WinterCMS migration = Phase 7 adds adoption path. Multisite, AI, real-time collaboration explicitly deferred to v2+.

Research Flags

Needs deep research during phase planning:

• Phase 2 (Plugin System): Complex architectural decisions. Study WordPress, WinterCMS, Discourse, VSCode plugin systems. Dependency resolution algorithms. Event vs trait-based extension patterns.
• Phase 5 (Admin Backend): YAML form/list parsing edge cases. Widget system architecture. Conditional field visibility logic.

Standard patterns (skip research-phase):

• Phase 1 (Foundation): Prototype patterns well-documented
• Phase 3 (Database/Auth): ZIO + Quill patterns established, auth patterns standard
• Phase 6 (Content Management): Straightforward CRUD on proven foundation
• Phase 7 (Migration): Data migration patterns standard

Confidence Assessment

Area	Confidence	Notes
Stack	HIGH	All major dependencies verified via official releases. ZIO HTTP 3.8.1, Quill 4.8.6, Mill 1.0 are production-ready with documented deployment patterns.
Features	HIGH	WinterCMS reference implementation provides complete feature inventory. CMF patterns well-established. Table stakes vs differentiators clearly defined.
Architecture	MEDIUM-HIGH	ZIO layer-based architecture proven in production. Plugin system pattern from WinterCMS translates cleanly. Some uncertainty around YAML parser hybrid strategy and theme compatibility.
Pitfalls	MEDIUM-HIGH	Scala/ZIO pitfalls verified via multiple sources. Rewrite anti-patterns documented in literature. AI quality debt confirmed by 2025 research. Some uncertainty around magnitude of learning curve impact.

Overall confidence: HIGH

The research successfully identified:

• Production-ready stack with stable dependencies
• Complete feature inventory from reference implementation
• Clear architectural patterns with proven foundations
• Well-documented pitfalls with concrete mitigation strategies

Gaps to Address

Template engine final decision: ScalaTags + Twirl hybrid recommended, but open question on Twig-to-ScalaTags compiler for WinterCMS theme compatibility. Decision required by Phase 4. Recommendation: Start with ScalaTags+Twirl, assess migration pain with real themes, invest in Twig compiler only if migration blockers discovered.

Plugin dependency resolution algorithm: WinterCMS uses Composer-like resolution. Need to decide: reimplement Composer algorithm, use SemVer with simpler resolution, or delegate to Mill's dependency system. Decision required by Phase 2. Recommendation: Deeper research during Phase 2 planning.

Hot reload development experience: JVM startup is slow. Investigate JRebel, Bloop, or compile daemon for plugin hot-reload. Not blocking for v1.0 but affects developer experience. Decision required by Phase 2. Recommendation: Accept slower iteration in Phase 1-2, optimize in Phase 3 once patterns stable.

YAML parsing performance: Scala YAML libraries need benchmarking for large config files. Not researched in detail. Recommendation: Load test during Phase 5 (Admin Backend) with real WinterCMS fields.yaml examples.

Plugin isolation/sandboxing: How to safely load third-party plugins without security risks. Classloader isolation? OSGi? Flat classpath with trust model? Decision required by Phase 2. Recommendation: Start with flat classpath + code review model (like WinterCMS), investigate sandboxing for v2 if marketplace emerges.

WebSocket vs SSE for real-time: Project context mentions "websockets scale poorly." ZIO HTTP has WebSocket support. Should real-time features use SSE instead? Decision required by Phase 3+ (deferred from v1.0). Recommendation: Skip real-time for v1.0, research when actually needed.

Sources

Primary (HIGH confidence)

Stack research:

• ZIO Releases - v2.1.24 verification
• ZIO HTTP Releases - v3.8.1 verification
• Scala All Versions - 3.3.7 LTS verification
• Ziverge: ZIO in 2025 - Quill as endorsed ZIO database library
• ZIO Quill Documentation - Official patterns
• Mill 1.0.0 Release - Build tool maturity

Features research:

• WinterCMS Official Documentation - Feature inventory
• WinterCMS Features - Product capabilities
• October CMS Forms - YAML form patterns
• Golem15 WinterCMS Starter CLAUDE.md - Local reference implementation

Architecture research:

• ZIO Architectural Patterns - Official patterns
• ZIO Service Pattern - DI patterns
• Structuring ZIO 2 Applications - Production patterns
• WinterCMS Plugin Extension - Extension mechanisms

Pitfalls research:

• 5 More ZIO Pitfalls - Wix Engineering - Production experience
• ZIO Quill Compiler Performance - Official compilation warnings
• Speed at Cost of Quality Study - AI quality debt research
• Why Rewrites Fail - Swizec - Rewrite anti-patterns

Secondary (MEDIUM confidence)

• ScalaTags Documentation - Template performance claims
• htmx4s GitHub - Integration library
• Onboarding Juniors into Scala - Xebia - Learning curve data
• State of Scala Survey - 40.5% onboarding slowdown

Tertiary (LOW confidence, needs validation)

• Various CMF comparison articles (2025) - Market trends
• Hacker News threads on CMS architecture - Community patterns
• Plugin architecture blog posts - General patterns

---

Research completed: 2026-02-04 Ready for roadmap: YES

Next step: Roadmapper agent can use this synthesis to structure detailed phase plans with tasks, dependencies, and success criteria.