121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# Phase 1: Foundation - Context
|
|
|
|
**Gathered:** 2026-02-04
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Validate the Scala/ZIO stack end-to-end with working database and deployment infrastructure. This includes Mill build setup, ZIO HTTP server, PostgreSQL integration via Quill, database migrations, repository pattern, and Pulumi deployment configuration.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Database Conventions
|
|
|
|
**Migrations:**
|
|
- Timestamped migration files (20260204_create_users.scala)
|
|
- Migrations require both up() and down() methods (rollbacks mandatory)
|
|
- Migration history tracked in `summer_migrations` database table
|
|
- Migrations run manually via CLI command, not automatically on startup
|
|
- Plugin uninstall prompts user whether to keep or drop data
|
|
|
|
**Naming:**
|
|
- snake_case for all table and column names (PostgreSQL convention)
|
|
- Core tables prefixed with `summer_` (summer_users, summer_pages)
|
|
- Plugin tables prefixed with `vendor_plugin_` (golem15_queststream_quests)
|
|
- Single shared schema (no separate PostgreSQL schemas per plugin)
|
|
|
|
**Standard Columns:**
|
|
- Scaffolded models include id, created_at, updated_at by default (Winter/October convention)
|
|
- These can be removed if not needed
|
|
- Soft deletes opt-in per model (add SoftDelete trait when needed)
|
|
|
|
### Repository Design
|
|
|
|
- Trait + Live implementation pattern (trait UserRepository, class UserRepositoryLive)
|
|
- Typed error ADT (sealed trait with NotFound, Conflict, ValidationError, etc.)
|
|
|
|
### Build & Run Experience
|
|
|
|
**Commands:**
|
|
- `mill run` - Simple start
|
|
- `mill dev` - Watch mode with file watching and auto-reload
|
|
- `summer init` - Interactive project initialization
|
|
- `summer check` - Production config validation (DB connection, env vars)
|
|
- Full DB command suite: migrate, rollback, reset, seed, status, create-migration
|
|
- Scala seed classes for populating test data
|
|
|
|
**Server:**
|
|
- Default port 8080
|
|
- Hot-reload of Scala code in development
|
|
- Global `--debug` flag for verbose output across all commands
|
|
|
|
**Logging:**
|
|
- Colorized console output in development
|
|
- SQL query logging hidden by default, enabled via flag
|
|
|
|
**CLI Style:**
|
|
- Friendly output with progress indicators, success/error messages
|
|
- ASCII art SummerCMS banner with sun
|
|
|
|
**Configuration:**
|
|
- HOCON files (application.conf) with environment overrides
|
|
- Environment variables override HOCON values (Typesafe Config pattern)
|
|
- PostgreSQL only (no SQLite option)
|
|
|
|
**Build Artifacts:**
|
|
- Fat JAR by default
|
|
- GraalVM native image as optional build target
|
|
|
|
### Deployment Setup
|
|
|
|
**Cloud Providers:**
|
|
- Multi-provider abstraction (AWS, GCP, Hetzner)
|
|
- Dockerfile included in project (users build their own images)
|
|
|
|
**Secrets:**
|
|
- Pulumi encrypted secrets for DB passwords, API keys
|
|
|
|
**Database Provisioning:**
|
|
- Configurable: can provision new PostgreSQL or connect to existing
|
|
|
|
**SSL/TLS:**
|
|
- Let's Encrypt automatic certificate provisioning
|
|
|
|
**CDN:**
|
|
- Optional add-on (basic deployment works without)
|
|
|
|
### Claude's Discretion
|
|
|
|
- Foreign key constraint enforcement strategy
|
|
- ZIO effect return type patterns for repositories
|
|
- Transaction handling approach (explicit wrapper vs service layer)
|
|
- Health check endpoint design (/health vs /health + /ready)
|
|
- Pulumi stack organization (per-environment vs single stack)
|
|
- Deployment documentation depth for Phase 1
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Migration pattern should match Winter/October: scaffold includes id + timestamps by default, removable if not needed
|
|
- CLI should have ASCII art sun banner for SummerCMS identity
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-foundation*
|
|
*Context gathered: 2026-02-04*
|