# 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](https://github.com/zio/zio/releases) - v2.1.24 verification
- [ZIO HTTP Releases](https://github.com/zio/zio-http/releases) - v3.8.1 verification
- [Scala All Versions](https://www.scala-lang.org/download/all.html) - 3.3.7 LTS verification
- [Ziverge: ZIO in 2025](https://www.ziverge.com/post/zio-in-2025) - Quill as endorsed ZIO database library
- [ZIO Quill Documentation](https://zio.dev/zio-quill/getting-started/) - Official patterns
- [Mill 1.0.0 Release](https://mill-build.org/blog/13-mill-build-tool-v1-0-0.html) - Build tool maturity

**Features research:**
- [WinterCMS Official Documentation](https://wintercms.com/docs) - Feature inventory
- [WinterCMS Features](https://wintercms.com/features) - Product capabilities
- [October CMS Forms](https://docs.octobercms.com/3.x/backend/forms.html) - YAML form patterns
- Golem15 WinterCMS Starter CLAUDE.md - Local reference implementation

**Architecture research:**
- [ZIO Architectural Patterns](https://zio.dev/reference/architecture/architectural-patterns/) - Official patterns
- [ZIO Service Pattern](https://zio.dev/reference/service-pattern/) - DI patterns
- [Structuring ZIO 2 Applications](https://softwaremill.com/structuring-zio-2-applications/) - Production patterns
- [WinterCMS Plugin Extension](https://wintercms.com/docs/v1.2/docs/plugin/extending) - Extension mechanisms

**Pitfalls research:**
- [5 More ZIO Pitfalls - Wix Engineering](https://medium.com/wix-engineering/5-more-pitfalls-to-avoid-when-starting-to-work-with-zio-d0cdd44fa439) - Production experience
- [ZIO Quill Compiler Performance](https://zio.dev/zio-quill/compiler-performance/) - Official compilation warnings
- [Speed at Cost of Quality Study](https://arxiv.org/abs/2511.04427) - AI quality debt research
- [Why Rewrites Fail - Swizec](https://swizec.com/blog/you-can-t-stop-the-business-or-why-rewrites-fail/) - Rewrite anti-patterns

### Secondary (MEDIUM confidence)

- [ScalaTags Documentation](https://com-lihaoyi.github.io/scalatags/) - Template performance claims
- [htmx4s GitHub](https://github.com/eikek/htmx4s) - Integration library
- [Onboarding Juniors into Scala - Xebia](https://xebia.com/blog/6-tips-for-onboarding-juniors-into-scala/) - Learning curve data
- [State of Scala Survey](https://www.jvm-weekly.com/p/the-state-of-scala-and-clojure-surveys) - 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.