83 lines
5.0 KiB
Markdown
83 lines
5.0 KiB
Markdown
|
# 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.
|