trails/openspec/specs/activity-feed/spec.md at ad11624c83c7620fbb4a0305e43f747ad58a4e56

Ullrich Schäfer 37073eafd7 Spec catchup: drift fixes, account-settings split, notifications archive

Drift (specs aligned to shipped code):
- social-follows: locked-account access rule for /users/:u/followers and
  /users/:u/following (owner + accepted-follower see; non-followers of
  private get 404). Adds the follow→notification lifecycle requirement.
  Fills the placeholder Purpose.
- public-profiles: counts degrade to plain text (not anchors) for viewers
  who can't see the lists. Cross-references social-follows. Fills the
  placeholder Purpose.
- journal-auth slimmed to cookie session + Terms gate. Auth methods moved
  out (see authentication-methods).

Splits:
- account-settings (14-line stub) deleted, content split into:
  - profile-settings (display name, bio, profile_visibility)
  - account-management (email change with verification, account deletion)
  - connected-services (Wahoo + future external integrations)
- authentication-methods split out of journal-auth: passkeys
  (register/login/add/delete), magic links, 6-digit codes
  (login + register), method toggle on register/login forms,
  dev-console fallback.

New specs:
- sse-broker: /api/events, in-process broker, useUnreadNotifications
  hook, Caddy passthrough, multi-process forward-compat contract.

Archived: notifications change → openspec/changes/archive/2026-04-26-notifications.
Promoted the four delta spec files into top-level specs:
- specs/notifications/ (new capability)
- specs/activity-feed/ (added: public activity fan-out)
- specs/journal-landing/ (added: Notifications navbar entry)
- specs/social-follows/ (added: follow→notification lifecycle)

Added openspec/CAPABILITIES.md grouped index covering all 40 specs with
a Conventions section explaining cross-references, naming, and the
catch-up-vs-change rule.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-26 02:02:43 +02:00

6.4 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

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 instance home page (see journal-landing). private and unlisted activities SHALL NOT appear in this feed; unlisted stays reachable by direct URL only.

Scenario: Public activity appears in the instance feed

WHEN an owner marks an activity as public and another 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: 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, 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: 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

6.4 KiB Raw Blame History