trails/docs/information-architecture.md

# Information Architecture Review

*Snapshot date: 2026-04-26.* If the navbar, route table, or feed model has
shifted since then, treat this doc as stale and refresh against
`apps/journal/app/routes.ts` + `apps/journal/app/root.tsx`.

To regenerate this doc (fresh or refresh), invoke the **`/ia-review`**
skill — it walks the route tables + nav surfaces, builds the sitemap,
flags drift since this snapshot, and preserves the decisions/backlog
already captured below. The companion **`/spec-drift-review`** skill
does the equivalent for `openspec/specs/` against shipped code.

A snapshot of where every page lives, who sees it, and how visitors navigate
between them. Intended for review — flag anything that doesn't make sense or
should change.

## Apps

trails.cool ships two front-ends:

- **Journal** (`trails.cool`) — user accounts, social, content. Most of the IA
  question lives here.
- **Planner** (`planner.trails.cool`) — anonymous, ephemeral. Five routes
  total; not a real IA concern. Listed at the bottom for completeness.

---

## Journal sitemap

### Public surface (logged-out)

```
/                              Anonymous home (hero + marketing + public feed)
/users/:username               Public profile (full or locked stub)
/users/:username/followers     Followers list (404 on private profile)
/users/:username/following     Following list (404 on private profile)
/activities/:id                Public activity (or 404)
/routes/:id                    Public route (or 404)

/auth/register                 Sign-up
/auth/login                    Sign-in
/auth/verify                   Magic-link click-through landing
/auth/accept-terms             Re-accept gate (used after a Terms version bump)

/legal/imprint                 Imprint (German required)
/legal/privacy                 Privacy policy
/legal/terms                   Terms of service
/privacy                       301 → /legal/privacy
```

### Authenticated surface (logged-in)

```
/                              Personal dashboard ("your activities" stream)
/feed                          Social feed (people you follow, accepted)
/notifications                 Notifications log (4 event types, cursor paginated)
/follows/requests              Incoming Pending follow requests inbox

/users/:username               Any profile (own, followed, or locked stub)
/users/:username/followers     Gated by locked-account rule
/users/:username/following     Gated by locked-account rule

/routes                        Your routes
/routes/new                    Create route
/routes/:id                    View
/routes/:id/edit               Edit (handoff to Planner via JWT callback)

/activities                    Your activities
/activities/new                Create activity
/activities/:id                View

/settings                      Profile + email + passkeys + sync + danger zone

/sync/import/:provider         Wahoo import flow
/auth/logout                   Logout
```

### Navigation surfaces

**Top navbar (logged-in)** — in document order:

```
[trails.cool]   Feed   Routes   Activities   ...   🔔   Follow requests   <username>   Settings   Logout
                                                  └─ unread badge        └─ pending badge
```

**Top navbar (logged-out):**

```
[trails.cool]   ...   Login   [Register]
```

**Footer (everywhere):** Imprint · Privacy · Terms · Source (GitHub) · "Alpha".

**Profile self-link in nav** points to `/users/<self>`. There is no separate
"My profile" route; you reach your own profile via your own username.

---

## Logged-in vs logged-out home

`/` does double duty:

| Visitor | What `/` shows |
|---|---|
| Anonymous | Hero · Sign-up CTAs · "Try the Planner" · marketing cards (flagship only) · **public instance feed** |
| Signed-in | "Welcome, X" · Feed button · "New activity" CTA · **personal stream of your own activities** |

The two surfaces share no layout — they're effectively two pages behind one
URL. `home.tsx` branches on `user`.

---

## Two feed surfaces, three views

**Decision (2026-04-26):** merge Social and Public into a single `/feed`
page with a Followed / Public toggle. `/` stays "your content," `/feed`
becomes "everyone else's content."

| Surface | View | Audience |
|---|---|---|
| `/` (logged-in) | **Personal** — your own activities | You |
| `/feed` | **Followed** (default) — accepted-followed users' public activities | Signed-in |
| `/feed?view=public` | **Public** — instance-wide public activities | Signed-in |
| `/` (logged-out) | Hero + marketing + public feed (visitor entry point) | Anonymous |

Signed-in users can now see the public instance feed without logging out.
The logged-out `/` keeps its public feed as the anonymous visitor's first
impression.

Implementation notes (for whoever picks this up):

- `listSocialFeed` and `listRecentPublicActivities` already exist in
  `apps/journal/app/lib/activities.server.ts` — the toggle just picks one.
- URL shape: `?view=followed` (default, can omit) | `?view=public`. Keeps the
  toggle bookmarkable and avoids two routes.
- Empty-state in the Followed view today links to `/` ("see the public feed
  there") — that link should become the in-page Public toggle.
- Anonymous request to `/feed` keeps redirecting to `/auth/login`; the
  public feed remains reachable for them on `/`.

---

## Notifications vs follow requests

Two adjacent inboxes, two navbar entries:

| | `/notifications` | `/follows/requests` |
|---|---|---|
| Purpose | Read-only event log | Actionable Approve/Reject |
| Types covered | follow_received, follow_request_received, follow_request_approved, activity_published | Only Pending follows targeting you |
| Navbar surface | 🔔 icon + red unread badge | "Follow requests" text + red pending count |
| State | `read_at` per row | None — Approve/Reject mutates the follow row |

A `follow_request_received` notification points its "Review request" link at
`/follows/requests`, so the two surfaces are explicitly cross-linked rather
than merged. Mastodon makes the same split.

---

## Settings

`/settings` is a single scrollable page with five concerns stacked top to
bottom:

1. Profile (display name, bio, profile visibility)
2. Email change (with re-verification)
3. Passkeys (list, add, delete)
4. Connected services (Wahoo today, Strava/Garmin later)
5. Danger zone (delete account)

Spec was recently split into three (`profile-settings`, `account-management`,
`connected-services`) but the UI is still one page.

---

## Cross-app linking

- **Journal → Planner:** "Edit in Planner" on a saved route generates a JWT
  callback URL and opens `planner.trails.cool/session/<id>`. Logged-out home
  also has a "Try the Planner" link.
- **Planner → Journal:** the post-edit "Save" flow POSTs back to
  `/api/routes/:id/callback` on the Journal that issued the JWT.
- The Planner has no link back to a specific Journal otherwise — it's
  intentionally instance-agnostic.

---

## Planner sitemap

```
/                              Anonymous home (CTA: "Plan a route")
/new                           Create a fresh anonymous session
/session/:id                   Collaborative editor
```

No accounts, no profiles, no settings. IA is essentially trivial.

---

## Observations worth discussing

These are tensions or surprises I noticed while mapping. None are bugs — but
each is a deliberate IA choice that's worth confirming.

1. **`/` is two different products.** Logged-in `/` is "your stuff," logged-out
   `/` is "the instance." Discoverable? Or should logged-in `/` keep showing
   *something* of the public surface (e.g., a "Discover" tab)?
   *Status: open — not sure yet if this needs resolving.*

2. ~~**Signed-in users can't see the public instance feed.**~~ *Resolved:
   merged into `/feed` with a Followed / Public toggle (see above).*

3. ~~**The navbar's account cluster is busy.**~~ *Folded into Stream C
   (navbar redesign): regroup the cluster behind an avatar dropdown.*

4. ~~**`/feed` is reachable from both the navbar AND a button on the home
   page.**~~ *Decision: drop the button on logged-in `/` — the navbar
   entry is enough. See Stream D.*

5. ~~**🔔 vs "Follow requests" are visually inconsistent.**~~ *Resolved by
   Stream B — Follow requests folded into the bell as a Requests tab, so
   there's a single inbox icon in the navbar.*

6. **Routes and Activities are siblings, not nested.** That's correct today —
   an activity can exist without a route, and vice versa. *Flagged for a
   broader review: the concept of routes-vs-activities, plus the impending
   word collision with social "activities" (comment, like, publish) once
   federation lands. Tracked separately — see "Open exploration"
   below.*

7. ~~**`/settings` is one page.**~~ *Decision: break it apart. See Stream E.*

8. ~~**No `/explore`, no `/users` directory, no search.**~~ *Decision:
   propose an `/explore` spec. See Stream F.*

9. ~~**No mobile breakpoint for the navbar.**~~ *Decision: include mobile
   responsiveness in Stream C (navbar redesign).*

10. **Profile vs identity.** Your own profile is at `/users/<you>` not
    `/me` or `/profile`. Reachable via the navbar self-link. Fine, but means
    "view as logged-out visitor" is non-trivial — opening incognito is the
    only way to see your locked stub.
    *Status: open — no decision yet.*

---

## Open IA questions

If the answer to any of these is "I don't know yet," that's a signal it's
worth discussing before the navbar redesign locks in shapes:

- ~~Should `/` and `/feed` merge for signed-in users?~~ *Resolved:
  no — `/` stays "you," `/feed` becomes "everyone else" with a
  Followed / Public toggle.*
- ~~Where does an `/explore` or `/discover` page live?~~ *Resolved: it's
  the Public view inside `/feed`, no new top-level destination needed.*

---

## Implementation backlog

Decisions captured above translate into two work-streams. Items marked
*needs decision* are blockers — confirm before starting that stream.

### Stream A — Merge Social and Public feeds into `/feed`

**Code changes:**

1. **`apps/journal/app/routes/feed.tsx`**
   - Loader reads `?view=` query (`"followed"` default, `"public"` accepted;
     anything else falls back to default).
   - Branch the fetch: `listSocialFeed(user.id, 50)` for Followed,
     `listRecentPublicActivities(50)` for Public — both already exist in
     `apps/journal/app/lib/activities.server.ts`.
   - Render a toggle (two pills/tabs) at the top of the page; active state
     highlighted; toggle uses `<Link to="?view=public">` so it's plain HTTP,
     SSR-friendly, bookmarkable, and works without JS.
   - Per-view `<meta>` title: "Following — trails.cool" / "Public — trails.cool".
   - Per-view empty state: Followed view's existing "see the public feed"
     escape now links to `?view=public` instead of `/`.

2. **Translation keys (`apps/journal/app/locales/{en,de}/journal.json`)**
   - `social.feed.toggle.followed`, `social.feed.toggle.public`
   - `social.feed.public.heading`, `social.feed.public.empty`
   - Drop `social.feed.publicFeedLink` once the empty-state link is rewired.

3. **No change** to `apps/journal/app/routes/home.tsx` — logged-in `/` keeps
   showing the personal stream; the "Feed" button still targets `/feed`
   (defaults to Followed view).

4. **No change** to anonymous `/feed` behavior — it continues to redirect to
   `/auth/login`. The public feed remains visible to anonymous visitors on `/`.

**Spec updates after Stream A ships:**

- `openspec/specs/social-follows/spec.md` — the **Social activity feed**
  requirement currently scopes `/feed` to followed users only. Update it (or
  split into a new "Feed views" requirement) to add scenarios for the Public
  view and the toggle behavior.
- `openspec/specs/activity-feed/spec.md` — the **Instance-wide public
  activity feed** requirement says it powers the home page. Add a scenario
  noting it now also powers `/feed?view=public` for signed-in users.
- `openspec/specs/journal-landing/spec.md` — no change. Logged-in `/`
  already shows the personal stream; this is unchanged.

### Stream B — Merge Follow requests into Notifications  ✅ Shipped (PR #316)

**Decision (2026-04-26):** fold `/follows/requests` into `/notifications`
as a tabbed sub-page (Activity / Requests). The bell icon stays the
single inbox surface; the Requests tab shows a dot when there are pending
follows still needing Approve/Reject. The Notifications spec's existing
"no inline Approve/Reject on the activity log" rule is preserved — the
Requests tab is the actionable surface, the Activity tab is the log.

**Code changes:**

1. **`apps/journal/app/routes/notifications.tsx`**
   - Loader reads `?tab=` (`"activity"` default, `"requests"` accepted).
   - For Activity tab: existing behavior (paginated rows, `?before=` cursor).
   - For Requests tab: load `listPendingFollowRequests(user.id)` and
     `countPendingFollowRequests(user.id)` (already exist).
   - Page renders a tab strip at the top with both labels and an unread/
     pending dot per tab; active tab highlighted.
   - "Mark all read" button only appears on the Activity tab.

2. **`apps/journal/app/routes.ts`**
   - `route("follows/requests", ...)` becomes a redirect to
     `/notifications?tab=requests` (301). New file
     `routes/follows.requests.tsx` reduces to one `loader` returning a
     redirect, mirroring the existing `routes/privacy.tsx` pattern.

3. **`apps/journal/app/lib/notifications/link-for.ts`**
   - `follow_request_received` now resolves to
     `/notifications?tab=requests` instead of `/follows/requests`. Update
     the unit test in `link-for.test.ts`.

4. **`apps/journal/app/root.tsx`**
   - Drop the `Follow requests` navbar entry entirely.
   - Drop `pendingFollowRequests` from the root loader (no longer needed
     for navbar). The Requests tab loader inside `/notifications`
     fetches it on-demand.
   - Bell unread badge logic unchanged — `follow_request_received`
     already creates an unread row, so the existing unread count
     implicitly covers pending requests.

5. **i18n updates** (`packages/i18n/src/locales/{en,de}.ts`)
   - New keys: `notifications.tabs.activity`, `notifications.tabs.requests`.
   - The `settings.profile.visibility.privateHelp` string mentions
     `/follows/requests` — update to point at the new surface.

6. **e2e tests**
   - `e2e/social.test.ts`: the `/follows/requests redirects anonymous
     visitors to login` test changes to verify the new redirect target,
     and the "B sees the request in /follows/requests" step navigates
     to `/notifications?tab=requests` instead.
   - `e2e/notifications.test.ts`: same — replace `bPage.goto("/follows/requests")`
     with `bPage.goto("/notifications?tab=requests")`.

**Spec updates after Stream B ships:**

- `openspec/specs/notifications/spec.md` — extend the **Notifications
  page and unread count** requirement to describe the tabbed structure;
  refine the "follow_request_received card links to /follows/requests,
  not inline Approve/Reject" scenario to reflect the new URL and the tab
  separation. The `linkFor` scenarios need the updated path.
- `openspec/specs/social-follows/spec.md` — update the **Pending follow
  request management** requirement: navigation moves to
  `/notifications?tab=requests`; the navbar count badge requirement is
  retired (it's now a dot inside the Requests tab).
- `openspec/specs/journal-landing/spec.md` — the **Notifications entry
  in the navbar** requirement should clarify that this is the only
  inbox-style entry (no separate Follow requests entry).

### Stream C — Navbar redesign

**Scope (decided):**

- Regroup the account cluster (`<username>` + Settings + Logout) behind
  an avatar dropdown.
- Treat mobile responsiveness as a first-class concern in the redesign,
  not a phase-2 follow-up. Today the navbar wraps badly on phones.
- The bell + Requests tab from Stream B already gives the navbar a
  consistent inbox surface; nothing further needed there.

**Needs decision before implementation:**

- **Avatar dropdown content.** Profile · Settings · Logout — any others?
  (Theme toggle? Language toggle? Account switcher when federation lands?)
- **Mobile pattern.** Hamburger drawer? Bottom tab bar? Condensed top
  bar with the dropdown absorbing most controls?
- **Self-link vs avatar.** Today the navbar has a `<username>` text link
  to your profile. After the avatar dropdown, does the avatar take that
  role (click → profile, dropdown chevron → menu), or does Profile live
  only inside the dropdown?

### Stream D — Drop the redundant "Feed" button on logged-in `/`

**Decision (2026-04-26):** logged-in `/` no longer needs a "Feed" button
in the page header — the navbar entry is the single discoverable path.

**Code changes:**

- `apps/journal/app/routes/home.tsx` — remove the `<a href="/feed">`
  button next to the "New Activity" CTA in the signed-in branch
  (currently lines ~170–183). Keep "New Activity" as the only header
  action.
- No spec changes; `journal-landing/spec.md` has a **Social feed link
  for signed-in users** requirement that mentions a "Feed (or
  equivalent) link" — that requirement should be retired.

Tiny PR, ~5 lines + a spec update.

### Stream E — Break Settings apart

**Decision (2026-04-26):** `/settings` becomes a sectioned area rather
than a single scrollable page. Spec was already split into three
(`profile-settings`, `account-management`, `connected-services`); the UI
should follow.

**Needs decision before implementation:**

- **Layout pattern.** Tab strip on `/settings` (single URL, JS-driven
  tabs)? Nested routes (`/settings/profile`, `/settings/security`,
  `/settings/connections`, `/settings/danger`)? Sidebar nav?
- **Section list.** The current page has five concerns:
  1. Profile (display name, bio, profile visibility)
  2. Email (with re-verification)
  3. Passkeys
  4. Connected services (Wahoo today)
  5. Danger zone (delete account)
  Keep five? Merge "Email" into "Profile"? Pull "Danger zone" into
  "Account" alongside Email?

**Spec impact:** `profile-settings`, `account-management`, and
`connected-services` are already separate specs — they describe behavior,
not URL structure. Whichever URL pattern wins, only `journal-landing`
(or wherever the navbar currently sits) needs to know.

### Stream F — Propose an `/explore` spec

**Decision (2026-04-26):** the gap between "I want to find people to
follow" and "I have a username from outside" needs an in-app path.
Federation (Phase 2) makes this more valuable, but local-only `/explore`
is useful on day one.

**Approach:** kick off an OpenSpec proposal via `/opsx:propose` rather
than diving into code. The proposal phase decides:

- What `/explore` actually shows. A directory of all local users? A
  curated "active in the last N days" list? A randomized rotation? Just
  the public activity feed (which is currently buried on logged-out `/`)?
- Whether search is part of v1 or a follow-up.
- Where the link lives in the navbar (its own entry vs. inside `/feed`).
- Privacy: private profiles need to be excluded from any directory; this
  is the same locked-account access rule that already gates
  followers/following lists.

**Spec impact:** new spec file at
`openspec/specs/explore/spec.md` (or similar — name TBD by the proposal),
plus an entry in `CAPABILITIES.md`.

**Code changes (assuming avatar dropdown + icon-only Follow requests + no
mobile work yet):**

1. **`apps/journal/app/root.tsx`**
   - Add `displayName` to the loader's `user` payload (currently only
     `id` + `username`).
   - Replace the `<username> · Settings · Logout` cluster with a single
     avatar trigger + dropdown menu.
   - Replace the "Follow requests" text link with an icon-only button +
     badge (matching the bell's visual treatment).
   - Confirm bell + Follow requests sit on the same baseline / same gap.

2. **New components in `apps/journal/app/components/`**
   - `Avatar.tsx` — initials fallback when no image (none of our 4 prod
     users have an avatar field today, so this is initials-only initially).
   - `NavDropdown.tsx` — click-outside + Escape-to-close. Simple
     headless impl, no library.

3. **Loader query**
   - `getSessionUser` already returns `displayName`; just expose it in the
     loader return shape.

**Spec updates after Stream B ships:**

- `openspec/specs/journal-landing/spec.md` — currently has only the
  **Notifications entry in the navbar** requirement. Add a new
  requirement (or extend that one) for the account dropdown shape and the
  Follow-requests icon. Or factor the navbar out into its own spec —
  plausible if the cluster keeps growing.
- `openspec/specs/social-follows/spec.md` — the **Pending follow request
  management** requirement says "the 'Follow requests' link in the navbar
  renders with a small red count badge". Update the wording to reflect
  the icon treatment.
- `openspec/specs/notifications/spec.md` — the **Notifications page and
  unread count** requirement already says "navbar entry renders with a
  count badge"; verify the wording still applies cleanly to the icon-only
  treatment.

### Out of scope (deliberately)

These came up in the IA review but aren't part of this round:

- **`/me` alias for own profile.** Marginal value; navbar self-link is
  enough.
- **Mobile breakpoints across the app.** Bigger than just the navbar.
  Stream C handles the navbar; the rest of the app is a separate effort.

---

## Open exploration

Items that aren't ready for an implementation backlog because the
underlying *concept* still needs work, not just the UI.

### Routes vs Activities — terminology and model

The IA review flagged that Routes and Activities are sibling top-level
concepts. Two reasons to revisit this beyond the URL structure:

1. **Conceptual overlap.** A *route* is a planned path. An *activity*
   is a recorded outing (often along a route). Some apps (Strava,
   Komoot) collapse these into one timeline; we keep them split. Worth
   confirming the split still earns its keep.
2. **Word collision with social "activities".** Once federation lands
   (and arguably already, with the `activity_published` notification
   type), "activity" will be overloaded:
   - **Athletic activity:** a bike ride, a hike, a run.
   - **Social activity:** a comment, a like, a follow, a publish event.
     This is the ActivityPub sense — and it's the one that will appear
     in feeds, notifications, and remote inboxes.

   The collision is going to bite. ActivityPub uses "Activity" as a
   technical term throughout; the user-facing "Activity" (a ride) will
   constantly be next to ActivityPub Activities (a follow, a like) in
   logs, diagrams, and possibly UI strings.

**Plan:** dedicate a separate review doc (e.g.
`docs/routes-vs-activities.md`) to think this through before any spec
or code change. Open questions for that doc:

- Do we rename the user-facing "Activity" to something else (Outing?
  Trip? Ride? Record? Trace?) before federation cements the social
  meaning?
- Or do we keep "Activity" for the user-facing object and use "Event"
  or "Stream item" for the social/ActivityPub sense?
- Are Routes still needed as a top-level object, or could they be a
  subordinate concept of Activities (a "saved planned version" of
  something you may eventually ride)?
- What does the export/import story look like — GPX is route-shaped;
  Strava's TCX is activity-shaped; how do we want the model to talk
  about each?

Not urgent, but worth resolving before federation is far enough along
that renaming is a migration headache.
- **Is "Follow requests" a sub-page of Notifications or a sibling?** Today
  it's a sibling (separate navbar item). Could be a tab inside `/notifications`.
- **Avatar dropdown content.** Profile · Settings · Logout — anything else?
  (Theme toggle? Language toggle? Account switcher when federation lands?)
- **Mobile.** Hamburger menu? Bottom tab bar? Nothing yet — what's the target?
- **Search.** None today. Adding it changes the navbar. When does it land?