Files

Jakub Zych 8f3c671cac docs(01): capture phase context

Phase 01: foundation
- Implementation decisions documented
- Phase boundary established

2026-02-04 13:57:50 +01:00

3.6 KiB

Raw Blame History

Phase 1: Foundation - Context

Gathered: 2026-02-04 Status: Ready for planning

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

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

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

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 01-foundation Context gathered: 2026-02-04

3.6 KiB Raw Blame History