micrach/docs/superpowers/specs/2026-07-15-project-modernization-design.md

Project Modernization Design

Date: 2026-07-15

Goal

Modernize micrach in controlled stages without changing application behavior or reworking its architecture. First establish a supported toolchain, current dependencies, reproducible local infrastructure, useful CI, and a minimal test safety net. Migrate from Fiber v2 to Fiber v3 only after that baseline is stable.

Current State

• go.mod declares Go 1.15, while CI uses Go 1.17.
• Fiber is v2.31.0 and pgx is v4.15.0.
• The Dockerfile packages a prebuilt binary in BusyBox; it does not build the application.
• The GitHub Actions workflow builds, publishes an image, and deploys it to an obsolete Docker Swarm environment over SSH.
• docker-compose.yml describes that obsolete Swarm, Traefik, and VPS setup.
• The CodeSee workflow and its action versions are obsolete.
• No checked-in Go tests provide a regression safety net.
• Parts of the code use deprecated ioutil APIs, broad context.TODO() calls, and unchecked transaction completion errors.

Scope and Constraints

• Preserve routes, templates, HTTP status behavior, database schema, upload layout, and minimal-JavaScript approach.
• Preserve the current package boundaries and application architecture.
• Do not combine dependency work with handler or repository redesign.
• Do not add infrastructure that the application does not need. PostgreSQL is the only Docker Compose service required now.
• Run the application directly on the host with go run . or make dev.
• Keep a multi-stage Dockerfile as a reproducible application build artifact, but do not publish or deploy its image in CI.
• Do not add or modify database migrations unless an upgrade proves that a compatibility migration is unavoidable. Such a change requires separate review before implementation.

Strategy

Use two modernization waves. Wave 1 stays on the latest compatible Fiber v2 to avoid mixing framework API migration with the toolchain, database driver, CI, container, and test changes. Wave 2 performs the Fiber v3 migration as a separate change after Wave 1 is green.

Exact dependency versions must be rechecked against Context7 and official release notes when each wave begins. Major upgrades remain explicit; automated dependency tooling must not silently merge them.

Wave 1: Stable Modern Baseline

Go and Dependencies

• Set the supported Go line to Go 1.26. Use the latest available Go 1.26 patch release in CI and the Docker builder image; keep documentation aligned.
• Upgrade Fiber from v2.31.0 to the latest stable Fiber v2 release.
• Upgrade the Fiber HTML template engine to the latest Fiber v2-compatible release.
• Migrate github.com/jackc/pgx/v4 and standalone github.com/jackc/pgtype usage to github.com/jackc/pgx/v5 packages.
• Replace pgtype.Int4Array with the pgx v5-compatible representation selected during implementation, preserving query results and ordering.
• Upgrade other direct dependencies to current versions compatible with the selected Go and Fiber versions.
• Run go mod tidy and review every direct and indirect dependency change.
• Upgrade dependencies in coherent groups so failures can be attributed to a specific change.

Compatibility Cleanup

• Replace deprecated io/ioutil calls with io and os equivalents.
• Replace broad context.TODO() usage where a request, startup, or explicit operation context is available.
• Check and propagate transaction Commit errors. Preserve safe rollback behavior.
• Limit changes to those needed for supported APIs, correct error handling, and testability. Do not refactor package ownership or business flow.

Local Development Infrastructure

• Replace the Swarm-oriented Compose file with a local PostgreSQL service.
• Give PostgreSQL a persistent named volume and a healthcheck.
• Use development-only credentials and defaults consistent with .env.example.
• Do not add the application, Redis, a proxy, or other optional services to Compose.
• Document the normal workflow: start PostgreSQL with Compose, then run micrach on the host with go run . or make dev using nodemon.

Dockerfile

• Replace the prebuilt-binary BusyBox image with a multi-stage Dockerfile.
• Build a static Linux binary in a pinned Go 1.26 builder image.
• Copy only the binary, templates, static assets, and migrations into a small runtime image.
• Run the application as a non-root user and preserve writable upload storage.
• Do not add a container healthcheck until the application has a suitable health endpoint. Adding such an endpoint is outside this modernization.

CI and Automation

• Replace the existing build, publish, and deploy workflow with a read-only CI workflow.
• Run formatting verification, go test ./..., go vet ./..., go build ., the Linux static build, and govulncheck ./....
• Build the Docker image as verification, without login, push, registry tags, or deployment.
• Use current stable GitHub-maintained action releases and Go module caching.
• Remove SSH deployment, Docker Swarm service update, registry publishing, and their workflow configuration.
• Remove the obsolete CodeSee workflow.
• Add Dependabot configuration for Go modules and GitHub Actions. Updates open reviewable pull requests and are not auto-merged.

Test Safety Net

Add focused tests beside changed code, favoring table-driven cases where practical:

• configuration parsing and defaults;
• post and upload validation boundaries;
• pure migration, filesystem, and repository helpers where they can be tested without a shared database;
• Fiber handler smoke tests for key status and rendering paths that do not require production data;
• pgx v5 array conversion or scanning behavior introduced by the migration.

Tests requiring PostgreSQL must use disposable data and the local development database only when explicitly invoked. Routine unit tests must not depend on a developer's shared database.

Documentation

• Update README prerequisites, setup, development commands, container notes, and supported versions.
• Make .env.example safe for local development: no implicit external gateway dependency and no repeated seed behavior by default.
• Update AGENTS guidance when its Go, CI, Docker, or Compose statements become stale.

Wave 2: Fiber v3 Migration

Wave 2 starts only after Wave 1 passes all automated and manual checks.

• Recheck the current stable Fiber v3, template engine, and minimum Go requirements through Context7 and official release notes.
• Keep Go 1.26 if supported; otherwise upgrade to the required supported Go line as an explicit part of Wave 2.
• Change Fiber imports from v2 to v3 and use a v3-compatible template engine.
• Adapt handler context signatures, middleware configuration, static serving, form and body parsing, redirects, and other changed APIs.
• Preserve routes, response codes, template data, forms, and browser behavior.
• Exercise catalog, thread view, thread creation, replies, CAPTCHA, pagination, rate limiting, sage, archival, JPEG/PNG uploads, and thumbnail generation.
• Fix only migration regressions. Do not include architectural cleanup.
• Refresh compatible dependencies again after Fiber v3, run go mod tidy, and repeat vulnerability scanning.
• Record any remaining major-version candidates or deprecated APIs for later work instead of expanding this migration.

Ongoing Maintenance

• Keep the project on a supported Go release line and consume patch releases promptly through reviewed dependency automation.
• Review Dependabot pull requests for Go modules and GitHub Actions.
• Perform periodic dependency refreshes rather than another multi-year jump.
• Isolate future major upgrades in their own pull requests and do not mix them with unrelated refactoring.

Verification and Acceptance

Each wave must provide fresh evidence for all applicable checks:

1. Formatting produces no diff.
2. go test ./... passes.
3. go vet ./... passes.
4. go build . passes.
5. The Linux static build passes.
6. govulncheck ./... reports no unhandled reachable vulnerability.
7. go mod tidy produces no unexplained diff.
8. git diff --check passes.
9. The Docker image builds successfully.
10. Compose PostgreSQL reaches healthy state.
11. The host-run application connects to Compose PostgreSQL and applies migrations to a clean database.
12. Manual smoke tests cover affected pages, forms, responsive states, CAPTCHA, pagination, rate limiting, uploads, thumbnails, sage, and archival.
13. No .env, upload, binary, credential, or generated artifact is tracked.

Wave 1 is complete only when its checks pass and existing behavior remains unchanged. Wave 2 cannot begin before that point. A failed major upgrade is rolled back as its own isolated change; it must not destabilize the Wave 1 baseline.

Explicit Non-Goals

• Handler or repository architecture cleanup.
• New routes, UI redesign, or feature work.
• Database schema redesign.
• New caching, queueing, proxy, or observability services.
• Containerized local execution of the application.
• Image publishing, GitHub Container Registry integration, VPS deployment, Docker Swarm, or Traefik configuration.