intotheeast-com/docs/reference/architecture.md

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