Roomy is a mobile application designed to simplify and streamline the complexities of co-living. This repository contains the source code for the Roomy Flutter application.

Join the Beta Program: https://onelink.to/roomy Visit our website: theroomyapp.com

📦 Related Roomy Projects

This repository focuses on the Roomy Flutter application. The broader Roomy ecosystem includes several other interconnected projects, all housed within this monorepo:

Roomy Firebase Backend: Manages all backend services, including Firebase Authentication, Firestore database, Cloud Functions, and storage rules. See the roomy-firebase/README.md for more details.
Roomy Astro Website: The public-facing website for Roomy, built with Astro and React. It handles product information, the landing page, and beta signups. See the roomy-astro-website/README.md for more details.
Roomy Email Templates: A dedicated project for creating and managing responsive email templates using React Email. These templates are used by both the Firebase backend and the Astro website. See the roomy-react-email-starter/README.md for more details.
Roomy Workspace: Contains workspace configurations and shared settings relevant to the Roomy monorepo structure. See the roomy-workspace/README.md for more details.

📖 Table of Contents

📦 Related Roomy Projects
📜 Introduction
✨ Features
🏛️ Architecture Overview
🔑 Key Technologies & Dependencies
📁 Directory Structure
🚀 Getting Started
- Prerequisites
- Installation
🛠️ Usage
- Running the App
- Using Firebase Emulators
⚙️ Configuration
- Environments
📜 Scripts
🤝 Contributing
📄 License
📞 Contact & Support

📜 Introduction

Coordinating chores, managing shared grocery lists, splitting bills, and keeping track of who's done what can quickly become sources of friction in any shared home. Roomy tackles these common pain points head-on, offering intuitive solutions to keep your household running smoothly.

This Flutter application aims to provide a seamless and user-friendly experience for managing shared living spaces.

✨ Features

The Roomy app includes the following core features:

🏡 Household Management: Create household spaces, invite roomies/family members via username, and manage member profiles.
🛒 Collaborative Shopping Lists:
- Create and manage multiple shared shopping lists.
- Add items with quantities (supports smart input like "Milk x2").
- Attach images to items for clarity.
- Real-time checking off of purchased items.
- Push notifications for shopping list activity.
🧹 Organized Cleaning Tasks:
- Define recurring cleaning tasks with custom frequencies (daily, weekly, monthly).
- Add specific instructions for tasks.
- Track completed tasks.
- Delete tasks when no longer needed.
💰 Payment & Expense Tracking:
- Create and track shared expenses and payments between household members.
- Attach receipt images from camera or gallery for documentation and verification.
- View payment analytics with interactive charts (filter by week, month, or year).
- Split payments equally or set custom amounts per person.
- Lock specific split amounts while adjusting others with proportional distribution.
- View payment history with member avatars showing who paid and who receives.
- Add subject descriptions to payments for better organization.
- Clear paid/receives distinction in payment summaries.
- Visual indicators for read-only payment mode.
👤 User Profiles & Security:
- Secure account creation and login (email/password).
- Manage profile information (username, bio, contact details).
- Upload profile pictures via camera or gallery.
📨 Invitation System: Send and receive invitations to join households via an in-app inbox.
🎨 Personalization:
- Dark mode interface.
- Language selection (English/Dutch currently supported).
- Automatic system language detection on first app launch.
💬 Feedback System: Shake your device from any screen to quickly submit feedback, suggestions, or bug reports.
🆕 What's New/Changelog: View recent updates and changes to the app.

🏛️ Architecture Overview

Roomy's Flutter application is built using the Model-View-ViewModel (MVVM) architectural pattern, promoting a clear separation of concerns.

Model: Represents data and business logic (DTOs, local models, services).
View: Flutter widgets responsible for the UI, built with shadcn_ui and custom T widgets.
ViewModel: Manages UI state and logic, interacting with services. Based on the veto package.

Key architectural principles include:

Feature-First Structure: Code is organized by features (e.g., auth, shopping_lists, cleaning).
Dependency Injection: Uses get_it for managing services and ViewModels.
Standardized API Abstraction: RmyApi (based on turbo_firestore_api) for Firestore interactions.
Custom Theming System: TProvider and context extensions for consistent UI.
Reactive State Management: informers package for observable state within ViewModels.
Standardized Error Handling: turbo_response for consistent success/failure states.
Structured Analytics: TAnalytics base class with global TSubjects and consistent verb-based method naming.
UI Card Pattern: TCard component for consistent content grouping and layout across the application.
UI Animation Standards: SlideShrink for conditional rendering, TButton for interactive elements with built-in animations.
Code Quality Practices: Switch statements for enums, expression methods, null-aware operators, extension methods for repeated logic.

For a more detailed explanation, refer to the Architecture Document.

🔑 Key Technologies & Dependencies

Flutter & Dart: Core framework and language.
Firebase:
- Authentication
- Firestore (Database)
- Cloud Functions
- Storage
State Management: veto, informers.
Routing: go_router.
UI Components: shadcn_ui, custom T widgets.
Dependency Injection: get_it.
API Abstraction: turbo_firestore_api (custom), RmyApi.
Local Storage: hive_ce, flutter_secure_storage.
Analytics: posthog_flutter.
Crash Reporting: firebase_crashlytics.
Logging: loglytics.
Animations: flutter_animate.
JSON Serialization: json_serializable.
Charts: fl_chart for payment analytics visualization.
Gestures: shake_gesture for feedback trigger.

📁 Directory Structure

The project follows a feature-first directory structure under lib/:

lib/
├── analytics/         # Analytics and crash reporting
├── auth/              # Authentication, user profiles
├── cleaning/          # Cleaning tasks and schedules
├── core/              # Core app setup, locator service
├── data/              # Shared data models, constants, extensions
├── environment/       # Environment configurations
├── feedback/          # User feedback UI (dialogs, toasts)
├── firebase/          # Firebase specific code (APIs, DTOs)
├── forms/             # Form configurations and base classes
├── generated/         # Auto-generated code (localization)
├── households/        # Household management features
├── http/              # HTTP and connectivity services
├── inbox/             # In-app messaging and notifications
├── l10n/              # Localization files and services
├── nlp/               # Natural Language Processing utilities
├── payments/          # Payment tracking and expense management
├── routing/           # Navigation and routing setup
├── shopping_lists/    # Shopping list features
├── state/             # Core state management utilities, base classes
├── storage/           # Local and cloud storage services
├── typography/         # Text styling and custom text widgets
├── ui/                # Base UI components, theming system
├── whats_new/         # Changelog display feature
└── main.dart          # Application entry point

For more details on specific architectural rules and guidelines, refer to the CLAUDE.md file.

🚀 Getting Started

Prerequisites

Flutter SDK (version 3.19.0 or higher recommended)
Dart SDK (version 3.8.0 or higher recommended)
An editor like VS Code or Android Studio
Firebase project setup (see Firebase console)
Firebase CLI installed and configured
For iOS: Xcode and CocoaPods
For Android: Android Studio and Android SDK
Make (for using Makefile commands)

Installation

Clone the repository:

git clone https://github.com/theroomyapp/roomy.git
cd roomy/roomy-mobile

Install Flutter dependencies:
```
flutter pub get
```
Configure Firebase:
- Place your google-services.json (for Android) and GoogleService-Info.plist (for iOS) files in the appropriate directories (android/app/ and ios/Runner/).
- Ensure your Firebase project has Authentication, Firestore, Cloud Functions, and Storage enabled.
Generate code: The project uses build_runner for code generation (e.g., for DTOs, localization).
```
flutter pub run build_runner build --delete-conflicting-outputs
```
Or use the provided script:
```
./scripts/run_build_generator.sh
```

🛠️ Usage

Running the App

Standard Run (Production Firebase):
```
flutter run
```

Running Tests

Run all tests (Flutter + Firebase Cloud Functions):
```
make test
```
Run only Flutter tests:
```
make test flutter
```
Run only Firebase Cloud Function tests:
```
make test firebase
```
Or use Flutter directly:
```
flutter test
```
Run with a specific environment (e.g., emulators):
```
flutter run --dart-define=env=emulators
```
If running on a physical device or iOS simulator with emulators, you might need to specify your machine's IP:
```
flutter run --dart-define=env=emulators --dart-define=ip=YOUR_MACHINE_IP
```
Run with staging environment:
```
flutter run --dart-define=env=staging
```

Using Firebase Emulators

Ensure Firebase emulators are installed and configured.

Start the emulators (you can use the provided script):

./scripts/run_emulators.sh

Or manually:

firebase emulators:start --import=./firebase-data --export-on-exit

Run the app with the emulators environment flag as shown above. The app is configured to connect to emulators when this flag is present (see lib/environment/config/emulator_config.dart).

⚙️ Configuration

Environments

The application supports different environments, primarily for connecting to Firebase services:

prod (Default): Connects to live Firebase services (the-roomy-app).
staging: Connects to staging Firebase services (the-roomy-staging-app) for internal testing.
emulators: Connects to local Firebase emulators.

Environment selection is done via the --dart-define=env=<environment_name> flag when running the app. The configuration is managed in lib/environment/enums/environment.dart.

📜 Scripts

The scripts/ directory contains utility scripts for common development tasks:

run_build_generator.sh: Runs the build_runner for code generation.
dart_fix.sh: Applies Dart static analysis fixes.
run_emulators.sh: Starts the Firebase emulators.
add_brick.sh (in lib/): Adds the turbo-flutter brick.
copy_to_brick.dart (in lib/): Updates the __brick__ directory for the Mason brick.

Make sure scripts are executable (chmod +x script_name.sh).

Makefile Commands

The project includes a Makefile for convenient command execution:

make test: Run all tests (Flutter + Firebase Cloud Functions)
make test flutter: Run only Flutter tests
make test firebase: Run only Firebase Cloud Function tests
make sync claude: Sync Claude Code agents and commands
make build: Run build generator and format code
make fix: Run dart fix and format code

🚀 CI/CD & Deployment

The project uses Codemagic for automated builds and deployments:

Production Workflow: Builds and deploys to App Store and Google Play
Staging Workflow: Builds for acceptance testing with dedicated Slack notifications
Platform-Specific Builds: Separate iOS and Android build configurations
Google Play Compliance: Supports 16 KB memory page sizes for Google Play requirements

Build Configuration

Android: Uses AAB format for Google Play distribution
iOS: Configured with proper provisioning profiles for Push Notifications
Code Signing: Managed through Codemagic environment variables

📱 Icon Management

The project uses separate icons for different purposes:

assets/icon/app-icon.png (512x512) - Used for app launcher icon
assets/icon/splash-icon.png (477x460) - Used for splash screen logo

Important: Never use the same file for both purposes as it causes the square icon issue on Android splash screens.

To regenerate icons:

App icons: flutter pub run icons_launcher:create
Splash screens: flutter pub run flutter_native_splash:create

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a new branch (git checkout -b feature/your-feature-name).
Make your changes.
Ensure your code adheres to the project's linting rules and architectural guidelines (see CLAUDE.md for detailed conventions).
Write tests for your changes (unit tests without mocks preferred).
Run flutter analyze and flutter test to ensure everything passes.
Commit your changes (git commit -m 'Add some feature').
Push to the branch (git push origin feature/your-feature-name).
Open a Pull Request.

Please ensure your PR description clearly describes the changes and their purpose.

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details (assuming one exists, otherwise specify).

📞 Contact & Support

Project Website: theroomyapp.com
Support/Issues: Please open an issue on the GitHub repository.
Beta Program: https://onelink.to/roomy

Happy Co-living with Roomy! 🎉

Reacties

Nog geen reacties

Athena — roomy-mobile/README.md

🏠 Roomy: Harmonizing Shared Living Spaces (Flutter App)