m038andClaude Opus 4.8
fb9a47ea0c
Update CLAUDE.md + architecture.md stack to Grav 2.0.4 stable, admin2 2.0.10, gpm.releases: stable, and the three-category plugin-management model (GPM-managed / custom-in-repo / remote-only git-sync). Add execution outcome, Phase 3 prod fresh-install runbook (documentation-only), and mark plan Status complete. Note the Form 9.1.10 filepond regression as a known issue owned by the separate form-to-page rework. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Np4cMQLF77i664CAQXySzU
155 lines
6.6 KiB
Markdown
155 lines
6.6 KiB
Markdown
# Architecture Overview
|
|
|
|
How the intotheeast site hangs together.
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
| Layer | Technology | Notes |
|
|
|---|---|---|
|
|
| CMS | Grav 2.0.4 stable | Flat-file PHP CMS; no database. Server upgrades in place via `bin/gpm self-upgrade` |
|
|
| Admin | Admin2 v2.0.10 | Plugin slug: `admin2` (not `admin`) |
|
|
| GPM channel | `stable` | Authoritative in `user/config/system.yaml` → `gpm.releases`; `GRAV_CHANNEL=production` in compose is cosmetic |
|
|
| Container | Docker (`getgrav/grav` base + custom `Dockerfile`) | Grav 2.0 baked in at build time |
|
|
| PHP session | `session.save_path = /tmp` | Set in `php/php-local.ini` |
|
|
| Dev URL | http://localhost:8081 | Mapped from container port 80 |
|
|
| Maps | MapLibre GL JS | Replaced Leaflet; one shared map path (`MapUtils.initEntryMap`) on trip + home |
|
|
| GPX rendering | toGeoJSON (bundled in `js/map.js`) | Parses GPX → GeoJSON route layers client-side; no CDN |
|
|
|
|
---
|
|
|
|
## Plugin roles
|
|
|
|
The posting pipeline is a chain of three plugins:
|
|
|
|
```
|
|
Browser POST /post
|
|
│
|
|
├─ Grav Form plugin (built-in)
|
|
│ └─ validates required fields; handles file uploads
|
|
│
|
|
├─ add-page-by-form (third-party, patched)
|
|
│ └─ reads post-form.md config:
|
|
│ ├─ pageconfig.parent → target folder (e.g. /trips/japan-korea-2026/dailies)
|
|
│ ├─ pageconfig.slug_field → slug from date + title
|
|
│ └─ pagefrontmatter → template: entry, published: true
|
|
│ └─ writes entry.md to user/pages/01.trips/<trip>/01.dailies/<slug>.entry/
|
|
│ └─ moves uploaded photos into the page folder
|
|
│
|
|
└─ cache-on-save (custom, user/plugins/cache-on-save/)
|
|
└─ calls $grav['cache']->deleteAll() on every new-entry form submission
|
|
└─ ensures entries appear in feed immediately in both dev and prod mode
|
|
```
|
|
|
|
Other notable plugins:
|
|
|
|
| Plugin | Role |
|
|
|---|---|
|
|
| `login` | Auth for /post and /gpx-manager |
|
|
| `api` (Grav API v1) | Used by /gpx-manager to list/upload/delete GPX files |
|
|
| `admin2` | Admin panel at /admin |
|
|
|
|
### Plugin management model
|
|
|
|
Three categories, by how each plugin is installed and maintained:
|
|
|
|
1. **GPM-managed** (`plugins.txt` → `make install-plugins`): the marketplace plugins, including `login`, `form`, `admin2`, `api`, `flex-objects`, shortcodes, etc. As of the 2.0.4 upgrade, `admin2`/`api`/`flex-objects` moved into this category — they were previously hand-extracted from the core bundle. Update with `bin/gpm update` (`make remote-update-plugins-<env>` on servers).
|
|
2. **Custom, in-repo** (`user/plugins/` allowlisted in `user/.gitignore`): `cache-on-save`, `story-blocks`. Versioned in the user repo.
|
|
3. **Remote-only**: `git-sync` — installed and configured only on servers, **never** in `plugins.txt`, and disabled during upgrades.
|
|
|
|
---
|
|
|
|
## Template hierarchy
|
|
|
|
All page templates extend `base.html.twig`:
|
|
|
|
```
|
|
templates/
|
|
├─ base.html.twig ← site shell: nav, fonts, CSS tokens
|
|
├─ default.html.twig ← extends base; generic page
|
|
├─ home.html.twig ← extends base; context-aware two-column layout
|
|
├─ trip.html.twig ← extends base; trip page with filter bar (All/Journal/Stories)
|
|
├─ entry.html.twig ← extends base; single journal entry (gallery, badges, map)
|
|
├─ story.html.twig ← extends base; single story (Ken Burns hero, shortcodes)
|
|
└─ gpx-manager.html.twig ← extends base; admin UI for GPX file management
|
|
```
|
|
|
|
The standalone `dailies.html.twig`, `map.html.twig`, `stats.html.twig` and `stories.html.twig` view templates were **removed** in the 2026-07-04 standalone-page cleanup — the trip page (`trip.html.twig`) consolidated the feed, inline map, and inline stats.
|
|
|
|
Partials live in `templates/partials/` (plus macros in `templates/macros/`). Key partials: `base.html.twig` (site shell extended by all page templates), `entry-map.html.twig` (shared map column + `initEntryMap` call, used by trip + home), `trip-feed-col.html.twig` (feed column chrome, shared by trip + home), `home-predeparture.html.twig`, `entry-journal.html.twig` / `entry-story.html.twig` (feed cards), and `weather-icons.html.twig`.
|
|
|
|
---
|
|
|
|
## Trip entity structure
|
|
|
|
The site is organized around Trip entities. The active trip is set in `user/config/site.yaml` → `active_trip`.
|
|
|
|
```
|
|
user/pages/01.trips/
|
|
└─ japan-korea-2026/
|
|
├─ trip.md ← template: trip; title, date_start, cover_image, album_url
|
|
├─ *.gpx ← GPX route files (served as page media; auto-detected by trip.html.twig)
|
|
├─ 01.dailies/ ← journal entry children (container .md is routable:false)
|
|
└─ 04.stories/ ← story children (container .md is routable:false)
|
|
```
|
|
|
|
`01.dailies/` and `04.stories/` are inert data containers — the trip page aggregates their children; visiting the container routes directly 404s/redirects. (The former `02.map/` and `03.stats/` folders were removed with their view templates.)
|
|
|
|
---
|
|
|
|
## GPX data flow
|
|
|
|
```
|
|
GPX file uploaded to trip page media
|
|
│
|
|
▼
|
|
user/pages/01.trips/<slug>/*.gpx
|
|
│
|
|
▼
|
|
trip.html.twig / home.html.twig: trip_page.media.all → filter .gpx → entry-map partial
|
|
│
|
|
▼
|
|
MapLibre source: each GPX file parsed by toGeoJSON (bundled in js/map.js) → GeoJSON source
|
|
│
|
|
▼
|
|
Connector suppression: same-file 10km proximity check prevents spurious inter-track segments
|
|
│ (override with force_connect: true in trip frontmatter)
|
|
▼
|
|
Rendered as route polyline on map
|
|
```
|
|
|
|
---
|
|
|
|
## Data flow for a post submission
|
|
|
|
```
|
|
1. User fills /post form and taps Submit
|
|
2. Grav Form plugin validates: title and content required
|
|
3. add-page-by-form reads post-form.md:
|
|
pageconfig.parent: /trips/japan-korea-2026/dailies
|
|
pageconfig.slug: {date}-{title|slugify}
|
|
pagefrontmatter: template: entry, published: true
|
|
4. New page written to:
|
|
user/pages/01.trips/japan-korea-2026/01.dailies/
|
|
└─ 2026-07-20-0930-first-day-in-kyoto.entry/
|
|
└─ entry.md
|
|
5. Photos moved into the same folder
|
|
6. cache-on-save calls $grav['cache']->deleteAll()
|
|
7. Browser: form shows success message
|
|
8. Feed at /trips/japan-korea-2026 immediately shows new entry
|
|
```
|
|
|
|
---
|
|
|
|
## Key config files
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `user/config/site.yaml` | `active_trip` slug; site title/description |
|
|
| `user/config/system.yaml` | Twig cache, flex accounts/pages, language prefix |
|
|
| `user/config/media.yaml` | Registers `.gpx` as a valid media type |
|
|
| `user/plugins/api/api.yaml` | `session_enabled: true` for GPX manager auth |
|
|
| `user/themes/intotheeast/css/tokens.css` | Design tokens (colors, fonts, spacing) |
|
|
| `CLAUDE.md` | Project rules and always-loaded context for Claude |
|