# 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*