trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/specs/activity-feed/spec.md
Ullrich Schäfer 0cf87b72ab
Fix medium-severity spec drift across 17 specs 
- authentication-methods: document completeAuth mode param ("redirect"|"json");
  clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
  matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
  implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
  document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
  retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
  requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
  object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
  note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
  split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
  cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
  includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
  is also displayed
- local-dev-environment: add mobile app (Expo) dev commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-24 11:11:31 +02:00

8 KiB
Raw Blame History

Purpose

Activity creation, chronological feed, detail views, and route linking in the Journal app.

Requirements

Requirement: Create activity

The Journal SHALL allow authenticated users to create an activity by uploading a GPX trace and adding a description.

Scenario: Create activity with GPX

  • WHEN a user uploads a GPX file and enters a description
  • THEN an activity is created with the GPS trace, computed distance and duration, and stored in the database

Scenario: Create activity linked to route

  • WHEN a user creates an activity and selects an existing route
  • THEN the activity is linked to that route (route_id foreign key)

Requirement: Activity feed

The Journal SHALL display a chronological feed of the authenticated user's activities.

Scenario: View own activity feed

  • WHEN a logged-in user navigates to their feed
  • THEN they see their activities in reverse chronological order with name, date, distance, and duration

Requirement: Activity detail page

The Journal SHALL display an activity detail page with map, stats, and description. Access depends on the activity's visibility: public activities are viewable by anyone including unauthenticated visitors, unlisted activities are viewable by anyone who has the URL, and private activities are viewable only by the owner.

Scenario: Owner views own activity

  • WHEN a logged-in user navigates to an activity they own at any visibility
  • THEN they see the activity name, description, a map with the GPS trace, distance, duration, and elevation stats

Scenario: Anyone views a public activity

  • WHEN any visitor (including unauthenticated) navigates to a public activity's URL
  • THEN they see the full activity detail page as above

Scenario: Anyone with the URL views an unlisted activity

  • WHEN any visitor navigates directly to an unlisted activity's URL
  • THEN they see the full activity detail page as above

Scenario: Non-owner is blocked from a private activity

  • WHEN a visitor who is not the owner requests a private activity URL
  • THEN the server responds with HTTP 404 (not 403), so the existence of the private activity is not leaked

Scenario: Public and unlisted activity pages emit social-share metadata

  • WHEN a visitor loads a public or unlisted activity detail page
  • THEN the response emits Open Graph and Twitter Card meta tags (og:title, og:description, og:type="article", og:site_name, twitter:card="summary")

Requirement: Link activity to route

Users SHALL be able to link an existing activity to a route, or create a route from an activity trace.

Scenario: Link activity to existing route

  • WHEN a user selects "Link to Route" on an activity and chooses a route
  • THEN the activity's route_id is set to the selected route

Scenario: Create route from activity

  • WHEN a user selects "Create Route from Activity"
  • THEN a new route is created using the activity's GPX trace

Requirement: Activity without route

Activities SHALL be allowed to exist without a linked route.

Scenario: Standalone activity

  • WHEN a user imports a GPX activity without linking to a route
  • THEN the activity is stored with route_id as null

Requirement: Instance-wide public activity feed

The Journal SHALL expose a reverse-chronological feed of every activity on the instance with visibility public. This feed powers the visitor home page (see journal-landing) for anonymous traffic and the Public view of /feed (see social-follows spec, "Social activity feed") for signed-in viewers. private and unlisted activities SHALL NOT appear in this feed; unlisted stays reachable by direct URL only.

Scenario: Public activity appears in the visitor home feed

  • WHEN an owner marks an activity as public and an anonymous visitor loads the home page
  • THEN the visitor sees the activity in the instance feed, with the owner's display name, distance, and start date

Scenario: Public activity appears in the signed-in /feed?view=public view

  • WHEN an owner marks an activity as public and a signed-in user loads /feed?view=public
  • THEN the signed-in user sees the activity in the Public view, regardless of whether they follow the owner

Scenario: Private or unlisted activities stay out of the feed

  • WHEN an activity's visibility is private or unlisted
  • THEN it does not appear in the instance feed on either surface, regardless of who is viewing

Requirement: Activity visibility

The Journal SHALL persist a visibility value on every activity and SHALL allow the owner to change it.

Scenario: New activities default to private

  • WHEN an activity is created without an explicit visibility
  • THEN the activity row is persisted with visibility = 'private'

Scenario: Owner changes an activity's visibility

  • WHEN an activity owner selects a different visibility (private, unlisted, public) and saves
  • THEN the stored visibility is updated and subsequent access checks use the new value immediately

Requirement: Activity listings respect visibility

The Journal's own-activities feed SHALL show the owner everything regardless of visibility, while any cross-user listing SHALL only include activities with visibility = 'public'.

Scenario: Own activity feed is unchanged

  • WHEN a logged-in user views their own activity feed
  • THEN the feed includes all of their own activities regardless of visibility

Scenario: Public profile lists only public activities

  • WHEN a visitor loads /users/:username
  • THEN the rendered list of activities includes only the user's public activities; unlisted and private activities are omitted

Requirement: Public activity creation fans out notifications

Creating an activity with visibility = 'public' SHALL enqueue a fan-out job that inserts an activity_published notification for every accepted follower of the activity owner. The fan-out SHALL run asynchronously so the activity-creation request returns immediately. See notifications spec for the notification row shape and the idempotency rules.

Scenario: Public activity fans out

  • WHEN a user with N accepted followers creates an activity with visibility = 'public'
  • THEN a pg-boss job is enqueued, and on completion N notifications exist with type = 'activity_published', recipient_user_id ∈ accepted-followers, actor_user_id = activity owner, subject_id = activity id

Scenario: Private or unlisted activity does not fan out

  • WHEN a user creates an activity with visibility = 'private' or 'unlisted'
  • THEN no fan-out job is enqueued and no notifications are created

Scenario: Visibility change to public fans out

  • WHEN an activity owner changes an existing activity's visibility from private or unlisted to public
  • THEN a fan-out job is enqueued for the visibility change, creating activity_published notifications for all accepted followers — the same fan-out as on initial public creation

Scenario: No accepted followers means no notifications

  • WHEN a user with zero accepted followers creates a public activity
  • THEN the fan-out job runs and inserts zero rows

Requirement: Synthetic activity flag

The Journal SHALL persist a synthetic boolean on every activity so automated / demo content can be distinguished from user-created content.

Scenario: User-created activities default to non-synthetic

  • WHEN an activity is created through any user-facing flow (GPX upload, sync import, Planner handoff)
  • THEN the activity row is persisted with synthetic = false

Scenario: Bot inserts flag their rows as synthetic

  • WHEN the demo-activity-bot inserts an activity
  • THEN the row is persisted with synthetic = true

Scenario: Synthetic flag is not user-editable

  • WHEN an activity owner edits the activity via any user-facing action
  • THEN the stored synthetic value is not changed by the edit