# Photo Inbox Phase 2 · Google Drive connection

## What works in `0.24.0-dev`

Photo Inbox remains local-first. Each photograph is saved into the browser's IndexedDB database together with a generated thumbnail preview, day tag, optional place, caption, favorite flag, and Drive-upload state.

Phase 2 adds an optional Google Drive path:

1. Configure a Google OAuth web client ID.
2. Configure a Google Picker API key and numeric Cloud project number when you want to choose an existing folder.
3. Connect Google Drive deliberately.
4. Create a new app-owned trip folder or select an accessible existing folder.
5. Upload one photograph or upload every pending photograph.
6. Retry failed uploads, pause after the current file, or cancel the current upload.
7. Preserve the returned Drive file ID and Drive link in the local photograph record.

Local originals are never deleted automatically after Drive upload.

## Repairing photographs added in Phase 1

Older Phase P1 records may contain the original blob but no durable thumbnail. Open Photo Inbox and press **Repair previews**. The app generates compact previews while keeping the originals intact.

## Google Cloud setup

Create or select a Google Cloud project, then enable:

- Google Drive API
- Google Picker API

Configure the OAuth consent screen. During private testing, add the intended Google accounts as test users.

Create an OAuth client ID of type **Web application**. Add the desktop development origin:

```text
http://localhost:8080
```

For the phone workflow, deploy the static shell through HTTPS, then add the deployed origin, for example:

```text
https://YOUR_PROJECT.pages.dev
```

Copy the OAuth client ID into Photo Inbox.

To use **Choose existing folder**, create an API key and copy the numeric Cloud project number. Paste both into Photo Inbox.

## Security boundary

The static browser build uses the narrow scope:

```text
https://www.googleapis.com/auth/drive.file
```

Access tokens remain in memory and are not written to local storage. You reconnect after the token expires or after a page reload.

Do not place a Google OAuth client secret in the browser bundle. For a public production product, move long-lived authorization into a server-side flow and review Google's current OAuth guidance before launch.

## Folder choices

### Create trip folder

This is the simplest private-workspace setup. Connect Google Drive and press **Create trip folder**. The browser creates a Drive folder named `Japan Honeymoon Photo Inbox` unless you choose another name.

### Choose existing folder

Paste the API key and numeric project number, connect Google Drive, then press **Choose existing folder**. Google Picker opens in a modal window. Select the folder that should receive photographs.

### Paste a folder URL or ID

Paste a Drive folder URL or folder ID, save setup, connect Google Drive, then press **Verify folder**. This works only when the connected app is authorized to access that folder.

## Upload behavior

The app initiates a Drive resumable session for each photograph and then uploads the image blob. Returned Drive IDs and links are saved locally. A failed upload does not remove the local original.

## iPhone guidance

Use an HTTPS deployment for Google OAuth on an iPhone. Keep the LAN-served workspace for local map testing, but use the hosted HTTPS shell for Drive connection and phone uploads.

## Official references

- Google Drive uploads: https://developers.google.com/workspace/drive/api/guides/manage-uploads
- Google Drive OAuth scopes: https://developers.google.com/workspace/drive/api/guides/api-specific-auth
- Google Identity Services token model: https://developers.google.com/identity/oauth2/web/guides/use-token-model
- Google Picker web-app overview: https://developers.google.com/workspace/drive/picker/guides/overview