281 lines
7.3 KiB
Markdown
281 lines
7.3 KiB
Markdown
# 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)
|