trails/docs/old-trails-analysis.md

Feature Analysis: /Users/ullrich/Projects/trails

Analysis of the older trails Remix app for features and patterns that could be ported or adapted for trails-cool. Organized by category with implementation references.

Social Features

Reactions/Kudos System

Allow users to react to activities with configurable reaction types (currently "kudos"). Generic implementation supports any target type (profile, activity, etc.). UI shows reaction counts on activity cards.

• drizzle/models/social-interactions.ts
• app/routes/api+/activities.$activityId.reactions.ts

Comments/Replies

Thread-based comment system on activities. Comments stored as social interactions with "reply" kind. Shows reply counts alongside reactions.

• app/routes/api+/activities.$activityId.replies.ts
• app/routes/feed.tsx

User Following

Follow/unfollow user profiles with mutual follow tracking and uniqueness constraints. Can be extended to follow specific routes or activities.

• app/routes/api+/follows.ts
• app/utils/social.server.ts

Personalized Activity Feed

Feed showing activities from followed users, filtered by visibility (public, followers-only, private). Shows interaction counts (reactions, replies).

• app/routes/feed.tsx
• app/utils/social.server.ts

Import & Integration

Activity Import from External Services

Komoot integration for importing tours. Batch import tracking with status (queued, running, completed, failed). Automatic deduplication using dedupeKey prevents duplicate imports. Detailed statistics (totalFound, importedCount, duplicateCount).

• app/inngest/importActivities.ts
• app/utils/integrations.server.ts

Third-Party Sync Jobs

Background Inngest jobs for syncing external platforms. Handles credential validation and error recovery. Tracks lastSyncedAt for incremental syncing.

• app/inngest/komootSync.ts

Integration Connections Management

Store encrypted credentials for multiple service integrations. Track connection status and last sync time. Support for multiple users connecting the same integration independently.

• app/routes/integrations.tsx
• app/routes/api+/integrations.ts

Route Planning

Ride Plan Scheduling

Schedule rides with timezone-aware start/end times. Privacy levels (followers-only, private, public). Group ride flag for collaborative planning.

• drizzle/models/ride-plans.ts

Route Geometry Encoding

Encoded polyline storage for efficient geometry. Route metrics: distance, elevation gain, origin, destination. Multiple routes per ride plan.

• drizzle/models/ride-routes.ts
• app/components/ride-plans/route-editor.tsx

Ride Plan Participants

Invite users to group rides. Track participation status (invited, accepted, declined). Enables collaborative ride planning.

• drizzle/models/ride-plan-participants.ts

Activity Tracking

Live Activity Recording

Start/pause/finish live recordings. Records start time, end time, duration, distance, elevation gain. Manual form completion for recorded activities. Activity status tracking (recording, paused, completed).

• app/components/activities/activity-recorder.tsx
• app/routes/api+/activities.recordings.start.ts

Activity Visibility Levels

Public, followers-only, and private visibility options. Source tracking (native recording vs. import). Link activities to specific ride plans and routes.

• drizzle/models/ride-activities.ts

User Profile & Content

Profile Images

S3-compatible storage for profile pictures. Signed PUT requests for direct client uploads. Image serving via openimg library for optimization.

• app/utils/storage.server.ts
• drizzle/models/user-images.ts

User Notes/Blog

Rich note creation with title and markdown content. Image attachments to notes (up to 5 images per note). Note listing and detail views. Image form validation (3MB max per file).

• drizzle/models/notes.ts
• app/routes/users+/$username_+/notes.tsx

Note Images

Upload and manage images within notes. Alt text support for accessibility. S3 storage with organized paths.

• drizzle/models/note-images.ts
• app/routes/users+/$username_+/__note-editor.tsx

Search & Discovery

User Search

Full-text search over username and display name. Pagination with limit of 50 results. Search results with profile images. Case-insensitive matching.

• app/routes/users+/index.tsx

Search Bar Component

Debounced auto-submit search. Reusable search UI component. Query parameter preservation.

• app/components/search-bar.tsx

Authentication & Settings

Two-Factor Authentication

TOTP-based 2FA on top of passkeys. Settings UI for enabling/disabling. Verification flow.

• app/routes/settings+/profile.two-factor.tsx

Email Verification

Email-based account verification. Verification token tracking. Email change flow with verification.

• drizzle/models/verifications.ts

Profile Management

Change email, password, name. Photo upload. Passkey management. Connected OAuth providers (GitHub).

• app/routes/settings+/profile.tsx

Federation

ActivityPub Foundation

Inbox/outbox endpoints for federated social network. Background publishing via Inngest. Federation record tracking for local/federated entity mapping.

• app/routes/api+/activitypub.inbox.ts
• app/routes/api+/activitypub.outbox.ts

Data Management

Activity Files Association

Attach files/media to activities. Track file metadata and relationships.

• drizzle/models/activity-files.ts

Import Batch Tracking

Comprehensive import job tracking. Status lifecycle: queued, running, completed, failed. Timing and statistics per batch. Progress monitoring in UI.

• drizzle/models/import-batches.ts

Architectural Patterns

Role-Based Access Control

User roles and permission system. Basis for admin controls. Permission groups for feature access.

• drizzle/models/roles.ts
• drizzle/models/permissions.ts

Background Job Queue (Inngest)

Event-driven async processing. Reliable job retry with exponential backoff. Step-based workflow for complex operations. Progress monitoring and error handling.

• app/inngest/

Deduplication Strategy

Unique composite keys (ownerId + dedupeKey) for imports. onConflictDoNothing pattern prevents duplicates. Useful for imports from multiple sources.

• drizzle/models/ride-activities.ts

UX/Component Patterns

Status Button

Button that displays async operation states (idle, pending, success, error). Useful for form submissions and API calls.

• app/components/ui/status-button.tsx

Form Validation (Conform + Zod)

Client/server validation with Conform.js and Zod. Constraint generation from schemas. Field error display and form recovery.

• app/components/forms.tsx

Priority Suggestions for trails-cool

High (directly applicable):

• Reactions/Kudos — simple engagement, minimal schema
• Comments — essential social feature
• Following — core for Phase 2 federation
• Live Activity Recording — core outdoor feature
• User Search — discovery

Medium (enhances existing):

• Profile images — user experience
• Activity visibility levels — privacy controls
• Import from Komoot/Strava — integration value
• Ride plan participants — collaborative planning

Lower (future):

• Notes/Blog — content creation
• 2FA — security hardening
• Role-based access — admin features
• Background jobs (Inngest pattern) — already have infra for it