sojorn/sojorn_docs/design/CLIENT_README.md

Sojorn Flutter Client

A calm, text-only social platform built with Flutter.

Status

✅ Core functionality implemented:

• Authentication (sign up, sign in, profile creation)
• Personal feed (chronological from follows)
• Sojorn feed (algorithmic FYP with calm velocity)
• Post creation with tone detection
• Profile viewing with trust tier display
• Clean, minimal UI theme

🚧 Features to be added:

• Engagement actions (appreciate, save, comment on posts)
• Profile editing
• Follow/unfollow functionality
• Category management (opt-in/out)
• Block functionality
• Report content flow
• Saved posts collection view

Prerequisites

• Flutter SDK 3.38.5 or higher
• Dart 3.10.4 or higher
• Supabase account with backend deployed (see ../EDGE_FUNCTIONS.md)

Setup

1. Install Dependencies

cd sojorn
flutter pub get

2. Configuration

The app is already configured to connect to your Supabase backend:

• URL: https://zwkihedetedlatyvplyz.supabase.co
• Anon Key: Embedded in lib/config/supabase_config.dart

If you need to change these values, edit the config file.

3. Run the App

Web

flutter run -d chrome

Android

flutter run -d android

iOS

flutter run -d ios

Project Structure

lib/
├── config/
│   └── supabase_config.dart       # Supabase credentials
├── models/
│   ├── category.dart               # Category and settings models
│   ├── comment.dart                # Comment model
│   ├── post.dart                   # Post, tone analysis models
│   ├── profile.dart                # Profile and stats models
│   ├── trust_state.dart            # Trust state model
│   └── trust_tier.dart             # Trust tier enum
├── providers/
│   ├── api_provider.dart           # API service provider
│   ├── auth_provider.dart          # Auth providers (Riverpod)
│   └── supabase_provider.dart      # Supabase client provider
├── screens/
│   ├── auth/
│   │   ├── auth_gate.dart          # Auth state router
│   │   ├── profile_setup_screen.dart
│   │   ├── sign_in_screen.dart
│   │   └── sign_up_screen.dart
│   ├── compose/
│   │   └── compose_screen.dart     # Post creation
│   ├── home/
│   │   ├── feed-personal_screen.dart
│   │   ├── feed-sojorn_screen.dart
│   │   └── home_shell.dart         # Bottom nav shell
│   └── profile/
│       └── profile_screen.dart     # User profile view
├── services/
│   ├── api_service.dart            # Edge Functions client
│   └── auth_service.dart           # Supabase Auth wrapper
├── theme/
│   └── app_theme.dart              # Calm, minimal theme
├── widgets/
│   ├── compose_fab.dart            # Floating compose button
│   └── post_card.dart              # Post display widget
└── main.dart                       # App entry point

Key Features Implemented

Authentication Flow

1. User signs up with email/password (Supabase Auth)
2. Creates profile via signup Edge Function
3. Sets handle (permanent), display name, and bio
4. Auto-redirects to home on success

Feed System

• Personal Feed: Chronological posts from followed users
• Sojorn Feed: Algorithmic feed using calm velocity ranking
• Pull-to-refresh on both feeds
• Infinite scroll with pagination

Post Creation

• 500 character limit
• Category selection (currently hardcoded to "general", needs UI)
• Tone detection at publish time
• Character count display
• Calm, intentional UX

Profile Display

• Shows display name, handle, bio
• Trust tier badge with harmony score
• Post/follower/following counts
• Daily posting limit progress bar
• Sign out button

Theme

• Muted, calm color palette
• Generous spacing
• Soft borders and shadows
• Clean typography
• Trust tier color coding:
  • New: Gray (#9E9E9E)
  • Trusted: Sage green (#8B9467)
  • Established: Blue-gray (#6B7280)

Testing

Run widget tests:

flutter test

Run analyzer:

flutter analyze

Building for Production

Android APK

flutter build apk --release

iOS

flutter build ios --release

Web

flutter build web --release

Next Steps for Development

High Priority

1. Implement engagement actions

   • Appreciate/unappreciate posts
   • Save/unsave posts
   • Comment on posts (mutual-follow only)
   • Add action buttons to PostCard widget

2. Profile editing

   • Update display name and bio
   • View/edit category preferences

3. Follow/unfollow

   • Add follow button to profiles
   • Show follow status
   • Followers/following lists

Medium Priority

4. Category management

   • Category list screen
   • Opt-in/opt-out toggles
   • Filter feeds by category

5. Block functionality

   • Block users
   • Blocked users list
   • Unblock option

6. Report flow

   • Report posts, comments, profiles
   • Reason input (10-500 chars)

Nice to Have

7. Saved posts collection

   • View saved posts
   • Organize saved posts

8. Settings screen

   • Password change
   • Email update
   • Delete account

9. Notifications

   • New followers
   • Comments on your posts
   • Appreciations

10. Search

    • Search users by handle
    • Search posts by content

Architecture Notes

State Management

• Riverpod for dependency injection and state management
• Providers for auth state, API service, Supabase client
• Local state management in StatefulWidgets for screens

API Communication

• Custom ApiService wrapping Edge Function calls
• Uses http package for HTTP requests
• All calls require auth token from Supabase session
• Error handling with user-friendly messages

Navigation

• Currently using Navigator 1.0 with MaterialPageRoute
• Future: Consider migrating to go_router for deep linking

Design Philosophy

• Calm UI: Muted colors, generous spacing, minimal animations
• Intentional UX: No infinite feeds, clear posting limits, thoughtful language
• Structural boundaries: Blocking, mutual-follow, category opt-in enforced by backend

Troubleshooting

"Failed to get profile" on sign up

• Make sure the signup Edge Function is deployed
• Check Supabase logs for errors
• Verify RLS policies allow profile creation

"Not authenticated" errors

• Ensure user is signed in
• Check Supabase session is valid
• Try signing out and back in

Build errors

• Run flutter clean && flutter pub get
• Check Flutter version: flutter --version
• Update dependencies: flutter pub upgrade

Contributing

When adding features:

1. Match the calm, minimal design language
2. Use the existing theme constants
3. Follow the established patterns for API calls
4. Add error handling and loading states
5. Test on both mobile and web

Resources

• Flutter Documentation
• Supabase Flutter SDK
• Riverpod Documentation
• Backend Edge Functions
• Sojorn Design Philosophy