# Google Drive File Export

## Objective

Let users send app files and reports straight to a folder in their own Google Drive.

An authorized per-user Drive connection that uploads generated files to a folder the user picks, with resumable uploads and naming rules.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Request the narrowest scope that allows writing the files this feature creates, and prefer a scope limited to files the app itself created over one granting access to the user's whole Drive.
2. Have the user pick the destination folder explicitly through a selection flow, store the folder reference with the connection, and write only inside it. Never fall back to the Drive root when the stored folder cannot be found.
3. Upload through a resumable mechanism for anything larger than a trivial file, record the upload session against the export, and resume from the last confirmed position rather than restarting from zero after an interruption.
4. Define the collision rule before writing: either create a new version of the existing file or write a distinct name with a deterministic suffix. Do not silently overwrite a file the user may not have realized was there.
5. Run every export through the app's existing background-job system and show its state on the export record, so a large upload never holds a web request open or times out under the user's cursor.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Asking for broad Drive access to do a narrow job is the tempting shortcut and the wrong one. Request only what writing the app's own exports requires, and if a wider scope was ever granted, drop to the narrow one on the next reconnect and say so in the connection screen.
- A stored folder can be renamed, moved, trashed, or have its sharing revoked between exports. Verify the folder is still present and writable before uploading, and when it is not, pause the export and ask the user to reselect rather than writing somewhere else.
- Repeated exports of the same report will collide by name. Apply the chosen collision rule consistently, make the resulting name predictable so the user can find it, and never destroy an existing file without an explicit instruction.
- Large uploads fail partway on flaky connections and leave a fragment behind. Use resumable uploads, resume from the last acknowledged byte, and clean up abandoned partial uploads so the user's Drive does not fill with truncated files.
- The connection must not become a general-purpose door into the user's Drive. Do not list, read, or index unrelated content, do not cache directory structure beyond what the folder picker needs, and revoke the token cleanly when the integration is disconnected.
- Tokens expire and consent can be revoked by the user or a Workspace administrator. Refresh ahead of expiry, and on permanent authorization failure mark the connection disconnected and prompt a reconnect rather than retrying indefinitely.
- Drive rejects uploads when the account is out of storage or a size limit is exceeded. Distinguish those permanent conditions from transient failures, tell the user which one occurred in plain terms, and do not queue endless retries against a full account.
- When Drive is unavailable the export itself must still succeed. Generate the file, keep it downloadable from the app, and show the Drive delivery as pending with a retry rather than losing the export.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The connection requests only the minimum scope needed to write the app's own export files.
- [ ] The destination folder is chosen explicitly, and exports are written only inside it.
- [ ] A missing or unwritable folder pauses the export and asks the user to reselect instead of writing elsewhere.
- [ ] Filename collisions follow a stated rule and never silently overwrite an existing file.
- [ ] Interrupted uploads resume from the last confirmed position, and abandoned partials are cleaned up.
- [ ] Disconnecting the integration revokes the stored access, and no unrelated Drive content is read or retained.
- [ ] A Drive outage leaves the generated file available in the app with the delivery marked pending.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.