# StratoFusion Project Overview

StratoFusion is a SaaS application that unifies multiple cloud storage providers behind one interface. The core user value is consistent browsing, search, transfer, backup, and sync workflows across providers such as Google Drive, OneDrive, and Dropbox.

## Core Architecture

- The web app is built with Next.js App Router and TypeScript.
- Provider-specific behavior is normalized behind shared service interfaces and adapters.
- Production runs on an OVHcloud VM Compose stack behind Caddy.
- Large data-plane operations run through the VM-hosted rclone worker instead of the browser or Next.js request process.
- Usage limits, job state, provider metadata, and operation state persist in the production Compose PostgreSQL database.
- AI indexing and semantic retrieval are isolated under `src/lib/search/ai/*` and stay behind runtime rollout flags.

The previous Vercel production, Neon production, and Fly.io rclone deployments
are retained legacy rollback resources. See [Architecture Evolution](./ARCHITECTURE_EVOLUTION.md)
for current, legacy, transitional, and planned classifications.

## Product Surfaces

- Authenticated app routes under `/user/*` cover dashboard, billing, jobs, quotas, and activity.
- `/drive` keeps browsing, search, and file operations focused on the active provider/account scope.
- `/user/dashboard` surfaces storage availability, active jobs, quotas, recent activity, and account health.
- `/user/ai-indexing` exposes AI indexing progress, diagnostics, retry, cancel, and dismiss controls separate from transfer jobs.
- Public docs and legal routes explain operational limits, privacy, and deployment tradeoffs.
- `/about` and `/articles` provide crawlable founder and owned-content surfaces; `/feed.xml`, `/sitemap.xml`, and `/robots.txt` provide deliberate discovery metadata. Article drafts stay repository-private until human publication review.
- `/dev/docs` is the consolidated engineering documentation entry point for local development.

## Capability Snapshot

- Connects Google Drive, OneDrive, and Dropbox behind one canonical file model, with additional provider shells documented for future expansion.
- Supports browsing, provider-native search, full-text search, uploads, downloads, copy, move, rename, delete, backup, sync, and activity logging.
- Executes cross-provider copy, move, backup, and sync work through the VM rclone service with job progress streamed back to the app.
- Keeps provider-specific IDs, paths, namespace rules, and API quirks behind service adapters and backend ports.
- Gates subscription, quota, provider auth, and runtime availability before launching costly or long-running work.
- Provides AI Search indexing, semantic retrieval, and grounded Ask AI behind independent rollout flags and fail-soft infrastructure boundaries.

## Current Operational Behaviors

- `/user/dashboard` is the primary storage and account-health surface. It shows full storage availability, active jobs, quota warnings, and recent activity while `/drive` stays focused on current-folder file work.
- Provider services emit canonical `/parent/item` paths where possible so dialogs, activity logs, tooltips, search results, and transfer prompts do not reconstruct provider paths in UI code.
- Batch copy and move launch streams emit NDJSON progress during validation, filtering, and per-operation rclone startup. Clients can begin operation SSE monitoring as each operation ID is created.
- Backup and sync jobs persist durable intent first, then launch rclone child operations without blocking on full recursive enumeration. Reconciliation repairs stale running jobs when child operations have already reached terminal states.
- Cancellation, retry, timeout, auth-refresh, transfer-quota, and provider-throttle states are explicit job outcomes. User prompts distinguish reconnect, billing, retry, and support actions instead of exposing raw provider or rclone errors.
- Large backup and sync profiles forward conservative timeout, stall-watchdog, listing/checking, and resource flags to the rclone worker so metadata-heavy runs are not cancelled as false stalls.
- One-way syncs preserve real empty folders, two-way syncs expose first-run and recovery resync controls, and Google Drive to non-Google bisync skips native Google Workspace files that rclone cannot safely reverse-copy.
- Billing supports one-time 7-day Pro and Unlimited trials through Stripe Checkout, card collection before the trial, Billing Portal payment-update prompts, and Free-plan handling for historical cancelled subscriptions.
- Admin hard delete for non-production users removes Clerk, environment-specific PostgreSQL, Stripe test-customer, provider-grant, and AI semantic-search state on a best-effort basis.
- AI indexing has a dedicated `/user/ai-indexing` surface with progress, diagnostics, retry, cancellation, and dismissal controls separate from backup/sync jobs.

## Runtime Safety

- rclone commands default to dry-run during manual operations unless a task explicitly authorizes live execution.
- Destructive transfer behavior such as delete, purge, or sync deletion requires explicit source, destination, flags, and confirmation.
- UI components should remain render-focused; provider, quota, auth, and job behavior belongs in domain or service modules.
- Provider and account identity form the boundary for user data: `(provider, account, resource)`.

## Documentation Map

- [Documentation Index](./INDEX.md).
- [User Guide Hub](./user-guide/INDEX.md).
- [Developer Hub](./developer/INDEX.md).
- [Operations Hub](./operations/INDEX.md).
- [Prompt Catalog](./prompts/INDEX.md).
- [AI Search Architecture](./developer/modules/AI_SEARCH_ARCHITECTURE.md).
- [Architecture Evolution](./ARCHITECTURE_EVOLUTION.md).
- [Production VM Runbook](./operations/VM_PRODUCTION_RUNBOOK.md).

## Canonical Sources

- Root `README.md` remains the GitHub-facing landing document.
- Detailed engineering and operations content lives in `public/docs/`.
- Historical consolidation records are preserved under `public/docs/consolidation-history/`.