papers/lux-firebase-exit/sections/05-step-by-step-migration-guide.tex

\section{Step-by-Step Migration Guide}
\label{sec:migration}

We define the migration as a sequence of phases, each of which can be
completed independently. The application remains functional throughout
the migration---there is no big-bang cutover.

\subsection{Phase 1: Local Data Layer}

Replace Firestore reads with local SQLite reads. Firestore remains the
source of truth; SQLite is a local cache that is populated from Firestore
on first load and updated via Firestore listeners.

\begin{enumerate}
    \item Add SQLite (via sql.js for web, SQLite for native) to the application.
    \item Mirror the Firestore schema into SQLite tables.
    \item On app startup, sync Firestore data into SQLite.
    \item Replace all \texttt{getDoc()} / \texttt{getDocs()} calls with local
    SQLite queries.
    \item Firestore listeners update the local SQLite database in real time.
\end{enumerate}

At the end of Phase~1, all reads are local. Writes still go to Firestore.
The application works offline for reads.

\subsection{Phase 2: Local Writes with CRDT Sync}

Replace Firestore writes with local SQLite writes, synchronized via CRDTs.

\begin{enumerate}
    \item Add a CRDT layer (Automerge or Yjs) that wraps SQLite writes.
    \item Each local write produces a CRDT operation.
    \item CRDT operations are synced to Firestore (as a bridge) and to
    other devices via the CRDT sync protocol.
    \item Conflict resolution is handled by CRDT merge semantics, not
    Firestore's last-write-wins.
\end{enumerate}

At the end of Phase~2, the application is offline-first: reads and writes
work without network connectivity. Firestore is still in the loop as a
sync relay, but is no longer the source of truth.

\subsection{Phase 3: Encryption}

Add client-side encryption to the local SQLite database.

\begin{enumerate}
    \item Generate a capsule key (or derive from the user's authentication key).
    \item Enable SQLCipher encryption on the SQLite database.
    \item Encrypt CRDT operations before syncing.
    \item CRDT sync targets shift from Firestore to relay providers (Firestore
    can no longer read the data).
\end{enumerate}

At the end of Phase~3, the application is encrypted at rest and in transit.
No server-side component can read user data.

\subsection{Phase 4: Identity Migration}

Replace Firebase Auth with I-Chain DIDs.

\begin{enumerate}
    \item Generate a DID for each user, anchored on the I-Chain.
    \item Link the existing Firebase Auth identity to the DID (one-time binding).
    \item Replace Firebase Auth session checks with DID-based signature verification.
    \item Optionally maintain Firebase Auth as a fallback during the transition period.
    \item After transition, Firebase Auth can be removed entirely.
\end{enumerate}

\subsection{Phase 5: Function Migration}

Replace Cloud Functions with Base Functions.

\begin{enumerate}
    \item Identify all Cloud Functions and categorize them:
    \begin{itemize}
        \item \textbf{User-triggered}: Can run on the user's device.
        \item \textbf{Background}: Require compute provider with TEE.
        \item \textbf{Scheduled}: Require compute provider with cron support.
    \end{itemize}
    \item Rewrite user-triggered functions as local capsule functions.
    \item Deploy background and scheduled functions to compute providers in TEE mode.
    \item Remove Cloud Functions from Firebase.
\end{enumerate}

\subsection{Phase 6: Hosting Migration}

Replace Firebase Hosting with the decentralized provider market.

\begin{enumerate}
    \item Build static assets as usual.
    \item Upload encrypted assets to storage providers via \texttt{lux deploy}.
    \item Configure gateway providers to serve the application.
    \item Update DNS to point to gateway providers.
    \item Decommission Firebase Hosting.
\end{enumerate}

At the end of Phase~6, the application has no dependency on Firebase or any
single cloud provider. It is a sovereign capsule application.