From 834dd51bcc9c94333133a4b642a5e764cf392878 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Wed, 4 Feb 2026 02:46:18 +0100 Subject: [PATCH] docs: complete project research for SummerCMS Files: - STACK.md - ZIO ecosystem recommendations (Scala 3.3.7 LTS, ZIO HTTP 3.8.1, Quill 4.8.6, Mill 1.0) - FEATURES.md - CMF feature inventory from WinterCMS reference (table stakes, differentiators, anti-features) - ARCHITECTURE.md - ZIO layer-based architecture with plugin system patterns - PITFALLS.md - 23 identified pitfalls across Scala/ZIO, CMF rewrite, scope, and team dimensions - SUMMARY.md - Executive synthesis with 7-phase roadmap recommendations Key findings: - Stack: ZIO ecosystem production-ready, Quill endorsed as only maintained database library - Architecture: Plugin System is critical bottleneck, build 3-5 plugins before finalizing API - Critical pitfall: Big Rewrite Anti-Pattern - define MVP as "build new site" not "full WinterCMS parity" Ready for roadmap creation. --- .planning/research/SUMMARY.md | 445 ++++++++++++++++++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 .planning/research/SUMMARY.md diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md new file mode 100644 index 0000000..cf0e432 --- /dev/null +++ b/.planning/research/SUMMARY.md @@ -0,0 +1,445 @@ +# 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 ` +- 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.