From 20e82870fae7ac12f4f0a2fdc70704d1f7f617a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zo=C3=AB?= <zoe@guido-it.nl>
Date: Sat, 8 Aug 2026 12:56:28 +0200
Subject: [PATCH] docs: add project README with setup and architecture overview

---
 README.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9a51164
--- /dev/null
+++ b/README.md
@@ -0,0 +1,162 @@
+# SwimBuddy
+
+Swimming workout tracker with Apple Watch and WearOS companion apps.
+
+## Features
+
+- Create and manage swimming workout templates
+- Track workouts with detailed set/rep/lap data
+- Apple Watch companion for real-time workout tracking
+- WearOS companion for Android smartwatches
+- HealthKit integration (iOS) and Health Services (WearOS)
+- Multi-language support (EN, NL, DE, FR, IT, ES, PL, PT, DK)
+- SWOLF score calculation
+- Workout history and statistics
+
+## Tech Stack
+
+- **Framework**: Expo 57 + React Native 0.86
+- **Styling**: NativeWind v5 (TailwindCSS for React Native)
+- **Database**: expo-sqlite + Drizzle ORM
+- **Navigation**: React Navigation 7
+- **State**: react-native-mmkv (settings), SQLite (workouts)
+- **Watch**: Swift/SwiftUI (Apple Watch), Kotlin/Compose (WearOS)
+
+## Prerequisites
+
+- Node.js 18+
+- Expo CLI (`npm install -g expo-cli`)
+- Xcode 15+ (for iOS/Watch development)
+- Android Studio (for WearOS development)
+- CocoaPods (for iOS)
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Generate database migrations
+npm run db:generate
+
+# Start development server
+npm start
+```
+
+## Development
+
+```bash
+# Start Expo dev server
+npm start
+
+# Run on iOS
+npm run ios
+
+# Run on Android
+npm run android
+```
+
+## Building
+
+### iOS & Apple Watch
+
+```bash
+# Build for iOS
+npx expo run:ios
+
+# Open in Xcode for Watch target
+open ios/SwimBuddy.xcworkspace
+```
+
+### WearOS
+
+```bash
+# Build debug APK
+./scripts/build-wearos.sh debug
+
+# Build release APK
+./scripts/build-wearos.sh release
+
+# Generate launcher icons
+./scripts/generate-wearos-icon.sh assets/icon.png
+```
+
+## Project Structure
+
+```
+src/
+├── components/          # Shared UI primitives
+├── config/              # App configuration
+├── constants/           # Stroke types, pool lengths, colors
+├── db/                  # Drizzle schema, migrations, operations
+├── features/
+│   ├── active-workout/  # Live workout tracking
+│   ├── history/         # Workout history
+│   ├── settings/        # App settings
+│   ├── templates/       # Workout template management
+│   └── workout-builder/ # Create/edit workout templates
+├── hooks/               # Shared React hooks
+├── i18n/                # Translations (en, nl, de, fr, it, es, pl, pt, dk)
+├── modules/
+│   ├── watch-connectivity/  # Apple Watch WCSession bridge
+│   └── wear-connectivity/   # WearOS Data Layer bridge
+├── navigation/          # React Navigation setup
+├── providers/           # DatabaseProvider, SettingsProvider
+├── types/               # TypeScript types
+└── utils/               # Utility functions
+
+targets/
+├── watch/               # Apple Watch app (Swift/SwiftUI)
+└── wearos/              # WearOS app (Kotlin/Compose)
+```
+
+## Database
+
+The app uses SQLite via Drizzle ORM with the following tables:
+
+- `templates` - Workout templates with JSON data
+- `workouts` - Completed workout sessions
+- `sets` - Individual sets within workouts
+- `laps` - Lap data for each set
+
+### Schema Changes
+
+After modifying `src/db/schema.ts`, regenerate migrations:
+
+```bash
+npm run db:generate
+```
+
+## Watch Integration
+
+### Apple Watch
+
+- Uses WCSession for phone↔watch communication
+- HealthKit for swim workout tracking
+- App Groups for data sharing between iPhone and Watch
+- Real-time sync during workouts
+
+### WearOS
+
+- Uses Wear Data Layer API for communication
+- Health Services for swim tracking
+- Jetpack Compose with Wear OS Compose libraries
+
+## Internationalization
+
+Supported languages:
+- English (en)
+- Dutch (nl)
+- German (de)
+- French (fr)
+- Italian (it)
+- Spanish (es)
+- Polish (pl)
+- Portuguese (pt)
+- Danish (dk)
+
+Translation files are in `src/i18n/{locale}/`.
+
+## License
+
+MIT