diff --git a/BUILD.md b/BUILD.md
new file mode 100644
index 0000000..03a3d25
--- /dev/null
+++ b/BUILD.md
@@ -0,0 +1,187 @@
+# Building LifeFlow APK
+
+This guide explains how to build the LifeFlow Android APK.
+
+## Prerequisites
+
+- Linux/macOS/Windows with bash
+- Git
+- 10GB free disk space
+
+## Step-by-Step Build Instructions
+
+### 1. Clone Repository
+
+```bash
+git clone https://git.lemonlink.eu/impulsivefps/LifeFlow.git
+cd LifeFlow
+```
+
+### 2. Install Flutter SDK
+
+#### Option A: Using the provided script (Linux/macOS)
+
+```bash
+bash scripts/install_flutter.sh
+source ~/.bashrc
+flutter doctor
+```
+
+#### Option B: Manual Installation
+
+1. Download Flutter from: https://docs.flutter.dev/get-started/install
+2. Extract to a location (e.g., `/opt/flutter` or `C:\flutter`)
+3. Add to PATH:
+   ```bash
+   # Linux/macOS - add to ~/.bashrc or ~/.zshrc
+   export PATH="$PATH:/opt/flutter/bin"
+   
+   # Windows - add to System Environment Variables
+   C:\flutter\bin
+   ```
+
+### 3. Verify Installation
+
+```bash
+flutter doctor
+```
+
+You should see checkmarks for:
+- [✓] Flutter (Channel stable)
+- [✓] Android toolchain
+- [✓] Android Studio (optional but recommended)
+
+### 4. Get Dependencies
+
+```bash
+cd android
+flutter pub get
+```
+
+### 5. Build APK
+
+#### Debug APK (for testing)
+
+```bash
+flutter build apk --debug
+```
+
+Output: `build/app/outputs/flutter-apk/app-debug.apk`
+
+#### Release APK (for distribution)
+
+```bash
+flutter build apk --release
+```
+
+Output: `build/app/outputs/flutter-apk/app-release.apk`
+
+### 6. Install on Device
+
+#### Option A: USB Installation
+
+1. Connect Android device with USB debugging enabled
+2. Run:
+   ```bash
+   flutter install
+   ```
+
+#### Option B: Manual Installation
+
+1. Copy APK to device
+2. Open file manager on device
+3. Tap APK to install (may need to allow "Unknown Sources")
+
+---
+
+## Troubleshooting
+
+### "flutter: command not found"
+
+**Solution:** Flutter not in PATH
+```bash
+export PATH="$PATH:/opt/flutter/bin"
+# Or wherever you installed Flutter
+```
+
+### "Android SDK not found"
+
+**Solution:** Install Android Studio or Android SDK Command Line Tools
+```bash
+# Download from: https://developer.android.com/studio
+# Or use sdkmanager
+```
+
+### "Gradle build failed"
+
+**Solution:** Clean and rebuild
+```bash
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+### "Out of memory"
+
+**Solution:** Increase heap size
+```bash
+export GRADLE_OPTS="-Xmx4g"
+flutter build apk --release
+```
+
+---
+
+## Build for Other Platforms
+
+### Windows
+
+```bash
+flutter build windows --release
+```
+
+Output: `build/windows/x64/runner/Release/`
+
+### Linux
+
+```bash
+flutter build linux --release
+```
+
+Output: `build/linux/x64/release/bundle/`
+
+### macOS
+
+```bash
+flutter build macos --release
+```
+
+Output: `build/macos/Build/Products/Release/`
+
+---
+
+## Automated Build (CI/CD)
+
+For GitHub Actions automated builds, see `.github/workflows/` (to be added).
+
+---
+
+## APK Size Optimization
+
+The default release APK includes debug symbols. To create a smaller APK:
+
+```bash
+flutter build apk --release --split-debug-info=symbols
+```
+
+Or build an App Bundle (recommended for Play Store):
+
+```bash
+flutter build appbundle --release
+```
+
+---
+
+## Need Help?
+
+- Check Flutter documentation: https://docs.flutter.dev
+- Open an issue: https://git.lemonlink.eu/impulsivefps/LifeFlow/issues
diff --git a/README.md b/README.md
index a37476a..a821a0b 100644
--- a/README.md
+++ b/README.md
@@ -1,252 +1,250 @@
-# LifeFlow - Personal Life Management System
+# 🌊 LifeFlow - Personal Life Management System
 
 > Transform your daily routines into enjoyable habits
-> 
-> **Android App** | **PC App** | **Home Assistant Integration** | **SMS Parsing**
+
+[![Flutter](https://img.shields.io/badge/Flutter-3.19+-blue.svg)](https://flutter.dev)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## 📱 Overview
+
+LifeFlow is a comprehensive life management app that helps you track:
+- 💊 Medications & Vitamins
+- 📅 Appointments & Meetings
+- 😴 Sleep Schedule
+- 🍎 Food & Nutrition
+- 💧 Hydration
+- 🏃 Exercise
+- 🧼 Hygiene
+- 🧘 Self Care
+
+### ✨ Features
+
+- **Easy Logging** - One-tap routine completion
+- **Smart Notifications** - Never miss a routine
+- **Gamification** - Points, streaks, badges, levels
+- **Home Assistant** - Full integration with sensors & buttons
+- **SMS Parsing** - Auto-detect appointments from texts
+- **Cross-Platform** - Android, PC app, Web
 
 ---
 
-## 🎯 Vision
+## 🚀 Quick Start
 
-LifeFlow makes managing your daily life **effortless, engaging, and rewarding**. From medications to hydration, appointments to self-care - everything organized in one beautiful, intuitive app.
+### Prerequisites
 
-### Core Principles
-- **Easy** - Minimal friction to log activities
-- **Fun** - Gamification and rewards
-- **Smart** - AI-powered suggestions and SMS parsing
-- **Connected** - Syncs across all devices + Home Assistant
+- Flutter SDK 3.19 or higher
+- Android Studio (for Android SDK)
+- Git
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone https://git.lemonlink.eu/impulsivefps/LifeFlow.git
+   cd LifeFlow
+   ```
+
+2. **Install Flutter** (if not already installed)
+   ```bash
+   # Option 1: Use the provided script
+   bash scripts/install_flutter.sh
+   source ~/.bashrc
+   
+   # Option 2: Manual installation
+   # Download from: https://docs.flutter.dev/get-started/install
+   ```
+
+3. **Navigate to Android app**
+   ```bash
+   cd android
+   ```
+
+4. **Get dependencies**
+   ```bash
+   flutter pub get
+   ```
+
+5. **Build APK**
+   ```bash
+   # Debug APK (for testing)
+   flutter build apk --debug
+   
+   # Release APK (for distribution)
+   flutter build apk --release
+   ```
+
+6. **Find your APK**
+   ```
+   build/app/outputs/flutter-apk/app-release.apk
+   ```
 
 ---
 
-## 📱 Features Overview
+## 📂 Project Structure
 
-### 1. Medication & Vitamins 💊
-- **Smart Reminders** - Time-based with snooze options
-- **Dose Tracking** - Log what you took and when
-- **Refill Alerts** - Warns when running low
-- **Interaction Checker** - Flags potential conflicts
-- **History View** - Complete medication timeline
-
-### 2. Appointments & Meetings 📅
-- **Calendar Sync** - Google/Outlook integration
-- **SMS Parsing** - Auto-extract from text messages
-- **Smart Scheduling** - Suggests optimal times
-- **Prep Reminders** - Reminds you to prepare
-- **Travel Time** - Includes commute in notifications
-
-### 3. Sleep Schedule 😴
-- **Sleep Tracking** - Duration and quality
-- **Wind-Down Alerts** - Prepare for bedtime
-- **Smart Alarm** - Wake at optimal cycle
-- **Sleep Hygiene** - Tips and reminders
-- **Trends Analysis** - Weekly/monthly patterns
-
-### 4. Food & Intake 🍎
-- **Meal Logging** - Quick photo + notes
-- **Macro Tracking** - Protein, carbs, fats
-- **Water Intake** - Hydration reminders
-- **Calorie Estimation** - Smart suggestions
-- **Meal Prep Reminders** - Plan ahead
-
-### 5. Self Care & Hygiene 🧘
-- **Routine Checklists** - Morning/evening rituals
-- **Skincare Tracking** - Product usage log
-- **Exercise Logging** - Workout tracking
-- **Mental Health** - Mood journaling
-- **Meditation Timer** - Mindfulness sessions
-
-### 6. Hydration 💧
-- **Smart Reminders** - Based on activity level
-- **Quick Log** - One-tap water logging
-- **Goal Tracking** - Daily target visualization
-- **Streak Counter** - Consecutive days hit
-- **Weather Aware** - More reminders on hot days
+```
+LifeFlow/
+├── android/                    # Flutter Android App
+│   ├── lib/
+│   │   ├── main.dart          # App entry point
+│   │   ├── models/            # Data models
+│   │   │   ├── routine.dart   # Routine, Schedule, Reminder
+│   │   │   ├── activity.dart  # Activity logging
+│   │   │   └── gamification.dart # Points, badges, levels
+│   │   ├── repositories/      # Data access layer
+│   │   ├── screens/           # UI screens
+│   │   │   ├── dashboard/     # Main dashboard
+│   │   │   ├── routines/      # Routine management
+│   │   │   ├── calendar/      # Calendar view
+│   │   │   ├── stats/         # Statistics & progress
+│   │   │   └── settings/      # App settings
+│   │   ├── services/          # Business logic
+│   │   │   ├── database_service.dart      # Hive database
+│   │   │   └── notification_service.dart  # Local notifications
+│   │   └── theme/             # App theming
+│   └── pubspec.yaml           # Dependencies
+│
+├── home-assistant/             # Home Assistant Integration
+│   └── custom_components/
+│       └── lifeflow/
+│           ├── __init__.py
+│           ├── sensor.py      # 6 sensors
+│           ├── button.py      # 4 buttons
+│           ├── config_flow.py
+│           └── manifest.json
+│
+├── scripts/                    # Build scripts
+│   └── install_flutter.sh     # Flutter SDK installer
+│
+└── docs/                       # Documentation
+    └── DEVELOPMENT_PLAN.md
+```
 
 ---
 
-## 🎮 Gamification System
+## 🛠️ Development
 
-### Points & Rewards
-- **Activity Points** - Earn for completing routines
-- **Streak Bonuses** - Multipliers for consistency
-- **Achievement Badges** - Unlock milestones
-- **Level System** - Progress from Novice to Master
-- **Weekly Challenges** - Special themed goals
+### Running in Debug Mode
 
-### Visual Progress
-- **Flame Streaks** - Visual fire for active streaks
-- **Progress Rings** - Daily completion circles
-- **Monthly Calendar** - Heat map of activity
-- **Trend Graphs** - Visualize improvements
+```bash
+cd android
+flutter run
+```
+
+### Running Tests
+
+```bash
+flutter test
+```
+
+### Building for Different Platforms
+
+```bash
+# Android APK
+flutter build apk --release
+
+# Android App Bundle (for Play Store)
+flutter build appbundle --release
+
+# Windows
+flutter build windows --release
+
+# Linux
+flutter build linux --release
+
+# macOS
+flutter build macos --release
+```
 
 ---
 
 ## 🏠 Home Assistant Integration
 
-### Features
-- **Dashboard Widget** - Quick status view
-- **Voice Commands** - "Hey Google, log my vitamins"
-- **Automations** - Trigger based on routines
-  - Lights dim at bedtime
-  - Coffee maker starts after morning routine
-  - Notifications to family members
-- **Sensors** - Track completion rates
-- **Scripts** - Run routines from HA
+### Installation
 
-### Entities Exposed
-- `sensor.lifeflow_medication_today`
-- `sensor.lifeflow_water_intake`
-- `sensor.lifeflow_sleep_quality`
-- `binary_sensor.lifeflow_all_routines_done`
-- `button.lifeflow_log_vitamins`
+1. Copy the `home-assistant/custom_components/lifeflow` folder to your Home Assistant `config/custom_components/` directory
+2. Restart Home Assistant
+3. Go to Settings > Devices & Services > Add Integration
+4. Search for "LifeFlow"
 
----
+### Available Entities
 
-## 💻 PC App Features
+**Sensors:**
+- `sensor.lifeflow_medications_today` - Medications taken today
+- `sensor.lifeflow_water_intake` - Water consumed (mL)
+- `sensor.lifeflow_sleep_quality` - Sleep quality (%)
+- `sensor.lifeflow_daily_progress` - Daily completion (%)
+- `sensor.lifeflow_current_streak` - Current streak (days)
+- `sensor.lifeflow_total_points` - Total points
 
-### Desktop Companion
-- **Quick Log Widget** - Desktop overlay
-- **Keyboard Shortcuts** - Ctrl+Shift+L for water
-- **System Tray** - Always accessible
-- **Calendar View** - Weekly planning
-- **Data Export** - CSV/JSON for analysis
+**Buttons:**
+- `button.lifeflow_log_vitamins` - Log vitamins
+- `button.lifeflow_log_water` - Log water
+- `button.lifeflow_log_medication` - Log medication
+- `button.lifeflow_complete_routine` - Complete routine
 
-### Cross-Platform Sync
-- **Real-time Sync** - Instant across devices
-- **Offline Mode** - Works without internet
-- **Conflict Resolution** - Smart merge
-- **Backup & Restore** - Never lose data
+### Example Automation
 
----
-
-## 📱 Android App Architecture
-
-### Tech Stack
-- **Framework:** Flutter (cross-platform)
-- **State Management:** Riverpod
-- **Local DB:** Hive (fast, lightweight)
-- **Backend:** Firebase / Supabase
-- **Notifications:** Flutter Local Notifications
-- **SMS:** Telephony plugin
-
-### Screens
-1. **Dashboard** - Today's overview
-2. **Routines** - All routine categories
-3. **Calendar** - Schedule view
-4. **Stats** - Progress & analytics
-5. **Settings** - Configuration
-6. **Add Routine** - Create new routines
-
----
-
-## 🤖 SMS Parsing AI
-
-### Extracts From Texts
-**Appointment SMS:**
-```
-"Your appointment with Dr. Smith is 
-confirmed for March 15 at 2:30 PM at 
-Downtown Medical Center"
-```
-→ Auto-adds to calendar with location
-
-**Medication Reminders:**
-```
-"Your prescription is ready for pickup 
-at CVS Pharmacy. Refill #3 of 5."
-```
-→ Logs refill, updates inventory
-
-**Meeting Invites:**
-```
-"Team standup tomorrow 9 AM in Conference 
-Room B. Bring your reports."
-```
-→ Adds meeting with notes
-
----
-
-## 📊 Data Model
-
-### Core Entities
-```
-User
-├── Routines[]
-├── Activities[]
-├── Medications[]
-├── Appointments[]
-├── SleepLogs[]
-├── FoodLogs[]
-└── Settings
-
-Routine
-├── name: string
-├── category: enum
-├── schedule: CronExpression
-├── reminders: Reminder[]
-├── points: number
-└── streak: number
-
-Activity
-├── routineId: string
-├── timestamp: datetime
-├── completed: boolean
-├── notes: string
-└── mood: enum
+```yaml
+automation:
+  - alias: "Morning Routine Complete"
+    trigger:
+      - platform: numeric_state
+        entity_id: sensor.lifeflow_daily_progress
+        above: 50
+    condition:
+      - condition: time
+        after: "06:00:00"
+        before: "09:00:00"
+    action:
+      - service: light.turn_on
+        target:
+          entity_id: light.bedroom
+        data:
+          brightness_pct: 100
 ```
 
 ---
 
-## 🔐 Privacy & Security
+## 📋 Feature Checklist
 
-- **Local-First** - Data stored on device
-- **Encrypted Sync** - End-to-end encryption
-- **No Data Selling** - Your data is yours
-- **Export Anytime** - Full data portability
-- **Optional Cloud** - Sync only if you want
+- [x] Flutter app structure
+- [x] Data models (Routine, Activity, Gamification)
+- [x] Repository layer with Riverpod
+- [x] Dashboard UI with progress ring
+- [x] Routine cards with categories
+- [x] Light/Dark theme support
+- [x] Local notifications service
+- [x] Hive database setup
+- [x] Home Assistant integration
+- [ ] SMS parsing implementation
+- [ ] PC app (Flutter Desktop)
+- [ ] Cloud sync
+- [ ] AI suggestions
 
 ---
 
-## 🚀 Development Phases
+## 🤝 Contributing
 
-### Phase 1: Core Android App
-- Basic routine tracking
-- Notifications
-- Local storage
-- Simple gamification
-
-### Phase 2: Smart Features
-- SMS parsing
-- AI suggestions
-- Advanced analytics
-- Widgets
-
-### Phase 3: Ecosystem
-- PC app
-- Home Assistant
-- Cloud sync
-- Social features
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
 
 ---
 
-## 📈 Success Metrics
+## 📄 License
 
-- Daily active users
-- Routine completion rates
-- User retention (7/30/90 day)
-- Average streak length
-- Feature adoption
+This project is licensed under the MIT License.
 
 ---
 
-## 🎨 Design Philosophy
+## 🙏 Acknowledgments
 
-- **Calming Colors** - Blues, greens, soft tones
-- **Minimalist** - Clean, uncluttered UI
-- **Accessible** - WCAG compliant
-- **Delightful** - Micro-interactions, animations
-- **Personal** - Customizable themes
+- Flutter Team for the amazing framework
+- Home Assistant Community for the integration platform
 
 ---
 
-Ready to build! 🚀
+**Ready to transform your daily routines? Let's flow! 🌊**