# 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/<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)
├─ 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/`. Currently one partial: `base.html.twig` (the site shell extended by all page templates).

---

## 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/<slug>/*.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 |