# Sojorn Flutter Client

A friends-first social platform built with Flutter that prioritizes genuine human connections.

## Status

✅ **Core functionality implemented:**
- Authentication (sign up, sign in, profile creation)
- Personal feed (chronological from follows)
- Sojorn feed (algorithmic FYP with engaging content)
- Post creation with tone detection
- Profile viewing with trust tier display
- Clean, modern 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](../EDGE_FUNCTIONS.md))

## Setup

### 1. Install Dependencies

```bash
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](lib/config/supabase_config.dart)

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

### 3. Run the App

#### Web
```bash
flutter run -d chrome
```

#### Android
```bash
flutter run -d android
```

#### iOS
```bash
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              # Warm, welcoming 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 authentic engagement 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
- Friendly, 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, warm 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:
```bash
flutter test
```

Run analyzer:
```bash
flutter analyze
```

## Building for Production

### Android APK
```bash
flutter build apk --release
```

### iOS
```bash
flutter build ios --release
```

### Web
```bash
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
- **Friendly 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 warm, welcoming 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](https://docs.flutter.dev/)
- [Supabase Flutter SDK](https://supabase.com/docs/reference/dart/introduction)
- [Riverpod Documentation](https://riverpod.dev/)
- [Backend Edge Functions](../EDGE_FUNCTIONS.md)
- [Sojorn Design Philosophy](../README.md)