diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e90ac5f1..ddb3f83d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,56 +1,736 @@ -## Contribution Guidelines +# ๐ŸŽค Resonate - Onboarding Guide for Contributors -Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure a smooth collaboration, please review the following guidelines. +Welcome to Resonate! This comprehensive guide will walk you through setting up the development environment for Resonate, an open-source social voice platform. Follow these steps carefully to get your local environment ready for contribution. -### Reporting Issues +## ๐Ÿ“‹ Table of Contents -If you come across any issues or bugs while using this project, please help us by reporting them. To submit an issue, follow these steps: +- [Prerequisites](#prerequisites) +- [System Requirements](#system-requirements) +- [Part 1: Flutter App Setup](#part-1-flutter-app-setup) +- [Part 2: Backend Setup (Appwrite + LiveKit)](#part-2-backend-setup-appwrite--livekit) +- [Running the Application](#running-the-application) +- [Troubleshooting](#troubleshooting) +- [Getting Help](#getting-help) -1. Go to the [Issues](https://github.com/AOSSIE-Org/Resonate/issues) tab on the GitHub repository. -2. Click on the "New Issue" button. -3. Provide a descriptive title and detailed description of the issue, including any error messages or steps to reproduce. -4. If applicable, add relevant labels or tags to categorize the issue. -5. Submit the issue and wait for further instructions or clarifications. +--- -### Feature Requests +## Prerequisites -Have a great idea for a new feature or improvement? We'd love to hear it! Follow these steps to suggest a feature: +Before you begin, ensure you have the following installed on your system: -1. Go to the [Issues](https://github.com/AOSSIE-Org/Resonate/issues) tab on the GitHub repository. -2. Click on the "New Issue" button. -3. Clearly describe the proposed feature or improvement, including any use cases or benefits. -4. Submit the feature request and engage in any discussions or feedback related to it. +### Required Software -### Pull Requests +1. **Git** - Version control system + - Download: https://git-scm.com/downloads + - Verify installation: `git --version` -We welcome contributions in the form of pull requests only to the `dev` branch. To submit a pull request, please follow these guidelines: +2. **Flutter SDK** (Latest stable version recommended) + - Download: https://docs.flutter.dev/get-started/install + - Recommended: Flutter 3.19 or higher + - Verify installation: `flutter --version` -1. Fork the repository and create your branch. -2. Make the necessary code changes or improvements in your branch. -3. Ensure your code adheres to the project's coding style and guidelines. -4. Document any relevant changes or updates in the project's documentation. -5. Submit the pull request, providing a clear title and description of the changes made. -6. Engage in any feedback or discussions related to your pull request. +3. **Android Studio** or **VS Code** + - Android Studio: https://developer.android.com/studio + - VS Code: https://code.visualstudio.com/ -### Code Style and Guidelines +4. **Android SDK** (for Android development) + - Install via Android Studio + - Minimum SDK: API 21 (Android 5.0) + - Target SDK: API 34 or higher -To maintain consistency throughout the project's codebase, please adhere to the following guidelines: +5. **Xcode** (for iOS development - macOS only) + - Install from Mac App Store + - Minimum version: Xcode 14 or higher -- Follow the Dart coding style conventions. -- Use meaningful variable and function names. -- Add comments when necessary to explain complex logic or intent. -- Ensure code is properly formatted by using `dartfmt`. +6. **Node.js and npm** (for backend setup) + - Download: https://nodejs.org/ + - Recommended: Node.js 18 LTS or higher + - Verify: `node --version` and `npm --version` -### Commit Structure +7. **Appwrite CLI** (for backend deployment) + - Install: `npm install -g appwrite-cli` + - Verify: `appwrite --version` -Make sure to use conventional commit structure as follows: +### Optional but Recommended +- **Docker Desktop** (for local Appwrite instance) + - Download: https://www.docker.com/products/docker-desktop + +- **Postman** or **Thunder Client** (for API testing) + +--- + +## System Requirements + +### Minimum Hardware Requirements +- **RAM**: 8 GB (16 GB recommended) +- **Storage**: 10 GB free space +- **Processor**: Intel i5 or equivalent + +### Operating Systems Supported +- Windows 10/11 +- macOS 10.15 or higher +- Linux (Ubuntu 20.04 or higher) + +--- + +## Part 1: Flutter App Setup + +### Step 1: Fork and Clone the Repository + +1. **Fork the repository** + - Go to https://github.com/AOSSIE-Org/Resonate + - Click the "Fork" button in the top right corner + - This creates a copy in your GitHub account + +2. **Clone your forked repository** + ```bash + git clone https://github.com/YOUR_USERNAME/Resonate.git + cd Resonate + ``` + +3. **Add upstream remote** (to sync with main repo) + ```bash + git remote add upstream https://github.com/AOSSIE-Org/Resonate.git + git remote -v # Verify remotes + ``` + +### Step 2: Install Flutter Dependencies + +1. **Check Flutter installation** + ```bash + flutter doctor -v + ``` + - This command checks your Flutter environment and displays issues + - Fix any issues reported before proceeding + +2. **Clean and get dependencies** + ```bash + # Clean previous builds (if any) + flutter clean + + # Get all packages + flutter pub get + ``` + +3. **Verify dependencies installation** + ```bash + flutter pub outdated # Check for outdated packages + ``` + +### Step 3: Configure Android Setup + +1. **Accept Android licenses** + ```bash + flutter doctor --android-licenses + ``` + Accept all licenses by typing 'y' + +2. **Configure Android SDK** (if needed) + - Open Android Studio + - Go to: Settings > Appearance & Behavior > System Settings > Android SDK + - Ensure the following are installed: + - Android SDK Platform 34 (or latest) + - Android SDK Build-Tools + - Android SDK Command-line Tools + - Android SDK Platform-Tools + - Android Emulator + +3. **Create Android Virtual Device (AVD)** + - Open Android Studio > Device Manager + - Click "Create Device" + - Select a device (e.g., Pixel 5) + - Select system image (API 34 recommended) + - Finish setup + +### Step 4: Configure iOS Setup (macOS only) + +1. **Install Xcode Command Line Tools** + ```bash + sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer + sudo xcodebuild -runFirstLaunch + ``` + +2. **Install CocoaPods** + ```bash + sudo gem install cocoapods + ``` + +3. **Setup iOS dependencies** + ```bash + cd ios + pod install + cd .. + ``` + +4. **Open iOS Simulator** + ```bash + open -a Simulator + ``` + +### Step 5: Project Configuration + +1. **Create environment configuration file** + + Create a file named `.env` in the project root (if not exists): + ```bash + touch .env + ``` + +2. **Configure the `.env` file** (you'll add values after backend setup): + ```env + # Appwrite Configuration + APPWRITE_ENDPOINT=your_appwrite_endpoint + APPWRITE_PROJECT_ID=your_project_id + + # LiveKit Configuration + LIVEKIT_URL=your_livekit_url + ``` + +--- + +## Part 2: Backend Setup (Appwrite + LiveKit) + +### Option A: Using Appwrite Cloud (Recommended for Beginners) + +#### Step 1: Create Appwrite Account + +1. Go to https://cloud.appwrite.io/ +2. Sign up for a free account +3. Create a new project +4. Note down your: + - **Project ID** + - **Endpoint** (usually `https://cloud.appwrite.io/v1`) + - **API Endpoint** + +#### Step 2: Configure Appwrite Project + +1. **Create Platform** + - In your Appwrite project, go to "Settings" > "Platforms" + - Click "Add Platform" + - Select your platform: + - For **Android**: + - Name: `Resonate Android` + - Package Name: `com.resonate.resonate` + - For **iOS**: + - Name: `Resonate iOS` + - Bundle ID: `com.resonate.resonate` + - For **Web** (optional): + - Name: `Resonate Web` + - Hostname: `localhost` + +2. **Generate API Key** + - Go to "Settings" > "API Keys" + - Click "Create API Key" + - Give it a name (e.g., "Backend Functions") + - Select scopes (All scopes for development) + - Copy and save the API Key securely + +#### Step 3: Setup LiveKit + +1. **Create LiveKit Cloud Account** + - Go to https://livekit.io/cloud + - Sign up for a free account + - Create a new project + +2. **Get LiveKit Credentials** + - Go to your project settings + - Copy the following: + - **LiveKit URL/Host** (e.g., `wss://your-project.livekit.cloud`) + - **API Key** + - **API Secret** + - Keep these credentials secure + +3. **Configure LiveKit Webhook** (Optional but recommended) + - In LiveKit dashboard, go to Settings > Webhooks + - Add webhook URL: `https://[your-appwrite-endpoint]/v1/functions/[livekit-webhook-function-id]/executions` + +#### Step 4: Deploy Backend Functions + +1. **Clone Backend Repository** + ```bash + cd .. # Go back to parent directory + git clone https://github.com/AOSSIE-Org/Resonate-Backend.git + cd Resonate-Backend + ``` + +2. **Install Appwrite CLI** (if not already installed) + ```bash + npm install -g appwrite-cli + ``` + +3. **Login to Appwrite CLI** + ```bash + appwrite login + ``` + Follow the prompts to authenticate with your Appwrite account + +4. **Initialize Appwrite Project** + ```bash + appwrite init project + ``` + - Select your project from the list + - Configure endpoint if needed + +5. **Configure Environment Variables for Functions** + + Edit the function configuration files to add your LiveKit credentials: + + For each function that requires LiveKit (check `appwrite.json`), you'll need to set: + - `LIVEKIT_HOST`: Your LiveKit URL + - `LIVEKIT_API_KEY`: Your LiveKit API Key + - `LIVEKIT_API_SECRET`: Your LiveKit API Secret + +6. **Deploy Functions** + + **Option 1: Deploy all functions at once** + ```bash + appwrite deploy function + ``` + + **Option 2: Deploy individual functions** + ```bash + # Deploy room creation function + appwrite deploy function --functionId create-room + + # Deploy other functions similarly + appwrite deploy function --functionId join-room + appwrite deploy function --functionId delete-room + appwrite deploy function --functionId livekit-webhook + appwrite deploy function --functionId match-maker + appwrite deploy function --functionId send-otp + appwrite deploy function --functionId verify-otp + appwrite deploy function --functionId verify-email + appwrite deploy function --functionId discussion-isTime-checker + appwrite deploy function --functionId database-cleaner + ``` + +7. **Run the automated setup script** (Recommended) + + **For Linux/macOS:** + ```bash + chmod +x init.sh + ./init.sh + ``` + + **For Windows (PowerShell):** + ```powershell + .\init.ps1 + ``` + + This script will automatically: + - Set up Appwrite collections + - Configure database schemas + - Deploy cloud functions + - Set up authentication + +#### Step 5: Configure Database Collections + +The Appwrite backend requires several collections. The `init.sh` script creates them, but here's what they are: + +1. **Users Collection**: User profiles and data +2. **Rooms Collection**: Room/discussion data +3. **Stories Collection**: Story content +4. **Chapters Collection**: Chapter data for stories +5. **Participants Collection**: Active room participants +6. **Pairs Collection**: Pair chat data +7. **Notifications Collection**: User notifications + +### Option B: Self-Hosted Appwrite (Advanced Users) + +If you prefer to run Appwrite locally: + +1. **Install Docker Desktop** + - Download from https://www.docker.com/products/docker-desktop + +2. **Run Appwrite using Docker** + ```bash + docker run -it --rm \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ + --entrypoint="install" \ + appwrite/appwrite:latest + ``` + +3. **Access Appwrite Console** + - Open http://localhost + - Complete the setup wizard + - Create your first project + +4. **Follow the same steps as Option A** for project configuration and function deployment + +#### Step 6: Update Flutter App Configuration + +1. **Go back to the Flutter app directory** + ```bash + cd ../Resonate + ``` + +2. **Update the `.env` file** with your credentials: + ```env + APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1 + APPWRITE_PROJECT_ID=your_project_id_here + LIVEKIT_URL=wss://your-project.livekit.cloud + ``` + +3. **Create/Update configuration files** + + Check if your app has a configuration file (usually in `lib/utils/constants.dart` or similar): + ```dart + class AppwriteConstants { + static const String endpoint = 'YOUR_APPWRITE_ENDPOINT'; + static const String projectId = 'YOUR_PROJECT_ID'; + } + + class LivekitConstants { + static const String url = 'YOUR_LIVEKIT_URL'; + } + ``` + +--- + +## Running the Application + +### Step 1: Start the Development Environment + +1. **Start an emulator or connect a physical device** + + **For Android:** + ```bash + # List available emulators + flutter emulators + + # Start a specific emulator + flutter emulators --launch + + # Or start from Android Studio: Tools > Device Manager > Run + ``` + + **For iOS (macOS only):** + ```bash + open -a Simulator + ``` + + **For Physical Device:** + - Enable Developer Options and USB Debugging (Android) + - Trust the computer (iOS) + - Connect via USB + - Verify: `flutter devices` + +### Step 2: Run the Application + +1. **Check connected devices** + ```bash + flutter devices + ``` + +2. **Run the app** + ```bash + # Run in debug mode + flutter run + + # Run in release mode + flutter run --release + + # Run on a specific device + flutter run -d + ``` + +3. **Hot reload during development** + - Press `r` in the terminal for hot reload + - Press `R` for hot restart + - Press `q` to quit + +### Step 3: Verify Everything Works + +1. **Test basic functionality:** + - App launches successfully + - You can create an account + - Authentication works + - You can navigate through the app + +2. **Test voice features:** + - Create a room + - Join a room + - Test audio permissions + - Verify LiveKit connection + +--- + +## Troubleshooting + +### Common Issues and Solutions + +#### Issue 1: Flutter Doctor Shows Errors + +**Problem:** `flutter doctor` shows red X marks + +**Solution:** +```bash +# For Android toolchain issues +flutter doctor --android-licenses + +# For missing dependencies +flutter doctor -v # Shows detailed info + +# Update Flutter +flutter upgrade +``` + +#### Issue 2: Gradle Build Failures (Android) + +**Problem:** Build fails with Gradle errors + +**Solution:** +```bash +# Clean the project +flutter clean + +# Navigate to android folder +cd android + +# Clean Gradle +./gradlew clean + +# Go back and rebuild +cd .. +flutter pub get +flutter run +``` + +#### Issue 3: Pod Install Failures (iOS) + +**Problem:** CocoaPods installation fails + +**Solution:** +```bash +cd ios + +# Update pod repo +pod repo update + +# Clean pods +rm -rf Pods Podfile.lock + +# Reinstall +pod install + +cd .. +``` + +#### Issue 4: Appwrite Connection Issues + +**Problem:** Cannot connect to Appwrite + +**Solution:** +1. Verify your endpoint URL is correct +2. Check if project ID matches +3. Ensure platform is properly configured in Appwrite console +4. Check firewall settings +5. For self-hosted: Verify Docker containers are running (`docker ps`) + +#### Issue 5: LiveKit Connection Failures + +**Problem:** Unable to join voice rooms + +**Solution:** +1. Verify LiveKit credentials are correct +2. Check if WebSocket connection is allowed +3. Test with LiveKit's example app first +4. Verify microphone permissions are granted +5. Check network firewall settings + +#### Issue 6: Build Number Conflicts + +**Problem:** App won't install due to version conflict + +**Solution:** +```bash +# Uninstall previous version +flutter clean + +# On Android device/emulator +adb uninstall com.resonate.resonate + +# Reinstall +flutter run ``` -: - โ”‚ โ”‚ - โ”‚ โ””โ”€โซธ Summary. Not capitalized. No period at the end. - โ”‚ - โ””โ”€โซธ Commit Type: docs|feat|fix|perf|refactor|test + +#### Issue 7: Missing Dependencies + +**Problem:** Package dependencies not resolving + +**Solution:** +```bash +# Remove lock file +rm pubspec.lock + +# Clear pub cache +flutter pub cache repair + +# Get dependencies again +flutter pub get +``` + +### Getting Detailed Error Logs + +```bash +# Run with verbose logging +flutter run -v + +# For specific device logs +# Android: +adb logcat + +# iOS: +xcrun simctl spawn booted log stream --predicate 'eventMessage contains "flutter"' ``` -Know more about Conventional Commits [here](https://www.conventionalcommits.org/en/v1.0.0/). +--- + +## Development Workflow + +### Before Making Changes + +1. **Sync with upstream** + ```bash + git fetch upstream + git checkout dev + git merge upstream/dev + ``` + +2. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +### Making Changes + +1. Make your code changes +2. Test thoroughly on both Android and iOS (if possible) +3. Follow the project's coding standards +4. Write meaningful commit messages + +### Code Quality Checks + +```bash +# Check for formatting issues +flutter format . + +# Run static analysis +flutter analyze + +# Run tests +flutter test +``` + +### Submitting Changes + +1. **Push to your fork** + ```bash + git add . + git commit -m "feat: your feature description" + git push origin feature/your-feature-name + ``` + +2. **Create Pull Request** + - Go to your fork on GitHub + - Click "New Pull Request" + - Set base repository: `AOSSIE-Org/Resonate` + - Set base branch: `dev` + - Fill in the PR template + - Submit for review + +--- + +## Getting Help + +### Communication Channels + +- **Discord**: https://discord.gg/MMZBadkYFm +- **Email**: aossie.oss@gmail.com +- **GitHub Issues**: https://github.com/AOSSIE-Org/Resonate/issues +- **GitHub Discussions**: https://github.com/AOSSIE-Org/Resonate/discussions + +### Resources + +- **Contribution Guidelines**: [CONTRIBUTING.md](CONTRIBUTING.md) +- **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) +- **Flutter Documentation**: https://docs.flutter.dev/ +- **Appwrite Documentation**: https://appwrite.io/docs +- **LiveKit Documentation**: https://docs.livekit.io/ + +### Tips for New Contributors + +1. **Start Small**: Look for issues labeled `good first issue` +2. **Ask Questions**: Don't hesitate to ask in Discord +3. **Read Existing Code**: Understand the project structure +4. **Test Your Changes**: Always test on multiple devices +5. **Be Patient**: Code review takes time + +--- + +## Next Steps + +Now that your environment is set up: + +1. โœ… Explore the codebase structure +2. โœ… Check [open issues](https://github.com/AOSSIE-Org/Resonate/issues) +3. โœ… Join our [Discord community](https://discord.gg/MMZBadkYFm) +4. โœ… Read the [Contributing Guidelines](CONTRIBUTING.md) +5. โœ… Make your first contribution! + +--- + +## Additional Notes + +### Project Structure +``` +Resonate/ +โ”œโ”€โ”€ android/ # Android native code +โ”œโ”€โ”€ ios/ # iOS native code +โ”œโ”€โ”€ lib/ # Main Dart code +โ”‚ โ”œโ”€โ”€ models/ # Data models +โ”‚ โ”œโ”€โ”€ views/ # UI screens +โ”‚ โ”œโ”€โ”€ controllers/ # Business logic +โ”‚ โ”œโ”€โ”€ utils/ # Utility functions +โ”‚ โ””โ”€โ”€ main.dart # Entry point +โ”œโ”€โ”€ test/ # Test files +โ”œโ”€โ”€ assets/ # Images, fonts, etc. +โ””โ”€โ”€ pubspec.yaml # Dependencies +``` + +### Useful Commands Reference + +```bash +# Flutter Commands +flutter doctor # Check installation +flutter devices # List devices +flutter run # Run app +flutter build apk # Build Android APK +flutter build ipa # Build iOS IPA +flutter clean # Clean build files +flutter pub get # Get dependencies +flutter pub upgrade # Upgrade dependencies +flutter analyze # Static analysis +flutter test # Run tests + +# Git Commands +git status # Check changes +git log --oneline # View commit history +git branch # List branches +git checkout -b branch # Create new branch +git pull upstream dev # Pull from upstream +git push origin branch # Push to your fork + +# Appwrite Commands +appwrite login # Login to Appwrite +appwrite deploy # Deploy functions +appwrite init # Initialize project +``` + +--- + +**Happy Contributing! ๐ŸŽ‰** + +Thank you for contributing to Resonate. Together, we're building an amazing open-source voice platform! \ No newline at end of file diff --git a/README.md b/README.md index 1b33b7f4..256a0cc4 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,452 @@ -
- - Resonate logo -Resonate logo - +# ๐ŸŽค Resonate - An Open Source Social Voice Platform -# :microphone: Resonate - An Open Source Social Voice Platform +
-
-
- - - - - Appwrite Logo - - -          - - - - Livekit Logo - - - -
-
-
+![Resonate Logo](assets/images/aossie_logo.png) -
- -[![License:GPL-3.0](https://img.shields.io/badge/License-GPL-yellow.svg)](https://opensource.org/license/gpl-3-0/) -![GitHub Org's stars](https://img.shields.io/github/stars/AOSSIE-Org/Resonate?style=social) +[![License: GPL-3.0](https://img.shields.io/badge/License-GPL-yellow.svg)](https://opensource.org/license/gpl-3-0/) +[![GitHub Stars](https://img.shields.io/github/stars/AOSSIE-Org/Resonate?style=social)](https://github.com/AOSSIE-Org/Resonate/stargazers) [![Get it on Google Play](https://img.shields.io/badge/Get_it_on-Google_Play-00C851?style=for-the-badge&logo=google-play&logoColor=white)](https://play.google.com/store/apps/details?id=com.resonate.resonate) +**Powered by:** + +[![Appwrite](https://img.shields.io/badge/Appwrite-F02E65?style=for-the-badge&logo=appwrite&logoColor=white)](https://appwrite.io) +[![LiveKit](https://img.shields.io/badge/LiveKit-00ADD8?style=for-the-badge)](https://livekit.io) +[![Flutter](https://img.shields.io/badge/Flutter-02569B?style=for-the-badge&logo=flutter&logoColor=white)](https://flutter.dev) +
-With social voice platforms like Spotify, Clubhouse, and Twitter Spaces experiencing rapid growth, Resonate is here to harness the power of open-source for voice-based social media. Whether it's sharing immersive stories, engaging in dynamic live discussions, or connecting through pair chats and voice calls, Resonate is designed to put voice at the center of your social experience. By fostering innovation and growth, this project aims to reach new heights, continually expanding its features and community, all while staying true to the open-source spirit of collaboration and transparency. +--- -## :rocket: Features +## ๐Ÿ“– About Resonate -1. Real-time Audio Communication by joining rooms and talking to people. -2. Ability to create rooms and moderate speakers and events. -3. Create Scheduled Rooms and notify subscribers as reminders to join -4. Listen to and Stories as chapters with synced lyrics, browse through entire catalog of stories following your favourate creators and waiting for their latest chapter/story releases. Post your own stories having chapters. (work in progess) -5. Pair chatting to enable users to find random partners to talk to in the app. -6. Friend People/Profiles enabling your self to talk on voice calls/realtime messaging with them (coming soon) +With social voice platforms like Spotify, Clubhouse, and Twitter Spaces experiencing rapid growth, **Resonate** harnesses the power of open-source for voice-based social media. Whether it's sharing immersive stories, engaging in dynamic live discussions, or connecting through pair chats and voice calls, Resonate is designed to put voice at the center of your social experience. -## :computer: Technologies Used +By fostering innovation and growth, this project aims to reach new heights, continually expanding its features and community, all while staying true to the open-source spirit of collaboration and transparency. -1. **Flutter** - Mobile application -2. **Appwrite** - Authentication, Database, Storage and Cloud functions. -3. **LiveKit** - Web Real-Time Communication +--- -## :link: Repository Links +## โœจ Features -1. [Resonate Flutter App](https://github.com/AOSSIE-Org/Resonate) -2. [Resonate Backend](https://github.com/AOSSIE-Org/Resonate-Backend) +### Current Features -## :four_leaf_clover: Getting Started +๐ŸŽ™๏ธ **Real-time Audio Rooms** +- Join voice rooms and talk to people in real-time +- Create your own rooms with custom settings +- Moderate speakers and manage room events -Resonate is a wide project taking use of other software solutions like Appwrite and Livekit, starting up can be a little challenging +๐Ÿ“… **Scheduled Rooms** +- Create scheduled discussions +- Notify subscribers with reminders +- Never miss important conversations -We offer a guide for walking you through setting up the entire project, including a script that automates the set up of the backend environment for you. -Please go through and strictly follow the [Onboarding Guide](https://github.com/AOSSIE-Org/Resonate/blob/master/ONBOARDING.md) for setting up the project for development and further contribution +๐Ÿ“š **Audio Stories** *(Work in Progress)* +- Listen to stories as chapters with synced lyrics +- Browse through entire catalog of stories +- Follow your favorite creators +- Wait for latest chapter/story releases +- Post your own stories with chapters -## โ–ถ๏ธ Play Store Feature Graphic +๐Ÿ‘ฅ **Pair Chat** +- Find random partners to talk to +- One-on-one voice conversations +- Meet new people in the community -
-Resonate_V1 1 +๐ŸŽจ **Customizable Themes** +- Multiple theme options: Forest, Amber, Classic, Cream, Time, Vintage +- Personalize your app experience + +๐ŸŒ **Multi-language Support** +- Available in multiple languages +- Easy translation contribution + +### Coming Soon + +โœ… Friend profiles and connections +โœ… Direct voice calls and messaging +โœ… Enhanced story marketplace +โœ… Advanced search and discovery + +--- + +## ๐Ÿ—๏ธ Architecture + +Resonate is built using modern, scalable technologies: + +- **Frontend**: Flutter (Dart) - Cross-platform mobile application +- **Backend**: Appwrite - Authentication, Database, Storage, Cloud Functions +- **Real-time Communication**: LiveKit - WebRTC for voice/video +- **State Management**: GetX / Provider +- **Database**: Appwrite Database Collections + +--- + +## ๐Ÿš€ Quick Start for New Contributors + +### Prerequisites + +Before you begin, make sure you have: + +- โœ… **Flutter SDK** (3.19 or higher) - [Install Guide](https://docs.flutter.dev/get-started/install) +- โœ… **Git** - [Download](https://git-scm.com/downloads) +- โœ… **Android Studio** or **VS Code** with Flutter extensions +- โœ… **Node.js & npm** (for backend) - [Download](https://nodejs.org/) +- โœ… **Appwrite CLI** - Install: `npm install -g appwrite-cli` + +### Quick Setup (5 Minutes) + +```bash +# 1. Clone the repository +git clone https://github.com/YOUR_USERNAME/Resonate.git +cd Resonate + +# 2. Install dependencies +flutter pub get + +# 3. Check your Flutter setup +flutter doctor + +# 4. Run the app +flutter run +``` + +### Full Setup Guide -
+For detailed setup instructions including backend configuration, please refer to our comprehensive **[Onboarding Guide](ONBOARDING.md)**. -## :movie_camera: App Screenshots +The onboarding guide covers: +- ๐Ÿ“ฆ Complete environment setup +- ๐Ÿ”ง Backend configuration (Appwrite + LiveKit) +- ๐Ÿ› Troubleshooting common issues +- ๐Ÿ’ป Development workflow +- ๐Ÿค Contribution guidelines + +--- + +## ๐Ÿ“‚ Project Structure + +``` +Resonate/ +โ”œโ”€โ”€ android/ # Android native code +โ”œโ”€โ”€ ios/ # iOS native code +โ”œโ”€โ”€ lib/ +โ”‚ โ”œโ”€โ”€ main.dart # Application entry point +โ”‚ โ”œโ”€โ”€ models/ # Data models +โ”‚ โ”œโ”€โ”€ views/ # UI screens and widgets +โ”‚ โ”‚ โ”œโ”€โ”€ screens/ # Main app screens +โ”‚ โ”‚ โ””โ”€โ”€ widgets/ # Reusable widgets +โ”‚ โ”œโ”€โ”€ controllers/ # Business logic (GetX/Provider) +โ”‚ โ”œโ”€โ”€ services/ # API and service classes +โ”‚ โ”œโ”€โ”€ utils/ # Utility functions and constants +โ”‚ โ”œโ”€โ”€ routes/ # App routing +โ”‚ โ””โ”€โ”€ themes/ # Theme configurations +โ”œโ”€โ”€ assets/ +โ”‚ โ”œโ”€โ”€ images/ # Image assets +โ”‚ โ”œโ”€โ”€ icons/ # App icons +โ”‚ โ””โ”€โ”€ translations/ # Localization files +โ”œโ”€โ”€ test/ # Unit and widget tests +โ”œโ”€โ”€ docs/ # Documentation +โ”œโ”€โ”€ pubspec.yaml # Dependencies +โ””โ”€โ”€ README.md # This file +``` + +--- + +## ๐Ÿ”— Repository Links + +This project consists of two main repositories: + +1. **[Resonate Flutter App](https://github.com/AOSSIE-Org/Resonate)** - Mobile application (This repo) +2. **[Resonate Backend](https://github.com/AOSSIE-Org/Resonate-Backend)** - Appwrite Cloud Functions + +--- + +## ๐Ÿค Contributing + +We โค๏ธ contributions! Resonate is open-source and we welcome contributors of all skill levels. + +### How to Contribute + +1. **๐Ÿด Fork the Repository** + - Click the "Fork" button at the top right of this page + +2. **๐Ÿ“ฅ Clone Your Fork** + ```bash + git clone https://github.com/YOUR_USERNAME/Resonate.git + cd Resonate + ``` + +3. **๐ŸŒฟ Create a Branch** + ```bash + git checkout -b feature/amazing-feature + ``` + +4. **โœจ Make Your Changes** + - Write clean, well-documented code + - Follow the existing code style + - Test your changes thoroughly + +5. **โœ… Commit Your Changes** + ```bash + git commit -m "feat: add amazing feature" + ``` + +6. **๐Ÿ“ค Push to Your Fork** + ```bash + git push origin feature/amazing-feature + ``` + +7. **๐ŸŽ‰ Open a Pull Request** + - Go to the original repository + - Click "New Pull Request" + - Select your branch + - Fill in the PR template + - Submit for review! + +### Contribution Guidelines + +Please read our detailed [Contribution Guidelines](CONTRIBUTING.md) before submitting a PR. + +**Important Notes:** +- ๐ŸŽฏ All contributions should target the `dev` branch, not `master` +- ๐Ÿ“ Follow the commit message format: `type: description` +- ๐Ÿงช Include tests for new features +- ๐Ÿ“– Update documentation as needed +- โœ… Ensure all checks pass before requesting review + +### Good First Issues + +New to open source? Look for issues labeled with: +- `good first issue` - Perfect for beginners +- `documentation` - Help improve our docs +- `bug` - Fix existing issues +- `enhancement` - Add new features + +--- + +## ๐ŸŽจ App Screenshots
- -| Login Screen (Forest) | Home Screen (Time) | Create Room Screen (Time) | -| :----------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | -| | | | -| Room Screen (Cream) | Profile Screen (Amber) | Explore Story (Forest) | -| :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | -| | | | +| Login Screen | Home Screen | Create Room | +|:---:|:---:|:---:| +| | | | -| Explore Story (Amber) | Theme Screen (Vintage) | Upcoming Room Screen (Cream) | -| :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | -| | | | +| Room Screen | Profile | Explore Stories | +|:---:|:---:|:---:| +| | | |
-## :raised_hands: Contributing +--- -:star: Don't forget to star this repository if you find it useful! :star: +## ๐Ÿ› ๏ธ Tech Stack -Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed (P.S. to the `dev` branch). To ensure a smooth collaboration, Refer to the [Contribution Guidelines](https://github.com/AOSSIE-Org/Resonate/blob/master/CONTRIBUTING.md). +### Frontend +- **Framework**: Flutter 3.19+ +- **Language**: Dart +- **State Management**: GetX / Provider +- **UI Components**: Material Design -We appreciate your contributions and look forward to working with you to make this project even better! +### Backend +- **BaaS**: Appwrite +- **Authentication**: Appwrite Auth (Email, Phone, OAuth) +- **Database**: Appwrite Database +- **Storage**: Appwrite Storage +- **Functions**: Appwrite Cloud Functions (Node.js) -By following these guidelines, we can maintain a productive and collaborative open-source environment. Thank you for your support! +### Real-time Communication +- **WebRTC**: LiveKit +- **Audio**: LiveKit SDK +- **Rooms**: LiveKit Room Management -## :v: Maintainers +### Tools & Services +- **Version Control**: Git & GitHub +- **CI/CD**: GitHub Actions +- **Package Manager**: Pub +- **Build Tools**: Gradle (Android), Xcode (iOS) -- [Jaideep Prasad](https://github.com/jddeep) -- [Chandan S Gowda](https://github.com/chandansgowda) +--- -## :mailbox: Communication Channels +## ๐Ÿ“ฑ Installation -If you have any questions, need clarifications, or want to discuss ideas, feel free to reach out through the following channels: +### For Users -- [Discord Server](https://discord.gg/MMZBadkYFm) -- [Email](mailto:aossie.oss@gmail.com) +Download Resonate from Google Play Store: + + Get it on Google Play + - +### For Developers -## :round_pushpin: License +Follow our [Onboarding Guide](ONBOARDING.md) for complete setup instructions. -Distributed under the [GNU General Public License](https://opensource.org/license/gpl-3-0/). See [LICENSE](https://github.com/AOSSIE-Org/Resonate/blob/master/LICENSE) for more information. +--- -## ๐Ÿ’ช Thanks To All Contributors +## ๐Ÿ› Troubleshooting -Thanks a lot for spending your time helping Resonate grow. Keep rocking ๐Ÿฅ‚ +### Common Issues - - Contributors - -
+**Issue: "Cannot connect to Appwrite"** +- Check your internet connection +- Verify Appwrite endpoint URL +- Ensure project ID is correct + +**Issue: "LiveKit connection failed"** +- Check microphone permissions +- Verify LiveKit credentials +- Test network connectivity + +**Issue: "Build failed"** +- Run `flutter clean` +- Delete `pubspec.lock` +- Run `flutter pub get` +- Try building again + +For more troubleshooting tips, see our [Onboarding Guide - Troubleshooting Section](ONBOARDING.md#troubleshooting). + +--- + +## ๐Ÿ“š Documentation + +- **[Onboarding Guide](ONBOARDING.md)** - Complete setup for contributors +- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute +- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines +- **[Security Policy](SECURITY.md)** - Report security issues +- **[Translation Guide](TRANSLATIONS.md)** - Help translate the app + +--- + +## ๐ŸŒŸ Community & Support + +### Get Help + +- ๐Ÿ’ฌ **Discord**: [Join our server](https://discord.gg/MMZBadkYFm) +- ๐Ÿ“ง **Email**: aossie.oss@gmail.com +- ๐Ÿ› **Issues**: [Report bugs](https://github.com/AOSSIE-Org/Resonate/issues) +- ๐Ÿ’ก **Discussions**: [Ask questions](https://github.com/AOSSIE-Org/Resonate/discussions) + +### Stay Updated + +- โญ Star this repository to show support +- ๐Ÿ‘€ Watch for updates and releases +- ๐Ÿฆ Follow us on social media (coming soon!) + +--- + +## ๐Ÿ‘ฅ Maintainers + +- **[Jaideep Prasad](https://github.com/jddeep)** - Project Lead +- **[Chandan S Gowda](https://github.com/chandansgowda)** - Core Maintainer + +--- + +## ๐Ÿ™ Contributors + +Thanks to all our amazing contributors! ๐ŸŽ‰ + +[![Contributors](https://contrib.rocks/image?repo=AOSSIE-Org/Resonate)](https://github.com/AOSSIE-Org/Resonate/graphs/contributors) + +Want to see your name here? [Start contributing!](#contributing) + +--- + +## ๐Ÿ“œ License + +This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details. + +``` +Resonate - An Open Source Social Voice Platform +Copyright (C) 2023-2025 AOSSIE + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. +``` + +--- + +## ๐Ÿ† Achievements + +- ๐ŸŽ“ **Google Summer of Code 2023 & 2024** - Selected Project +- ๐ŸŒŸ **290+ GitHub Stars** +- ๐Ÿด **270+ Forks** +- ๐Ÿ‘ฅ **45+ Contributors** +- ๐Ÿ“ฅ **Available on Google Play Store** + +--- + +## ๐ŸŽฏ Roadmap + +### Q1 2025 +- [ ] Enhanced story marketplace +- [ ] Advanced search functionality +- [ ] Profile customization +- [ ] Friend system implementation + +### Q2 2025 +- [ ] Direct messaging +- [ ] Voice notes feature +- [ ] Notification improvements +- [ ] Performance optimizations + +### Q3 2025 +- [ ] Web platform support +- [ ] Desktop application +- [ ] Advanced analytics +- [ ] Premium features + +*Want to suggest a feature? [Open a discussion](https://github.com/AOSSIE-Org/Resonate/discussions)!* + +--- + +## ๐Ÿค— Acknowledgments + +- **AOSSIE** - Australian Open Source Software Innovation and Education +- **Appwrite** - For providing an amazing backend platform +- **LiveKit** - For real-time communication infrastructure +- **Flutter** - For the cross-platform framework +- **All Contributors** - For making this project possible + +--- + +## ๐Ÿ“ž Contact + +- **Organization**: AOSSIE (Australian Open Source Software Innovation and Education) +- **Email**: aossie.oss@gmail.com +- **Discord**: https://discord.gg/MMZBadkYFm +- **GitHub**: https://github.com/AOSSIE-Org + +--- + +
+ +### โญ Don't forget to star this repository if you find it useful! โญ + +**Made with โค๏ธ by the AOSSIE Community** + +
+ +--- + +## ๐Ÿ’ Support the Project + +If you like Resonate, consider: +- โญ Starring the repository +- ๐Ÿ› Reporting bugs +- ๐Ÿ’ก Suggesting features +- ๐Ÿค Contributing code +- ๐Ÿ“ข Spreading the word + +Every contribution, no matter how small, makes a difference! + +--- + +**Happy Contributing! ๐ŸŽ‰** \ No newline at end of file diff --git a/SETUP_CHECKLIST.md b/SETUP_CHECKLIST.md new file mode 100644 index 00000000..a6dcbc59 --- /dev/null +++ b/SETUP_CHECKLIST.md @@ -0,0 +1,131 @@ +๐Ÿ“‹ Resonate Setup Checklist +Use this checklist to ensure you've completed all setup steps correctly. + +Pre-Setup Requirements + Git installed (git --version) + Flutter SDK installed (flutter --version) + Android Studio or VS Code installed + Android SDK installed (API 21+) + Xcode installed (macOS only, for iOS) + Node.js and npm installed (node --version, npm --version) + Appwrite CLI installed (appwrite --version) +Part 1: Flutter App Setup +Repository Setup + Forked the repository on GitHub + Cloned your fork locally + Added upstream remote + Verified remotes with git remote -v +Flutter Configuration + Ran flutter doctor (all checks pass) + Ran flutter clean + Ran flutter pub get (no errors) + Accepted Android licenses (flutter doctor --android-licenses) +Device Setup + Android emulator created OR physical device connected + iOS simulator installed (macOS only) + Device shows in flutter devices +Environment Configuration + Created .env file in project root + Added Appwrite configuration (will update after backend setup) + Added LiveKit configuration (will update after backend setup) +Part 2: Backend Setup +Appwrite Account + Created Appwrite Cloud account + Created new project + Noted Project ID + Noted Endpoint URL +Appwrite Platform Configuration + Added Android platform (package: com.resonate.resonate) + Added iOS platform (bundle: com.resonate.resonate) + Generated API Key + Saved API Key securely +LiveKit Setup + Created LiveKit Cloud account + Created new project + Noted LiveKit URL + Noted API Key + Noted API Secret + Saved credentials securely +Backend Repository + Cloned Resonate-Backend repository + Logged into Appwrite CLI (appwrite login) + Initialized Appwrite project (appwrite init project) + Configured environment variables for functions + Ran setup script (./init.sh or .\init.ps1) + Deployed all cloud functions +Database Collections + Users collection created + Rooms collection created + Stories collection created + Chapters collection created + Participants collection created + Pairs collection created + Notifications collection created +Updated Flutter Configuration + Updated .env file with Appwrite credentials + Updated .env file with LiveKit credentials + Verified configuration in code files +Part 3: Running the App +First Run + Started emulator/simulator or connected device + Verified device in flutter devices + Ran flutter run successfully + App launched without errors + Can navigate through app screens +Feature Testing + Can create an account + Authentication works + Can create a room + Can join a room + Audio permissions granted + LiveKit connection works + Can send/receive audio +Troubleshooting (If Needed) +If you encounter issues: + + Checked Troubleshooting section in ONBOARDING.md + Ran flutter clean and flutter pub get + Restarted IDE/editor + Restarted emulator/device + Checked error logs + Asked for help in Discord +Final Steps + Read CONTRIBUTING.md + Read CODE_OF_CONDUCT.md + Joined Discord server + Found a "good first issue" to work on + Created a feature branch for your work +Quick Command Reference +bash +# Flutter Commands +flutter doctor # Check setup +flutter clean # Clean build +flutter pub get # Get dependencies +flutter run # Run app +flutter run -v # Run with verbose logging + +# Git Commands +git status # Check status +git pull upstream dev # Sync with upstream +git checkout -b feature/name # Create branch +git add . # Stage changes +git commit -m "message" # Commit +git push origin branch # Push to fork + +# Appwrite Commands +appwrite login # Login to Appwrite +appwrite deploy function # Deploy functions +Success Criteria +โœ… You're ready to contribute when: + +App runs without errors +You can create and join rooms +Audio features work +You understand the project structure +You've read the contribution guidelines +Need Help? +Discord: https://discord.gg/MMZBadkYFm +Email: aossie.oss@gmail.com +Issues: https://github.com/AOSSIE-Org/Resonate/issues +Congratulations on completing the setup! Happy coding! ๐ŸŽ‰ + diff --git a/lib/themes/bright_theme.dart b/lib/themes/bright_theme.dart new file mode 100644 index 00000000..8643e3f6 --- /dev/null +++ b/lib/themes/bright_theme.dart @@ -0,0 +1,43 @@ +import 'package:flutter/material.dart'; + +final ThemeData brightTheme = ThemeData( + brightness: Brightness.light, + primaryColor: Colors.white, + scaffoldBackgroundColor: Colors.white, + appBarTheme: const AppBarTheme( + backgroundColor: Colors.white, + foregroundColor: Colors.black, + elevation: 0, + iconTheme: IconThemeData(color: Colors.black), + ), + colorScheme: const ColorScheme.light( + primary: Color(0xFF4CAF50), // Vibrant green for action elements like Join Button + secondary: Color(0xFF2196F3), // Clean blue for share/connectivity icons + tertiary: Color(0xFFFF9800), // Soft orange for participant count (high contrast and clarity) + surface: Colors.white, + background: Colors.white, + onPrimary: Colors.white, + onSecondary: Colors.white, + onTertiary: Colors.white, + onBackground: Colors.black, + onSurface: Colors.black, + ), + elevatedButtonTheme: ElevatedButtonThemeData( + style: ElevatedButton.styleFrom( + backgroundColor: const Color(0xFF4CAF50), // Vibrant green Join Button + foregroundColor: Colors.white, + shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(30)), + ), + ), + iconTheme: const IconThemeData( + color: Color(0xFF2196F3), // Default blue for icons like Share + ), + textTheme: const TextTheme( + displayLarge: TextStyle(color: Colors.black, fontWeight: FontWeight.bold), + bodyLarge: TextStyle(color: Colors.black), + bodyMedium: TextStyle(color: Colors.black87), + labelLarge: TextStyle(color: Colors.white), // For button text + ), + // Ensures high contrast (WCAG AA compliant on white background) + // Can be extended for more elements if needed +); \ No newline at end of file diff --git a/lib/themes/theme_list.dart b/lib/themes/theme_list.dart index 34ba117a..ec4d6c4b 100644 --- a/lib/themes/theme_list.dart +++ b/lib/themes/theme_list.dart @@ -64,16 +64,27 @@ class ThemeList { onSurfaceColor: Colors.white, themeMode: ThemeMode.dark, ), + // New Bright Theme - exactly as per proposal + ThemeModel( + name: "Bright", + primaryColor: Color(0xFF4CAF50), // Vibrant green shade for Join Button and core actions + onPrimaryColor: Colors.white, + secondaryColor: Color(0xFF2196F3), // Clean blue tone for Share Icon and connectivity + onSecondaryColor: Colors.white, + surfaceColor: Colors.white, // White background for high-contrast bright look + onSurfaceColor: Colors.black, // Black text for maximum readability + themeMode: ThemeMode.light, // Light mode for vibrant accessibility + ), ]; static ThemeModel getThemeModel(String themeName) { for (var themeModel in themesList) { - if (themeModel.name.toLowerCase() == themeName) { + if (themeModel.name.toLowerCase() == themeName.toLowerCase()) { return themeModel; } } - // Return Classic Theme + // Return Classic Theme as fallback return themesList.first; } -} +} \ No newline at end of file diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 00000000..11bc1673 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "Updated-AOSSIE-Org-Resonate", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}