From d884f80e19dfa75e3786250938e1aec72c6274ca Mon Sep 17 00:00:00 2001 From: Mischa Date: Sun, 21 Jun 2026 13:07:55 +0200 Subject: [PATCH] docs: add architecture overview reference --- docs/reference/architecture.md | 147 +++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/reference/architecture.md diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md new file mode 100644 index 0000000..b6553d6 --- /dev/null +++ b/docs/reference/architecture.md @@ -0,0 +1,147 @@ +# Architecture Overview + +How the intotheeast site hangs together. + +--- + +## Stack + +| Layer | Technology | Notes | +|---|---|---| +| CMS | Grav 2.0.0-rc.10 | Flat-file PHP CMS; no database | +| Admin | Admin2 v2.0.0-rc.15 | Plugin slug: `admin2` (not `admin`) | +| 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; all 3 map templates use it | +| GPX rendering | maplibre-gl-leaflet-gpx (CDN) | Renders GPX files as route layers | + +--- + +## 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//01.dailies/.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 | + +--- + +## 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) +├─ dailies.html.twig ← extends base; journal feed list +├─ map.html.twig ← extends base; full-height MapLibre trip map +├─ stats.html.twig ← extends base; trip stats (days, distance, elevation) +├─ stories.html.twig ← extends base; stories grid +├─ story.html.twig ← extends base; single story (Ken Burns hero, shortcodes) +└─ gpx-manager.html.twig ← extends base; admin UI for GPX file management +``` + +Partials live in `templates/partials/`. Key partials: `entry-card.html.twig` (feed card), `map-init.html.twig` (shared MapLibre bootstrap). + +--- + +## 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 map.html.twig) + ├─ 01.dailies/ ← journal entries (template: dailies list + entry children) + ├─ 02.map/map.md ← template: map + ├─ 03.stats/stats.md ← template: stats + └─ 04.stories/ ← story pages (template: stories list + story children) +``` + +--- + +## GPX data flow + +``` +GPX file uploaded to trip page media + │ + ▼ +user/pages/01.trips//*.gpx + │ + ▼ +map.html.twig: trip_page.media.all → filter .gpx files → pass as JS array + │ + ▼ +MapLibre source: each GPX file added as a GeoJSON source via maplibre-gl-leaflet-gpx + │ + ▼ +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 |