refactor: new project struct (#8199)

packages/frontend/web -> packages/frontend/apps/web
packages/frontend/mobile -> packages/frontend/apps/mobile
packages/frontend/electron -> packages/frontend/apps/electron

packages/frontend/apps/electron/src/helper/db/db-adapter.ts

@@ -0,0 +1,246 @@
+import type { InsertRow } from '@affine/native';
+import { SqliteConnection } from '@affine/native';
+import type { ByteKVBehavior } from '@toeverything/infra/storage';
+
+import { logger } from '../logger';
+
+/**
+ * A base class for SQLite DB adapter that provides basic methods around updates & blobs
+ */
+export class SQLiteAdapter {
+  db: SqliteConnection | null = null;
+  constructor(public readonly path: string) {}
+
+  async connectIfNeeded() {
+    if (!this.db) {
+      this.db = new SqliteConnection(this.path);
+      await this.db.connect();
+      logger.info(`[SQLiteAdapter]`, 'connected:', this.path);
+    }
+    return this.db;
+  }
+
+  async destroy() {
+    const { db } = this;
+    this.db = null;
+    // log after close will sometimes crash the app when quitting
+    logger.info(`[SQLiteAdapter]`, 'destroyed:', this.path);
+    await db?.close();
+  }
+
+  async addBlob(key: string, data: Uint8Array) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.addBlob(key, data);
+    } catch (error) {
+      logger.error('addBlob', error);
+    }
+  }
+
+  async getBlob(key: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return null;
+      }
+      const blob = await this.db.getBlob(key);
+      return blob?.data ?? null;
+    } catch (error) {
+      logger.error('getBlob', error);
+      return null;
+    }
+  }
+
+  async deleteBlob(key: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.deleteBlob(key);
+    } catch (error) {
+      logger.error(`${this.path} delete blob failed`, error);
+    }
+  }
+
+  async getBlobKeys() {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getBlobKeys();
+    } catch (error) {
+      logger.error(`getBlobKeys failed`, error);
+      return [];
+    }
+  }
+
+  async getUpdates(docId?: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getUpdates(docId);
+    } catch (error) {
+      logger.error('getUpdates', error);
+      return [];
+    }
+  }
+
+  async getAllUpdates() {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getAllUpdates();
+    } catch (error) {
+      logger.error('getAllUpdates', error);
+      return [];
+    }
+  }
+
+  // add a single update to SQLite
+  async addUpdateToSQLite(updates: InsertRow[]) {
+    // batch write instead write per key stroke?
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      const start = performance.now();
+      await this.db.insertUpdates(updates);
+      logger.debug(
+        `[SQLiteAdapter] addUpdateToSQLite`,
+        'length:',
+        updates.length,
+        'docids',
+        updates.map(u => u.docId),
+        performance.now() - start,
+        'ms'
+      );
+    } catch (error) {
+      logger.error('addUpdateToSQLite', this.path, error);
+    }
+  }
+
+  async deleteUpdates(docId?: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.deleteUpdates(docId);
+    } catch (error) {
+      logger.error('deleteUpdates', error);
+    }
+  }
+
+  async getUpdatesCount(docId?: string) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return 0;
+      }
+      return await this.db.getUpdatesCount(docId);
+    } catch (error) {
+      logger.error('getUpdatesCount', error);
+      return 0;
+    }
+  }
+
+  async replaceUpdates(docId: string | null | undefined, updates: InsertRow[]) {
+    try {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.replaceUpdates(docId, updates);
+    } catch (error) {
+      logger.error('replaceUpdates', error);
+    }
+  }
+
+  serverClock: ByteKVBehavior = {
+    get: async key => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return null;
+      }
+      const blob = await this.db.getServerClock(key);
+      return blob?.data ?? null;
+    },
+    set: async (key, data) => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.setServerClock(key, data);
+    },
+    keys: async () => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getServerClockKeys();
+    },
+    del: async key => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.delServerClock(key);
+    },
+    clear: async () => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.clearServerClock();
+    },
+  };
+
+  syncMetadata: ByteKVBehavior = {
+    get: async key => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return null;
+      }
+      const blob = await this.db.getSyncMetadata(key);
+      return blob?.data ?? null;
+    },
+    set: async (key, data) => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.setSyncMetadata(key, data);
+    },
+    keys: async () => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return [];
+      }
+      return await this.db.getSyncMetadataKeys();
+    },
+    del: async key => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.delSyncMetadata(key);
+    },
+    clear: async () => {
+      if (!this.db) {
+        logger.warn(`${this.path} is not connected`);
+        return;
+      }
+      await this.db.clearSyncMetadata();
+    },
+  };
+}

packages/frontend/apps/electron/src/helper/db/ensure-db.ts

@@ -0,0 +1,43 @@
+import { logger } from '../logger';
+import type { SpaceType } from './types';
+import type { WorkspaceSQLiteDB } from './workspace-db-adapter';
+import { openWorkspaceDatabase } from './workspace-db-adapter';
+
+// export for testing
+export const db$Map = new Map<
+  `${SpaceType}:${string}`,
+  Promise<WorkspaceSQLiteDB>
+>();
+
+async function getWorkspaceDB(spaceType: SpaceType, id: string) {
+  const cacheId = `${spaceType}:${id}` as const;
+  let db = await db$Map.get(cacheId);
+  if (!db) {
+    const promise = openWorkspaceDatabase(spaceType, id);
+    db$Map.set(cacheId, promise);
+    const _db = (db = await promise);
+    const cleanup = () => {
+      db$Map.delete(cacheId);
+      _db
+        .destroy()
+        .then(() => {
+          logger.info('[ensureSQLiteDB] db connection closed', _db.workspaceId);
+        })
+        .catch(err => {
+          logger.error('[ensureSQLiteDB] destroy db failed', err);
+        });
+    };
+
+    db.update$.subscribe({
+      complete: cleanup,
+    });
+
+    process.on('beforeExit', cleanup);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return db!;
+}
+
+export function ensureSQLiteDB(spaceType: SpaceType, id: string) {
+  return getWorkspaceDB(spaceType, id);
+}

packages/frontend/apps/electron/src/helper/db/index.ts

@@ -0,0 +1,130 @@
+import { mainRPC } from '../main-rpc';
+import type { MainEventRegister } from '../type';
+import { ensureSQLiteDB } from './ensure-db';
+import type { SpaceType } from './types';
+
+export * from './ensure-db';
+
+export const dbHandlers = {
+  getDocAsUpdates: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    subdocId: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.getDocAsUpdates(subdocId);
+  },
+  applyDocUpdate: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    update: Uint8Array,
+    subdocId: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.addUpdateToSQLite(update, subdocId);
+  },
+  deleteDoc: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    subdocId: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.deleteUpdate(subdocId);
+  },
+  addBlob: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string,
+    data: Uint8Array
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.addBlob(key, data);
+  },
+  getBlob: async (spaceType: SpaceType, workspaceId: string, key: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.getBlob(key);
+  },
+  deleteBlob: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.deleteBlob(key);
+  },
+  getBlobKeys: async (spaceType: SpaceType, workspaceId: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.getBlobKeys();
+  },
+  getDefaultStorageLocation: async () => {
+    return await mainRPC.getPath('sessionData');
+  },
+  getServerClock: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.serverClock.get(key);
+  },
+  setServerClock: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string,
+    data: Uint8Array
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.serverClock.set(key, data);
+  },
+  getServerClockKeys: async (spaceType: SpaceType, workspaceId: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.serverClock.keys();
+  },
+  clearServerClock: async (spaceType: SpaceType, workspaceId: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.serverClock.clear();
+  },
+  delServerClock: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.serverClock.del(key);
+  },
+  getSyncMetadata: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.syncMetadata.get(key);
+  },
+  setSyncMetadata: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string,
+    data: Uint8Array
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.syncMetadata.set(key, data);
+  },
+  getSyncMetadataKeys: async (spaceType: SpaceType, workspaceId: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.syncMetadata.keys();
+  },
+  clearSyncMetadata: async (spaceType: SpaceType, workspaceId: string) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.syncMetadata.clear();
+  },
+  delSyncMetadata: async (
+    spaceType: SpaceType,
+    workspaceId: string,
+    key: string
+  ) => {
+    const spaceDB = await ensureSQLiteDB(spaceType, workspaceId);
+    return spaceDB.adapter.syncMetadata.del(key);
+  },
+};
+
+export const dbEvents = {} satisfies Record<string, MainEventRegister>;

packages/frontend/apps/electron/src/helper/db/merge-update.ts

@@ -0,0 +1,17 @@
+import { applyUpdate, Doc as YDoc, encodeStateAsUpdate, transact } from 'yjs';
+
+export function mergeUpdate(updates: Uint8Array[]) {
+  if (updates.length === 0) {
+    return new Uint8Array();
+  }
+  if (updates.length === 1) {
+    return updates[0];
+  }
+  const yDoc = new YDoc();
+  transact(yDoc, () => {
+    for (const update of updates) {
+      applyUpdate(yDoc, update);
+    }
+  });
+  return encodeStateAsUpdate(yDoc);
+}

packages/frontend/apps/electron/src/helper/db/types.ts

@@ -0,0 +1 @@
+export type SpaceType = 'userspace' | 'workspace';

packages/frontend/apps/electron/src/helper/db/workspace-db-adapter.ts

@@ -0,0 +1,134 @@
+import { AsyncLock } from '@toeverything/infra/utils';
+import { Subject } from 'rxjs';
+import { applyUpdate, Doc as YDoc } from 'yjs';
+
+import { logger } from '../logger';
+import { getWorkspaceMeta } from '../workspace/meta';
+import { SQLiteAdapter } from './db-adapter';
+import { mergeUpdate } from './merge-update';
+import type { SpaceType } from './types';
+
+const TRIM_SIZE = 1;
+
+export class WorkspaceSQLiteDB {
+  lock = new AsyncLock();
+  update$ = new Subject<void>();
+  adapter = new SQLiteAdapter(this.path);
+
+  constructor(
+    public path: string,
+    public workspaceId: string
+  ) {}
+
+  async transaction<T>(cb: () => Promise<T>): Promise<T> {
+    using _lock = await this.lock.acquire();
+    return await cb();
+  }
+
+  async destroy() {
+    await this.adapter.destroy();
+
+    // when db is closed, we can safely remove it from ensure-db list
+    this.update$.complete();
+  }
+
+  private readonly toDBDocId = (docId: string) => {
+    return this.workspaceId === docId ? undefined : docId;
+  };
+
+  getWorkspaceName = async () => {
+    const ydoc = new YDoc();
+    const updates = await this.adapter.getUpdates();
+    updates.forEach(update => {
+      applyUpdate(ydoc, update.data);
+    });
+    return ydoc.getMap('meta').get('name') as string;
+  };
+
+  async init() {
+    const db = await this.adapter.connectIfNeeded();
+    await this.tryTrim();
+    return db;
+  }
+
+  async get(docId: string) {
+    return this.adapter.getUpdates(docId);
+  }
+
+  // getUpdates then encode
+  getDocAsUpdates = async (docId: string) => {
+    const dbID = this.toDBDocId(docId);
+    const update = await this.tryTrim(dbID);
+    if (update) {
+      return update;
+    } else {
+      const updates = await this.adapter.getUpdates(dbID);
+      return mergeUpdate(updates.map(row => row.data));
+    }
+  };
+
+  async addBlob(key: string, value: Uint8Array) {
+    this.update$.next();
+    const res = await this.adapter.addBlob(key, value);
+    return res;
+  }
+
+  async getBlob(key: string) {
+    return this.adapter.getBlob(key);
+  }
+
+  async getBlobKeys() {
+    return this.adapter.getBlobKeys();
+  }
+
+  async deleteBlob(key: string) {
+    this.update$.next();
+    await this.adapter.deleteBlob(key);
+  }
+
+  async addUpdateToSQLite(update: Uint8Array, subdocId: string) {
+    this.update$.next();
+    await this.transaction(async () => {
+      const dbID = this.toDBDocId(subdocId);
+      const oldUpdate = await this.adapter.getUpdates(dbID);
+      await this.adapter.replaceUpdates(dbID, [
+        {
+          data: mergeUpdate([...oldUpdate.map(u => u.data), update]),
+          docId: dbID,
+        },
+      ]);
+    });
+  }
+
+  async deleteUpdate(subdocId: string) {
+    this.update$.next();
+    await this.adapter.deleteUpdates(this.toDBDocId(subdocId));
+  }
+
+  private readonly tryTrim = async (dbID?: string) => {
+    const count = (await this.adapter?.getUpdatesCount(dbID)) ?? 0;
+    if (count > TRIM_SIZE) {
+      return await this.transaction(async () => {
+        logger.debug(`trim ${this.workspaceId}:${dbID} ${count}`);
+        const updates = await this.adapter.getUpdates(dbID);
+        const update = mergeUpdate(updates.map(row => row.data));
+        const insertRows = [{ data: update, docId: dbID }];
+        await this.adapter?.replaceUpdates(dbID, insertRows);
+        logger.debug(`trim ${this.workspaceId}:${dbID} successfully`);
+        return update;
+      });
+    }
+    return null;
+  };
+}
+
+export async function openWorkspaceDatabase(
+  spaceType: SpaceType,
+  spaceId: string
+) {
+  const meta = await getWorkspaceMeta(spaceType, spaceId);
+  const db = new WorkspaceSQLiteDB(meta.mainDBPath, spaceId);
+  await db.init();
+  logger.info(`openWorkspaceDatabase [${spaceId}]`);
+  return db;
+}

packages/frontend/apps/electron/src/helper/dialog/dialog.ts

@@ -0,0 +1,221 @@
+import { ValidationResult } from '@affine/native';
+import fs from 'fs-extra';
+import { nanoid } from 'nanoid';
+
+import { ensureSQLiteDB } from '../db/ensure-db';
+import { logger } from '../logger';
+import { mainRPC } from '../main-rpc';
+import { storeWorkspaceMeta } from '../workspace';
+import { getWorkspaceDBPath, getWorkspacesBasePath } from '../workspace/meta';
+
+export type ErrorMessage =
+  | 'DB_FILE_ALREADY_LOADED'
+  | 'DB_FILE_PATH_INVALID'
+  | 'DB_FILE_INVALID'
+  | 'DB_FILE_MIGRATION_FAILED'
+  | 'FILE_ALREADY_EXISTS'
+  | 'UNKNOWN_ERROR';
+
+export interface LoadDBFileResult {
+  workspaceId?: string;
+  error?: ErrorMessage;
+  canceled?: boolean;
+}
+
+export interface SaveDBFileResult {
+  filePath?: string;
+  canceled?: boolean;
+  error?: ErrorMessage;
+}
+
+export interface SelectDBFileLocationResult {
+  filePath?: string;
+  error?: ErrorMessage;
+  canceled?: boolean;
+}
+
+// provide a backdoor to set dialog path for testing in playwright
+export interface FakeDialogResult {
+  canceled?: boolean;
+  filePath?: string;
+  filePaths?: string[];
+}
+
+// result will be used in the next call to showOpenDialog
+// if it is being read once, it will be reset to undefined
+let fakeDialogResult: FakeDialogResult | undefined = undefined;
+
+function getFakedResult() {
+  const result = fakeDialogResult;
+  fakeDialogResult = undefined;
+  return result;
+}
+
+export function setFakeDialogResult(result: FakeDialogResult | undefined) {
+  fakeDialogResult = result;
+  // for convenience, we will fill filePaths with filePath if it is not set
+  if (result?.filePaths === undefined && result?.filePath !== undefined) {
+    result.filePaths = [result.filePath];
+  }
+}
+
+const extension = 'affine';
+
+function getDefaultDBFileName(name: string, id: string) {
+  const fileName = `${name}_${id}.${extension}`;
+  // make sure fileName is a valid file name
+  return fileName.replace(/[/\\?%*:|"<>]/g, '-');
+}
+
+/**
+ * This function is called when the user clicks the "Save" button in the "Save Workspace" dialog.
+ *
+ * It will just copy the file to the given path
+ */
+export async function saveDBFileAs(
+  workspaceId: string
+): Promise<SaveDBFileResult> {
+  try {
+    const db = await ensureSQLiteDB('workspace', workspaceId);
+    const fakedResult = getFakedResult();
+
+    const ret =
+      fakedResult ??
+      (await mainRPC.showSaveDialog({
+        properties: ['showOverwriteConfirmation'],
+        title: 'Save Workspace',
+        showsTagField: false,
+        buttonLabel: 'Save',
+        filters: [
+          {
+            extensions: [extension],
+            name: '',
+          },
+        ],
+        defaultPath: getDefaultDBFileName(
+          await db.getWorkspaceName(),
+          workspaceId
+        ),
+        message: 'Save Workspace as a SQLite Database file',
+      }));
+    const filePath = ret.filePath;
+    if (ret.canceled || !filePath) {
+      return {
+        canceled: true,
+      };
+    }
+
+    await fs.copyFile(db.path, filePath);
+    logger.log('saved', filePath);
+    if (!fakedResult) {
+      mainRPC.showItemInFolder(filePath).catch(err => {
+        console.error(err);
+      });
+    }
+    return { filePath };
+  } catch (err) {
+    logger.error('saveDBFileAs', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}
+
+export async function selectDBFileLocation(): Promise<SelectDBFileLocationResult> {
+  try {
+    const ret =
+      getFakedResult() ??
+      (await mainRPC.showOpenDialog({
+        properties: ['openDirectory'],
+        title: 'Set Workspace Storage Location',
+        buttonLabel: 'Select',
+        defaultPath: await mainRPC.getPath('documents'),
+        message: "Select a location to store the workspace's database file",
+      }));
+    const dir = ret.filePaths?.[0];
+    if (ret.canceled || !dir) {
+      return {
+        canceled: true,
+      };
+    }
+    return { filePath: dir };
+  } catch (err) {
+    logger.error('selectDBFileLocation', err);
+    return {
+      error: (err as any).message,
+    };
+  }
+}
+
+/**
+ * This function is called when the user clicks the "Load" button in the "Load Workspace" dialog.
+ *
+ * It will
+ * - symlink the source db file to a new workspace id to app-data
+ * - return the new workspace id
+ *
+ * eg, it will create a new folder in app-data:
+ * <app-data>/<app-name>/workspaces/<workspace-id>/storage.db
+ *
+ * On the renderer side, after the UI got a new workspace id, it will
+ * update the local workspace id list and then connect to it.
+ *
+ */
+export async function loadDBFile(): Promise<LoadDBFileResult> {
+  try {
+    const ret =
+      getFakedResult() ??
+      (await mainRPC.showOpenDialog({
+        properties: ['openFile'],
+        title: 'Load Workspace',
+        buttonLabel: 'Load',
+        filters: [
+          {
+            name: 'SQLite Database',
+            // do we want to support other file format?
+            extensions: ['db', 'affine'],
+          },
+        ],
+        message: 'Load Workspace from a AFFiNE file',
+      }));
+    const originalPath = ret.filePaths?.[0];
+    if (ret.canceled || !originalPath) {
+      logger.info('loadDBFile canceled');
+      return { canceled: true };
+    }
+
+    // the imported file should not be in app data dir
+    if (originalPath.startsWith(await getWorkspacesBasePath())) {
+      logger.warn('loadDBFile: db file in app data dir');
+      return { error: 'DB_FILE_PATH_INVALID' };
+    }
+
+    const { SqliteConnection } = await import('@affine/native');
+
+    const validationResult = await SqliteConnection.validate(originalPath);
+
+    if (validationResult !== ValidationResult.Valid) {
+      return { error: 'DB_FILE_INVALID' }; // invalid db file
+    }
+
+    // copy the db file to a new workspace id
+    const workspaceId = nanoid(10);
+    const internalFilePath = await getWorkspaceDBPath('workspace', workspaceId);
+
+    await fs.ensureDir(await getWorkspacesBasePath());
+    await fs.copy(originalPath, internalFilePath);
+    logger.info(`loadDBFile, copy: ${originalPath} -> ${internalFilePath}`);
+
+    await storeWorkspaceMeta(workspaceId, {
+      id: workspaceId,
+      mainDBPath: internalFilePath,
+    });
+
+    return { workspaceId };
+  } catch (err) {
+    logger.error('loadDBFile', err);
+    return {
+      error: 'UNKNOWN_ERROR',
+    };
+  }
+}

packages/frontend/apps/electron/src/helper/dialog/index.ts

@@ -0,0 +1,23 @@
+import {
+  loadDBFile,
+  saveDBFileAs,
+  selectDBFileLocation,
+  setFakeDialogResult,
+} from './dialog';
+
+export const dialogHandlers = {
+  loadDBFile: async () => {
+    return loadDBFile();
+  },
+  saveDBFileAs: async (workspaceId: string) => {
+    return saveDBFileAs(workspaceId);
+  },
+  selectDBFileLocation: async () => {
+    return selectDBFileLocation();
+  },
+  setFakeDialogResult: async (
+    result: Parameters<typeof setFakeDialogResult>[0]
+  ) => {
+    return setFakeDialogResult(result);
+  },
+};

packages/frontend/apps/electron/src/helper/exposed.ts

@@ -0,0 +1,36 @@
+import { dbEvents, dbHandlers } from './db';
+import { dialogHandlers } from './dialog';
+import { provideExposed } from './provide';
+import { workspaceEvents, workspaceHandlers } from './workspace';
+
+export const handlers = {
+  db: dbHandlers,
+  workspace: workspaceHandlers,
+  dialog: dialogHandlers,
+};
+
+export const events = {
+  db: dbEvents,
+  workspace: workspaceEvents,
+};
+
+const getExposedMeta = () => {
+  const handlersMeta = Object.entries(handlers).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)] as [string, string[]];
+    }
+  );
+
+  const eventsMeta = Object.entries(events).map(
+    ([namespace, namespaceHandlers]) => {
+      return [namespace, Object.keys(namespaceHandlers)] as [string, string[]];
+    }
+  );
+
+  return {
+    handlers: handlersMeta,
+    events: eventsMeta,
+  };
+};
+
+provideExposed(getExposedMeta());

packages/frontend/apps/electron/src/helper/index.ts

@@ -0,0 +1,82 @@
+import { AsyncCall } from 'async-call-rpc';
+
+import type { RendererToHelper } from '../shared/type';
+import { events, handlers } from './exposed';
+import { logger } from './logger';
+
+function setupRendererConnection(rendererPort: Electron.MessagePortMain) {
+  const flattenedHandlers = Object.entries(handlers).flatMap(
+    ([namespace, namespaceHandlers]) => {
+      return Object.entries(namespaceHandlers).map(([name, handler]) => {
+        const handlerWithLog = async (...args: any[]) => {
+          try {
+            const start = performance.now();
+            const result = await handler(...args);
+            logger.debug(
+              '[async-api]',
+              `${namespace}.${name}`,
+              args.filter(
+                arg => typeof arg !== 'function' && typeof arg !== 'object'
+              ),
+              '-',
+              (performance.now() - start).toFixed(2),
+              'ms'
+            );
+            return result;
+          } catch (error) {
+            logger.error('[async-api]', `${namespace}.${name}`, error);
+          }
+        };
+        return [`${namespace}:${name}`, handlerWithLog];
+      });
+    }
+  );
+  const rpc = AsyncCall<RendererToHelper>(
+    Object.fromEntries(flattenedHandlers),
+    {
+      channel: {
+        on(listener) {
+          const f = (e: Electron.MessageEvent) => {
+            listener(e.data);
+          };
+          rendererPort.on('message', f);
+          // MUST start the connection to receive messages
+          rendererPort.start();
+          return () => {
+            rendererPort.off('message', f);
+          };
+        },
+        send(data) {
+          rendererPort.postMessage(data);
+        },
+      },
+      log: false,
+    }
+  );
+
+  for (const [namespace, namespaceEvents] of Object.entries(events)) {
+    for (const [key, eventRegister] of Object.entries(namespaceEvents)) {
+      const unsub = eventRegister((...args: any[]) => {
+        const chan = `${namespace}:${key}`;
+        rpc.postEvent(chan, ...args).catch(err => {
+          console.error(err);
+        });
+      });
+      process.on('exit', () => {
+        unsub();
+      });
+    }
+  }
+}
+
+function main() {
+  process.parentPort.on('message', e => {
+    if (e.data.channel === 'renderer-connect' && e.ports.length === 1) {
+      const rendererPort = e.ports[0];
+      setupRendererConnection(rendererPort);
+      logger.info('[helper] renderer connected');
+    }
+  });
+}
+
+main();

packages/frontend/apps/electron/src/helper/logger.ts

@@ -0,0 +1,5 @@
+import log from 'electron-log/main';
+
+export const logger = log.scope('helper');
+
+log.transports.file.level = 'info';

packages/frontend/apps/electron/src/helper/main-rpc.ts

@@ -0,0 +1,32 @@
+import { assertExists } from '@blocksuite/global/utils';
+import { AsyncCall } from 'async-call-rpc';
+
+import type { HelperToMain, MainToHelper } from '../shared/type';
+import { exposed } from './provide';
+
+const helperToMainServer: HelperToMain = {
+  getMeta: () => {
+    assertExists(exposed);
+    return exposed;
+  },
+};
+
+export const mainRPC = AsyncCall<MainToHelper>(helperToMainServer, {
+  strict: {
+    unknownMessage: false,
+  },
+  channel: {
+    on(listener) {
+      const f = (e: Electron.MessageEvent) => {
+        listener(e.data);
+      };
+      process.parentPort.on('message', f);
+      return () => {
+        process.parentPort.off('message', f);
+      };
+    },
+    send(data) {
+      process.parentPort.postMessage(data);
+    },
+  },
+});

packages/frontend/apps/electron/src/helper/provide.ts

@@ -0,0 +1,11 @@
+import type { ExposedMeta } from '../shared/type';
+
+/**
+ * A naive DI implementation to get rid of circular dependency.
+ */
+
+export let exposed: ExposedMeta | undefined;
+
+export const provideExposed = (exposedMeta: ExposedMeta) => {
+  exposed = exposedMeta;
+};

packages/frontend/apps/electron/src/helper/type.ts

@@ -0,0 +1,8 @@
+export interface WorkspaceMeta {
+  id: string;
+  mainDBPath: string;
+}
+
+export type YOrigin = 'self' | 'external' | 'upstream' | 'renderer';
+
+export type MainEventRegister = (...args: any[]) => () => void;

packages/frontend/apps/electron/src/helper/workspace/handlers.ts

@@ -0,0 +1,45 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+
+import { ensureSQLiteDB } from '../db/ensure-db';
+import { logger } from '../logger';
+import type { WorkspaceMeta } from '../type';
+import {
+  getDeletedWorkspacesBasePath,
+  getWorkspaceBasePath,
+  getWorkspaceMeta,
+} from './meta';
+
+export async function deleteWorkspace(id: string) {
+  const basePath = await getWorkspaceBasePath('workspace', id);
+  const movedPath = path.join(await getDeletedWorkspacesBasePath(), `${id}`);
+  try {
+    const db = await ensureSQLiteDB('workspace', id);
+    await db.destroy();
+    return await fs.move(basePath, movedPath, {
+      overwrite: true,
+    });
+  } catch (error) {
+    logger.error('deleteWorkspace', error);
+  }
+}
+
+export async function storeWorkspaceMeta(
+  workspaceId: string,
+  meta: Partial<WorkspaceMeta>
+) {
+  try {
+    const basePath = await getWorkspaceBasePath('workspace', workspaceId);
+    await fs.ensureDir(basePath);
+    const metaPath = path.join(basePath, 'meta.json');
+    const currentMeta = await getWorkspaceMeta('workspace', workspaceId);
+    const newMeta = {
+      ...currentMeta,
+      ...meta,
+    };
+    await fs.writeJSON(metaPath, newMeta);
+  } catch (err) {
+    logger.error('storeWorkspaceMeta failed', err);
+  }
+}

packages/frontend/apps/electron/src/helper/workspace/index.ts

@@ -0,0 +1,11 @@
+import type { MainEventRegister } from '../type';
+import { deleteWorkspace } from './handlers';
+
+export * from './handlers';
+export * from './subjects';
+
+export const workspaceEvents = {} as Record<string, MainEventRegister>;
+
+export const workspaceHandlers = {
+  delete: async (id: string) => deleteWorkspace(id),
+};

packages/frontend/apps/electron/src/helper/workspace/meta.ts

@@ -0,0 +1,94 @@
+import path from 'node:path';
+
+import fs from 'fs-extra';
+
+import type { SpaceType } from '../db/types';
+import { logger } from '../logger';
+import { mainRPC } from '../main-rpc';
+import type { WorkspaceMeta } from '../type';
+
+let _appDataPath = '';
+
+export async function getAppDataPath() {
+  if (_appDataPath) {
+    return _appDataPath;
+  }
+  _appDataPath = await mainRPC.getPath('sessionData');
+  return _appDataPath;
+}
+
+export async function getWorkspacesBasePath() {
+  return path.join(await getAppDataPath(), 'workspaces');
+}
+
+export async function getWorkspaceBasePath(
+  spaceType: SpaceType,
+  workspaceId: string
+) {
+  return path.join(
+    await getAppDataPath(),
+    spaceType === 'userspace' ? 'userspaces' : 'workspaces',
+    workspaceId
+  );
+}
+
+export async function getDeletedWorkspacesBasePath() {
+  return path.join(await getAppDataPath(), 'deleted-workspaces');
+}
+
+export async function getWorkspaceDBPath(
+  spaceType: SpaceType,
+  workspaceId: string
+) {
+  return path.join(
+    await getWorkspaceBasePath(spaceType, workspaceId),
+    'storage.db'
+  );
+}
+
+export async function getWorkspaceMetaPath(
+  spaceType: SpaceType,
+  workspaceId: string
+) {
+  return path.join(
+    await getWorkspaceBasePath(spaceType, workspaceId),
+    'meta.json'
+  );
+}
+
+/**
+ * Get workspace meta, create one if not exists
+ * This function will also migrate the workspace if needed
+ */
+export async function getWorkspaceMeta(
+  spaceType: SpaceType,
+  workspaceId: string
+): Promise<WorkspaceMeta> {
+  try {
+    const basePath = await getWorkspaceBasePath(spaceType, workspaceId);
+    const metaPath = await getWorkspaceMetaPath(spaceType, workspaceId);
+    if (
+      !(await fs
+        .access(metaPath)
+        .then(() => true)
+        .catch(() => false))
+    ) {
+      await fs.ensureDir(basePath);
+      const dbPath = await getWorkspaceDBPath(spaceType, workspaceId);
+      // create one if not exists
+      const meta = {
+        id: workspaceId,
+        mainDBPath: dbPath,
+        type: spaceType,
+      };
+      await fs.writeJSON(metaPath, meta);
+      return meta;
+    } else {
+      const meta = await fs.readJSON(metaPath);
+      return meta;
+    }
+  } catch (err) {
+    logger.error('getWorkspaceMeta failed', err);
+    throw err;
+  }
+}

packages/frontend/apps/electron/src/helper/workspace/subjects.ts

@@ -0,0 +1,7 @@
+import { Subject } from 'rxjs';
+
+import type { WorkspaceMeta } from '../type';
+
+export const workspaceSubjects = {
+  meta$: new Subject<{ workspaceId: string; meta: WorkspaceMeta }>(),
+};