docs: add architecture overview reference
This commit is contained in:
@@ -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/<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/`. 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/<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 |
|
||||
Reference in New Issue
Block a user