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

# Roadmap: SummerCMS

## Overview

SummerCMS delivers a Scala/ZIO-based Content Management Framework by building from foundation to features in vertical slices. The journey starts with database and infrastructure validation, proceeds through the plugin system (the architectural bottleneck), layers on components and themes, establishes admin capabilities, and culminates in content management and core plugins. Each phase delivers something verifiable before the next begins.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation** - Database integration, migrations, repository pattern, deployment config
- [ ] **Phase 2: Plugin System** - Plugin discovery, lifecycle, dependencies, extension API
- [ ] **Phase 3: Component System** - Reusable UI components with HTMX handlers
- [ ] **Phase 4: Theme Engine** - Layouts, partials, asset management, Vue integration
- [ ] **Phase 5: CLI Scaffolding** - Commands to create plugins, themes, components
- [ ] **Phase 6: Backend Authentication** - Admin users, login/logout, RBAC permissions
- [ ] **Phase 7: Admin Forms & Lists** - YAML-driven form and list generation
- [ ] **Phase 8: Admin Dashboard** - Dashboard widgets and plugin settings pages
- [ ] **Phase 9: Content Management** - CMS pages, layouts, media library, menus
- [ ] **Phase 10: Core Plugins** - User plugin and Blog plugin with full features

## Phase Details

### Phase 1: Foundation
**Goal**: Validate the Scala/ZIO stack end-to-end with working database and deployment infrastructure
**Depends on**: Nothing (first phase)
**Requirements**: INFRA-01, INFRA-02, INFRA-03, INFRA-04, DIFF-01
**Success Criteria** (what must be TRUE):
  1. Developer can run `mill run` and see HTTP server responding to requests
  2. Database queries execute with compile-time SQL validation via Quill
  3. Migrator service exists for running database migrations via CLI (not auto-run on startup)
  4. Models use Repository pattern with ZIO effects for data access
  5. Pulumi configuration deploys the application to cloud infrastructure
**Plans**: 3 plans

Plans:
- [x] 01-01-PLAN.md - Mill build setup and ZIO HTTP server with health endpoint
- [x] 01-02-PLAN.md - PostgreSQL integration with Quill and Flyway migrations
- [x] 01-03-PLAN.md - Repository pattern and Pulumi/Besom deployment config

### Phase 2: Plugin System
**Goal**: Establish the plugin architecture that all other features build upon
**Depends on**: Phase 1
**Requirements**: CORE-01, CORE-02
**Success Criteria** (what must be TRUE):
  1. Developer can create a plugin with manifest defining dependencies
  2. Plugins are discovered automatically from the plugins directory
  3. Plugin lifecycle executes in correct order (register, boot, shutdown)
  4. Plugin dependencies resolve correctly (plugin A requiring plugin B loads B first)
  5. Plugin can extend another plugin via type-safe extension API
**Plans**: 3 plans

Plans:
- [ ] 02-01-PLAN.md - Plugin discovery and manifest parsing (circe-yaml, PluginId, PluginManifest, PluginDiscovery)
- [ ] 02-02-PLAN.md - Lifecycle management and dependency resolution (SummerPlugin trait, PluginManager, topological sort)
- [ ] 02-03-PLAN.md - Extension API with type-safe plugin-to-plugin communication (EventService, ExtensionRegistry)

### Phase 3: Component System
**Goal**: Enable reusable UI components that respond to HTMX interactions
**Depends on**: Phase 2
**Requirements**: CORE-03, CORE-04
**Success Criteria** (what must be TRUE):
  1. Developer can create a component with properties defined in YAML
  2. Component lifecycle (init, onRun) executes correctly per request
  3. Components can define HTMX handlers that respond to data-attribute triggers
  4. HTMX handlers return HTML fragments that swap into the page
**Plans**: 2 plans

Plans:
- [ ] 03-01-PLAN.md - Component registration and lifecycle (SummerComponent trait, YAML property schemas, ComponentManager)
- [ ] 03-02-PLAN.md - HTMX handler routing and response (HtmxResponse, Pebble templates, ComponentRoutes, CSRF)

### Phase 4: Theme Engine
**Goal**: Render themes with layouts, partials, and Vue integration
**Depends on**: Phase 3
**Requirements**: CORE-05, CORE-06
**Success Criteria** (what must be TRUE):
  1. Developer can create a theme with layouts and partials
  2. Pages render by combining layout, page template, and partial includes
  3. Asset management bundles and serves CSS/JS from theme
  4. Theme can declare rendering mode (SPA, hybrid, static)
  5. Vue components integrate into theme pages
**Plans**: 2 plans

Plans:
- [ ] 04-01-PLAN.md - Theme loading and layout composition (ThemeConfig, ThemeLoader, ThemeService, custom Pebble tags)
- [ ] 04-02-PLAN.md - Asset pipeline and Vue integration (AssetService, ViteManifest, StaticPageCache, PagePipeline)

### Phase 5: CLI Scaffolding
**Goal**: Provide developer tools for rapid project setup
**Depends on**: Phase 4
**Requirements**: CORE-07, CORE-08, CORE-09
**Success Criteria** (what must be TRUE):
  1. Developer can run CLI command to scaffold a new plugin with boilerplate
  2. Developer can run CLI command to scaffold a new theme with structure
  3. Developer can run CLI command to scaffold a component within a plugin
  4. Generated scaffolds follow project conventions and are immediately usable
**Plans**: 2 plans

Plans:
- [ ] 05-01-PLAN.md - CLI framework setup with ZIO CLI and plugin scaffolding command
- [ ] 05-02-PLAN.md - Theme scaffolding (blank/starter templates) and component scaffolding

### Phase 6: Backend Authentication
**Goal**: Secure admin backend with user accounts and role-based access
**Depends on**: Phase 2
**Requirements**: AUTH-01, AUTH-02, AUTH-03, AUTH-04
**Success Criteria** (what must be TRUE):
  1. Admin can log in with email/password and access backend
  2. Admin can log out and session is terminated
  3. Admin can reset password via email link
  4. Roles can be created with specific permissions attached
  5. Controllers and views check permissions before rendering protected content
**Plans**: 3 plans

Plans:
- [ ] 06-01-PLAN.md - Admin user model, login/logout, sessions with JWT + DB hybrid
- [ ] 06-02-PLAN.md - Password reset flow with secure tokens and email
- [ ] 06-03-PLAN.md - RBAC permissions system with plugin registry and optional 2FA

### Phase 7: Admin Forms & Lists
**Goal**: Generate forms and lists from YAML definitions
**Depends on**: Phase 6
**Requirements**: ADMIN-01, ADMIN-02, ADMIN-03, ADMIN-04
**Success Criteria** (what must be TRUE):
  1. Developer defines fields.yaml and admin renders corresponding form
  2. Form supports standard widgets (text, textarea, dropdown, checkbox, etc.)
  3. Developer defines columns.yaml and admin renders corresponding list/table
  4. List supports column types (text, date, relation) and filters
  5. Forms validate input and display errors appropriately
**Plans**: 3 plans

Plans:
- [ ] 07-01-PLAN.md - YAML parsing infrastructure and basic form rendering (circe-yaml, WidgetRegistry, FormRenderer)
- [ ] 07-02-PLAN.md - Form widget implementations (text, textarea, dropdown, checkbox, datepicker, repeater, relation)
- [ ] 07-03-PLAN.md - List rendering with columns, filters, and pagination (ColumnRegistry, ListRenderer)

### Phase 8: Admin Dashboard
**Goal**: Provide customizable dashboard and plugin settings interface
**Depends on**: Phase 7
**Requirements**: ADMIN-05, ADMIN-06, ADMIN-07
**Success Criteria** (what must be TRUE):
  1. Admin sees customizable dashboard after login
  2. Dashboard displays widgets from plugins (reports, stats, quick actions)
  3. Plugins can register settings pages accessible from admin menu
  4. Settings use the same YAML-driven form system
**Plans**: 4 plans

Plans:
- [ ] 08-01-PLAN.md - Dashboard widget framework (DashboardWidget trait, WidgetRegistry, DashboardPreferenceService)
- [ ] 08-02-PLAN.md - Plugin settings pages (SettingsManager, SettingsModel, system_settings table)
- [ ] 08-03-PLAN.md - Dashboard container and core widgets (Gridstack.js, SSE updates, Welcome/Status/QuickActions)
- [ ] 08-04-PLAN.md - Settings controller integration (SettingsController, SettingsIndex, Phase 7 form integration)

### Phase 9: Content Management
**Goal**: Manage CMS pages, layouts, media, and navigation
**Depends on**: Phase 7
**Requirements**: CONT-01, CONT-02, CONT-03, CONT-04, CONT-05, CONT-06, CONT-07, CONT-08, CONT-09, DIFF-02
**Success Criteria** (what must be TRUE):
  1. Admin can create CMS pages with URL routing
  2. Pages use layouts with placeholders that content fills
  3. Components can be embedded in CMS pages via template syntax
  4. Admin can upload files to media library
  5. Images can be resized and cropped in media manager
  6. Content supports draft and published states
  7. Content revisions are tracked and can be viewed
  8. Navigation menus can be created and managed
  9. Menu items support different types (URL, page reference, plugin-generated)
  10. Changes reflect immediately during development (hot reload)
**Plans**: 7 plans

Plans:
- [ ] 09-01-PLAN.md - CMS pages and layouts (CmsPage, CmsLayout, CmsRouter, CmsPageService)
- [ ] 09-02-PLAN.md - Component embedding (ComponentTag, PlaceholderTag, PutTag, PartialTag, CmsPebbleExtension)
- [ ] 09-03-PLAN.md - Media library core (StorageBackend, LocalStorage, S3Storage, MediaLibrary)
- [ ] 09-03b-PLAN.md - Media routes and image processing (ImageProcessor, MediaRoutes)
- [ ] 09-04-PLAN.md - Content states and revisions (ContentRevision, RevisionService, publish/unpublish)
- [ ] 09-05-PLAN.md - Navigation menus with plugin integration (Menu, MenuItem, MenuItemTypeRegistry, MenuService, plugin tests)
- [ ] 09-06-PLAN.md - Hot reload (FileWatcher, HotReloadService, TemplateInvalidator)

### Phase 10: Core Plugins
**Goal**: Deliver User and Blog plugins demonstrating the complete plugin system
**Depends on**: Phase 9
**Requirements**: PLUG-01, PLUG-02, PLUG-03, PLUG-04, PLUG-05, PLUG-06, PLUG-07, PLUG-08
**Success Criteria** (what must be TRUE):
  1. Frontend visitors can register user accounts
  2. Frontend users can log in and log out
  3. Frontend users have profile pages they can edit
  4. Frontend users can reset forgotten passwords
  5. Admin can create blog posts with WYSIWYG editor
  6. Blog posts can be organized into categories
  7. Blog posts can be tagged with multiple tags
  8. Frontend displays blog post listings via components
**Plans**: TBD

Plans:
- [ ] 10-01: User plugin - registration and authentication
- [ ] 10-02: User plugin - profiles and password reset
- [ ] 10-03: Blog plugin - posts and editor
- [ ] 10-04: Blog plugin - categories, tags, listing components

## Progress

**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 3/3 | Complete | 2026-02-05 |
| 2. Plugin System | 0/3 | Planned | - |
| 3. Component System | 0/2 | Planned | - |
| 4. Theme Engine | 0/2 | Planned | - |
| 5. CLI Scaffolding | 0/2 | Planned | - |
| 6. Backend Authentication | 0/3 | Planned | - |
| 7. Admin Forms & Lists | 0/3 | Planned | - |
| 8. Admin Dashboard | 0/4 | Planned | - |
| 9. Content Management | 0/7 | Planned | - |
| 10. Core Plugins | 0/4 | Not started | - |

---
*Roadmap created: 2026-02-04*
*Last updated: 2026-02-05*