🐠 ReefKeeper

A cross-platform mobile app for reef aquarium hobbyists to track creatures, manage recurring maintenance tasks, and stay on top of their tank care — built with React Native, Expo, and TypeScript.

---

Features

• Dashboard — at-a-glance view of your tank: creature counts, overdue/upcoming tasks, and quick actions
• Creature Registry — catalog your fish, corals, invertebrates and more with photos, species info, and health logs
• Maintenance Tasks — recurring and one-off task management with automatic rescheduling (water changes, parameter tests, feeding, etc.)
• Notifications — configurable reminders before tasks are due
• Search & Filter — find creatures by name, species, or type
• Dark Mode — automatic theme based on system preference
• Auth0 Authentication — secure login/registration
• Offline-first — all data stored locally via AsyncStorage

Tech Stack

Layer	Technology
Framework	Expo (SDK 54) + Expo Router
Language	TypeScript
UI	React Native Paper (Material Design 3)
Auth	Auth0 via react-native-auth0
Storage	@react-native-async-storage/async-storage
Unit Tests	Jest + React Testing Library
E2E Tests	Playwright
CI/CD	GitHub Actions

---

Getting Started

Prerequisites

• Node.js 20+
• npm 10+
• An Auth0 account (for authentication)

Installation

# Clone the repository
git clone https://github.com/<your-org>/ReefKeeper.git
cd ReefKeeper

# Install dependencies
npm install

Environment Variables

IMPORTANT: Create a .env file before running the app, especially for Android development. Without this file, authentication will fail with "Unknown Host unconfigured.auth0.com".

Copy the example env file and fill in your Auth0 credentials:

cp .env.example .env
# Edit .env with your actual Auth0 credentials

Variable	Description
AUTH0_DOMAIN	Your Auth0 tenant domain (e.g., yourapp.eu.auth0.com)
AUTH0_CLIENT_ID	Auth0 application client ID (for web/iOS)
AUTH0_CLIENT_ID_APK	Auth0 application client ID for Android (optional, defaults to AUTH0_CLIENT_ID)
AUTH0_CLIENT_SECRET	Auth0 application client secret
AUTH0_CALLBACK_URL	OAuth callback URL (http://localhost:8081 for local dev)
TEST_USER_EMAIL	Email for the E2E test user
TEST_USER_PASSWORD	Password for the E2E test user

Auth0 Configuration

For Android authentication to work properly, you need to configure the following URLs in your Auth0 application settings:

Allowed Callback URLs:

reef-keeper://{yourDomain}/android/com.reefkeeper.app/callback
http://localhost:8081

Allowed Logout URLs:

reef-keeper://{yourDomain}/android/com.reefkeeper.app/callback
http://localhost:8081

Replace {yourDomain} with your actual Auth0 domain (e.g., reefkeeper.eu.auth0.com).

Note: The Android package name is com.reefkeeper.app and the custom scheme is reef-keeper.

Running the App

# Start in web mode
npx expo start --web

# Start for iOS (requires macOS + Xcode)
npx expo start --ios

# Start for Android (requires Android Studio)
npx expo start --android

The app will be available at http://localhost:8081.

Note: To build a standalone Android APK for testing without Metro, see the Android Development Build Guide.

---

Testing

Unit Tests

npm test

Runs Jest tests located in __tests__/. The configuration is in jest.config.js.

End-to-End Tests

Playwright tests live in e2e/ and run against the web build.

# Install Playwright browsers (first time only)
npx playwright install chromium

# Run E2E tests (auto-starts the dev server)
npx playwright test

# Run with visible browser
npx playwright test --headed

# View the last test report
npx playwright show-report

---

Project Structure

ReefKeeper/
├── app/                    # Expo Router screens
│   ├── (tabs)/             # Tab navigator (Dashboard, Creatures, Tasks)
│   ├── creature/           # Creature detail & add screens
│   ├── task/               # Task detail & add screens
│   ├── settings.tsx        # Settings screen
│   └── _layout.tsx         # Root layout (Auth0 provider, theme)
├── components/             # Reusable UI components
├── constants/              # Theme colors, creature types, default tasks
├── hooks/                  # Custom React hooks (useCreatures, useTasks, etc.)
├── models/                 # TypeScript interfaces (Creature, Task)
├── services/               # Data layer (AsyncStorage CRUD, notifications)
├── e2e/                    # Playwright E2E tests (web)
├── maestro/                # Maestro UI tests (Android)
├── __tests__/              # Jest unit tests
├── .github/workflows/      # CI/CD pipelines (ci, web, android)
└── docs/screenshots/       # App screenshots

---

Contributing

1. Fork the repository
2. Create a branch for your feature or fix:

   git checkout -b feature/my-feature

3. Make your changes — follow the existing code style (TypeScript strict mode, functional components, hooks)
4. Run checks before committing:

   npx tsc --noEmit        # Type-check
   npm test                 # Unit tests
   npx playwright test      # E2E tests

5. Commit with a clear message and open a Pull Request

The Shared CI pipeline automatically runs type-checking, unit tests, and dependency audits on every PR.

Code Conventions

• Functional components with hooks — no class components
• TypeScript strict mode — no any unless absolutely necessary
• React Native Paper for all UI elements — follow Material Design 3 patterns
• AsyncStorage for persistence — all keys prefixed with @reef_keeper
• Expo Router file-based routing — screens go in app/

---

CI/CD

Three-layer pipeline architecture for fast feedback and independent platform releases:

1. Shared CI (.github/workflows/ci.yml)

Runs on every push & PR to main. Fast quality gate (<8 min).

Step	Description
TypeScript type-check	tsc --noEmit
Lint	Expo lint (if configured)
Unit tests	Jest with coverage
Dependency audit	npm audit for known vulnerabilities

2. Web Pipeline (.github/workflows/web.yml)

Runs on merge to main and version tags (v*). Calls Shared CI first.

Job	Steps
web-build	Version injection → Expo web export → Upload bundle artifact
web-e2e	Install Playwright → Run E2E tests → Upload report
web-deploy	Deploy placeholder — wire to your hosting (Vercel, Netlify, Azure, etc.)

3. Android Pipeline (.github/workflows/android.yml)

Runs on merge to main and version tags (v*). Calls Shared CI first.

Job	Steps
android-build	Expo prebuild → Gradle build debug APK + release AAB (on tags) → Upload artifacts
android-test	Download APK → Start emulator → Run Maestro E2E tests → Upload report
android-release-internal	Upload to Google Play internal track (placeholder)
android-release-production	Promote to production — requires manual approval via GitHub environment

4. CI Failure Issue Creation (.github/workflows/create-issue-on-failure.yml)

Automatically creates GitHub issues when CI pipelines fail. Triggered on workflow completion.

Feature	Description
Auto-detection	Monitors Shared CI, Web, and Android workflows for failures
Detailed reporting	Extracts failed job details, error logs, and traces
Copilot assignment	Assigns issues to @copilot for automatic fixing
Duplicate prevention	Checks for existing open issues before creating new ones
Update tracking	Adds comments to existing issues for repeated failures

See docs/ci-failure-workflow.md for detailed documentation.

---

License

This project is private. All rights reserved.