Media-Aggregation-and-Sorting-System/README.md

# Media Aggregation and Sorting System

A React Native/Expo application that aggregates photos and videos from multiple sources (Google Photos, iCloud, and Network-Attached Storage) into a unified photo library.

## Features

### Core Functionality
- **User Authentication**: Local account creation and login with SQLite database storage
- **Multi-Service Integration**:
  - 🔵 **Google Photos**: OAuth2 integration for Google Photos API
  - 🍎 **iCloud Photos**: Apple iCloud account support (placeholder)
  - 💾 **NAS Storage**: SFTP connection to Ubuntu servers for photo/video access
  
- **Onboarding Flow**: 
  - Service selection (enable 1-3 services)
  - Service configuration with credentials
  - Default service selection for uploads

- **Photo Gallery**: 
  - Unified photo library view combining all services
  - Google Photos-styled grid layout
  - Modal image viewer with metadata display
  - Support for photos and videos

### Architecture

#### Database Schema
- **users**: User account storage (username, email, password)
- **linked_accounts**: External service credentials and configurations
- **media**: Photo/video metadata from all sources
- **sync_logs**: Sync operation history and status

#### Authentication Services
All authentication services follow the `AuthServiceBase` interface for easy interchangeability:

1. **GoogleAUTH**: OAuth2 authentication with Google Photos API
2. **IOSAUTH**: Apple iCloud authentication (currently placeholder)
3. **NASAUTH**: SFTP connection to Ubuntu servers via SSH2

#### Navigation Flow
```
Login/Register → Onboarding (Service Setup) → Home (Photo Gallery)
```

## Project Structure

```
Media-Aggregation-and-Sorting-System/
├── src/
│   ├── AUTH/
│   │   ├── AuthServiceBase.js        # Abstract auth service interface
│   │   ├── GoogleAUTH.js             # Google Photos authentication
│   │   ├── IOSAUTH.js                # iCloud authentication
│   │   └── NASAUTH.js                # NAS SFTP authentication
│   ├── screens/
│   │   ├── LoginScreen.js            # Login form
│   │   ├── RegisterScreen.js         # Registration form
│   │   ├── OnboardingScreen.js       # Service setup wizard
│   │   └── HomeScreen.js             # Main photo gallery
│   ├── services/
│   │   └── DatabaseService.js        # SQLite database operations
│   ├── components/
│   └── API/
├── App.js                            # Navigation setup
├── app.json                          # Expo configuration
├── package.json                      # Dependencies
└── README.md
```

## Installation

### Prerequisites
- Node.js and npm
- Expo CLI: `npm install -g expo-cli`
- iOS Simulator or Android Emulator (or physical device with Expo Go)

### Setup Steps

1. **Clone and Install Dependencies**
   ```bash
   cd Media-Aggregation-and-Sorting-System
   npm install
   ```

2. **Start the Development Server**
   ```bash
   npm start
   ```

3. **Run on Device/Emulator**
   - iOS: Press `i` in the terminal
   - Android: Press `a` in the terminal
   - Physical Device: Scan QR code with Expo Go app

## Usage

### Creating an Account
1. Open the app → Select "Register here"
2. Enter username, email, and password (min 6 characters)
3. Confirm password and create account

### Login
1. Enter registered email and password
2. Click "Login"

### Onboarding (Service Configuration)
**Step 1: Select Services**
- Toggle which services to enable (1-3 maximum)
- Google Photos, iCloud, and/or NAS

**Step 2: Configure Services**
- **Google Photos**: Tap to authenticate with Google (OAuth flow)
- **iCloud**: Tap to authenticate with Apple (OAuth flow)
- **NAS**: Enter connection details:
  - Server address (IP or hostname)
  - SSH port (default: 22)
  - Username
  - Password
  - Photos folder path
  - Test connection before proceeding

**Step 3: Choose Default Service**
- Select which service to use by default for uploads

### Photo Gallery
- View all photos/videos from connected services
- Service badges at top show connected accounts
- ★ indicates the default service
- Tap any photo to view in enlarged modal
- Modal shows metadata: title, description, source, type, date

## API Integration (TODO)

### Google Photos Implementation
- Replace placeholder `authenticate()` with actual Google Sign-In
- Implement OAuth2 token exchange
- Add `/photoslibrary/v1/mediaItems:search` API calls
- Handle pagination and filtering

### iCloud Implementation
- Integrate Apple Sign-In
- Implement CloudKit API for photo access
- Handle iCloud authentication

### NAS Implementation
- Replace SSH2 placeholders with actual library implementation
- Implement SFTP file listing and download
- Add file upload functionality
- Handle directory navigation

## Configuration

### Environment Variables (Optional)
Create a `.env` file for sensitive configuration:
```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
NAS_DEFAULT_PORT=22
```

### Database
- SQLite database is automatically created on first run
- Location: Device's app-specific directory
- Filename: `PhotosApp.db`

## Authentication Service Pattern

Each service implements the same interface:

```javascript
class AuthService extends AuthServiceBase {
  async authenticate(credentials) { }
  async getAccessToken() { }
  async refreshToken() { }
  async revokeAccess() { }
  async getUserInfo() { }
  // Service-specific methods
}
```

### Easy Interchangeability
To swap or extend authentication:

1. Create new class extending `AuthServiceBase`
2. Implement all abstract methods
3. Update the service type in `DatabaseService.linkAccount()`
4. Update `OnboardingScreen` UI if needed

## Data Flow

```
Login/Register
    ↓
Authentication → Save to SQLite
    ↓
Onboarding → Service Selection
    ↓
Service Auth → Store Credentials
    ↓
Home Screen → Fetch from Services
    ↓
Display in Gallery
```

## Security Considerations

⚠️ **Current Implementation Warnings**:
- Passwords stored in plain text in SQLite (development only)
- NAS passwords stored in plain text (development only)
- OAuth tokens not persisted securely

**For Production**:
- Use secure storage (Keychain/Keystore)
- Encrypt sensitive data in database
- Implement token refresh and expiration
- Use OAuth for all services
- Never store plain-text passwords

## Dependencies

### Core
- `react`: 19.1.0
- `react-native`: 0.81.5
- `expo`: ~54.0.31

### Navigation
- `@react-navigation/native`: ^6.1.17
- `@react-navigation/native-stack`: ^6.9.26
- `react-native-screens`: ^3.31.1
- `react-native-safe-area-context`: ^4.10.5
- `react-native-gesture-handler`: ^2.16.1

### Database & Storage
- `react-native-sqlite-storage`: ^6.0.0
- `expo-file-system`: ~17.0.1
- `expo-media-library`: ~15.9.0

### Network
- `ssh2`: ^1.15.0
- `react-native-ssh2`: ^1.0.0

### Media
- `expo-image-picker`: ~14.7.1

## Troubleshooting

### Database Initialization Error
```
Solution: Clear app cache/reinstall
npx expo prebuild --clean
npm start
```

### Navigation Issues
Ensure all screens are properly exported and imported in App.js

### Service Connection Failures
- Check network connectivity
- Verify API credentials
- Check NAS server accessibility (port 22 open)
- Review console logs for detailed error messages

## Future Enhancements

- [ ] Implement actual Google Photos API integration
- [ ] Implement actual iCloud Photos integration
- [ ] Complete SFTP functionality for NAS
- [ ] Photo upload to default service
- [ ] Photo search and filtering
- [ ] Album management
- [ ] Automatic sync scheduling
- [ ] Cloud backup
- [ ] Photo sharing features
- [ ] Advanced metadata editing
- [ ] Duplicate detection
- [ ] Smart album creation
- [ ] Facial recognition (optional)