sabisan/PLAN.md

Go HTMX Architecture Portfolio Monolith

Summary

Build a SQLite-backed Go monolith that serves server-rendered HTML templates enhanced with HTMX and styled with Tailwind CSS. The public site will use a minimal editorial visual style inspired by MAD Architects: large photography, restrained typography, smooth scrolling, a responsive image-led layout, and a header that starts large on the homepage then compacts after scroll.

Use local image uploads, password-protected admin access, and saved contact requests visible in the admin panel.

Key Changes

• Create a Go 1.24 app using net/http, html/template, github.com/mattn/go-sqlite3, HTMX from a CDN, and Tailwind CSS for styling.
• Add routes:
  • GET / home landing page with large centerpiece image, intro text, featured projects, and scroll-responsive header.
  • GET /projects square project grid.
  • GET /projects/{slug} project detail with title, location, year, category, narrative text, cover image, and ordered gallery images.
  • GET /projects/{slug}/images/{imageID}/overlay returns an HTMX overlay fragment for a full-screen, full-resolution project image viewer.
  • GET /about profile image, bio/details, and contact form.
  • POST /contact saves visitor request and returns an HTMX success/error fragment.
  • GET /admin/login, POST /admin/login, POST /admin/logout.
  • /admin protected dashboard for editing site text, homepage/about images, projects, galleries, and contact requests.
• Store data in SQLite with tables for:
  • site settings/content blocks
  • projects
  • project images
  • uploaded assets
  • contact requests
  • admin users/sessions
• Store uploaded image files under data/uploads/; database rows store file metadata and public paths.
• Add startup migration logic that creates missing tables and seeds one admin user plus placeholder portfolio content if the database is empty.
• Configure admin credentials via environment variables, defaulting only for local development:
  • ADMIN_USERNAME
  • ADMIN_PASSWORD
  • SESSION_SECRET
  • DATABASE_PATH, default data/app.db

Interface Plan

• Public UI:
  • Use a clean black/white base, generous image scale, compact metadata, and no decorative gradients or card-heavy marketing layout.
  • Header is large and transparent/airy on the home hero; after scroll it becomes fixed, compact, opaque, and mobile-friendly.
  • Projects render as a responsive square image grid: 1 column mobile, 2 tablet, 3-4 desktop.
  • Project detail pages prioritize full-width imagery and simple narrative sections; every project image is clickable and opens a full-screen overlay with the original-resolution image.
  • The image overlay supports close controls, backdrop click, Escape key dismissal, scroll locking while open, and mobile-safe image sizing.
  • About page combines portrait/profile image, short bio, contact details, and an HTMX contact form.
• Admin UI:
  • Hidden by navigation but accessible by URL.
  • Login required with username/password and secure HTTP-only session cookie.
  • Dashboard sections: site content, projects, image uploads/galleries, and contact requests.
  • Use HTMX for create/update/delete actions so admin edits update page fragments without a full reload.
• Interactivity:
  • Use HTMX swaps with the View Transitions API for smooth page and overlay transitions.
  • Add a small local JavaScript module for behavior HTMX does not own well: scroll-based header compaction, overlay focus/keyboard handling, and body scroll locking.
  • Do not add a larger animation or UI framework for v1; consider Alpine.js later only if admin interactions become state-heavy.

Test Plan

• Add Go tests for:
  • route handlers returning expected status codes
  • auth middleware blocking unauthenticated admin requests
  • login/session behavior
  • contact form validation and persistence
  • project CRUD and gallery ordering
  • project image overlay endpoint authorization/data lookup behavior
• Add manual acceptance checks:
  • homepage header compacts on scroll
  • project grid and details work on mobile and desktop widths
  • clicking any project image opens a full-screen overlay, loads the full-resolution image, and closes with button, backdrop, and Escape
  • admin can upload images, add/remove projects, edit text, and view contact requests
  • public forms show success and validation errors through HTMX
• Run:
  • go test ./...
  • go run ./cmd/server and verify the app locally in browser

Assumptions

• This is a first production-shaped version, not just a static prototype.
• SQLite is the source of truth for editable content and contact requests.
• Images are uploaded locally, not stored externally.
• Tailwind CSS is the styling layer for both public and admin interfaces.
• HTMX plus the View Transitions API and a small local JavaScript module are enough for v1 smoothness; no additional JS UI library is required initially.
• Admin MFA is intentionally out of scope for v1, but auth structure should allow adding it later.
• Contact submissions are saved in the admin panel; email sending is out of scope for v1.