intotheeast-com/docs/reference/architecture.md

# 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; 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 |

---

## 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 |