From a3d10436e1b4f796f36fac320b8048a2d6f1c36d Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Mon, 9 Feb 2026 17:19:13 +0530
Subject: [PATCH 1/9] feat: implement project management handlers and refactor
 configuration utilities

---
 bridge/src/connectors/mariadb.ts         |   2 +-
 bridge/src/connectors/mysql.ts           |   2 +-
 bridge/src/connectors/postgres.ts        |   2 +-
 bridge/src/handlers/migrationHandlers.ts |   2 +-
 bridge/src/handlers/projectHandlers.ts   | 310 +++++++++++++++
 bridge/src/jsonRpcHandler.ts             |  48 +++
 bridge/src/services/dbStore.ts           |  27 +-
 bridge/src/services/projectStore.ts      | 486 +++++++++++++++++++++++
 bridge/src/utils/config.ts               |  37 ++
 9 files changed, 886 insertions(+), 30 deletions(-)
 create mode 100644 bridge/src/handlers/projectHandlers.ts
 create mode 100644 bridge/src/services/projectStore.ts
 create mode 100644 bridge/src/utils/config.ts

diff --git a/bridge/src/connectors/mariadb.ts b/bridge/src/connectors/mariadb.ts
index 896de96..8ce9151 100644
--- a/bridge/src/connectors/mariadb.ts
+++ b/bridge/src/connectors/mariadb.ts
@@ -7,7 +7,7 @@ import mysql, {
 import { loadLocalMigrations, writeBaselineMigration } from "../utils/baselineMigration";
 import crypto from "crypto";
 import fs from "fs";
-import { ensureDir, getMigrationsDir } from "../services/dbStore";
+import { ensureDir, getMigrationsDir } from "../utils/config";
 import {
     CacheEntry,
     CACHE_TTL,
diff --git a/bridge/src/connectors/mysql.ts b/bridge/src/connectors/mysql.ts
index 3500830..72acba9 100644
--- a/bridge/src/connectors/mysql.ts
+++ b/bridge/src/connectors/mysql.ts
@@ -7,7 +7,7 @@ import mysql, {
 import { loadLocalMigrations, writeBaselineMigration } from "../utils/baselineMigration";
 import crypto from "crypto";
 import fs from "fs";
-import { ensureDir, getMigrationsDir } from "../services/dbStore";
+import { ensureDir, getMigrationsDir } from "../utils/config";
 import {
   CacheEntry,
   CACHE_TTL,
diff --git a/bridge/src/connectors/postgres.ts b/bridge/src/connectors/postgres.ts
index 58654c1..19084dc 100644
--- a/bridge/src/connectors/postgres.ts
+++ b/bridge/src/connectors/postgres.ts
@@ -5,7 +5,7 @@ import { Readable } from "stream";
 import { loadLocalMigrations, writeBaselineMigration } from "../utils/baselineMigration";
 import crypto from "crypto";
 import fs from "fs";
-import { ensureDir, getMigrationsDir } from "../services/dbStore";
+import { ensureDir, getMigrationsDir } from "../utils/config";
 import {
   CacheEntry,
   CACHE_TTL,
diff --git a/bridge/src/handlers/migrationHandlers.ts b/bridge/src/handlers/migrationHandlers.ts
index 4f18b58..686740d 100644
--- a/bridge/src/handlers/migrationHandlers.ts
+++ b/bridge/src/handlers/migrationHandlers.ts
@@ -2,7 +2,7 @@ import { Rpc } from "../types";
 import { DatabaseService } from "../services/databaseService";
 import { QueryExecutor } from "../services/queryExecutor";
 import { Logger } from "pino";
-import { getMigrationsDir } from "../services/dbStore";
+import { getMigrationsDir } from "../utils/config";
 import path from "path";
 import fs from "fs";
 
diff --git a/bridge/src/handlers/projectHandlers.ts b/bridge/src/handlers/projectHandlers.ts
new file mode 100644
index 0000000..98a0a35
--- /dev/null
+++ b/bridge/src/handlers/projectHandlers.ts
@@ -0,0 +1,310 @@
+import { Rpc } from "../types";
+import { Logger } from "pino";
+import { projectStoreInstance } from "../services/projectStore";
+
+/**
+ * RPC handlers for project CRUD and sub-resource operations.
+ * Mirrors the DatabaseHandlers pattern.
+ */
+export class ProjectHandlers {
+    constructor(
+        private rpc: Rpc,
+        private logger: Logger
+    ) { }
+
+
+    async handleListProjects(_params: any, id: number | string) {
+        try {
+            const projects = await projectStoreInstance.listProjects();
+            this.rpc.sendResponse(id, { ok: true, data: projects });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.list failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleGetProject(params: any, id: number | string) {
+        try {
+            const { id: projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing id",
+                });
+            }
+
+            const project = await projectStoreInstance.getProject(projectId);
+            if (!project) {
+                return this.rpc.sendError(id, {
+                    code: "NOT_FOUND",
+                    message: "Project not found",
+                });
+            }
+
+            this.rpc.sendResponse(id, { ok: true, data: project });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.get failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleCreateProject(params: any, id: number | string) {
+        try {
+            const { databaseId, name, description, defaultSchema } = params || {};
+            if (!databaseId || !name) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing databaseId or name",
+                });
+            }
+
+            const project = await projectStoreInstance.createProject({
+                databaseId,
+                name,
+                description,
+                defaultSchema,
+            });
+
+            this.rpc.sendResponse(id, { ok: true, data: project });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.create failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleUpdateProject(params: any, id: number | string) {
+        try {
+            const { id: projectId, ...updates } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing id",
+                });
+            }
+
+            const project = await projectStoreInstance.updateProject(projectId, updates);
+            if (!project) {
+                return this.rpc.sendError(id, {
+                    code: "NOT_FOUND",
+                    message: "Project not found",
+                });
+            }
+
+            this.rpc.sendResponse(id, { ok: true, data: project });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.update failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleDeleteProject(params: any, id: number | string) {
+        try {
+            const { id: projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing id",
+                });
+            }
+
+            await projectStoreInstance.deleteProject(projectId);
+            this.rpc.sendResponse(id, { ok: true });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.delete failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleGetSchema(params: any, id: number | string) {
+        try {
+            const { projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId",
+                });
+            }
+
+            const schema = await projectStoreInstance.getSchema(projectId);
+            this.rpc.sendResponse(id, { ok: true, data: schema });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.getSchema failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleSaveSchema(params: any, id: number | string) {
+        try {
+            const { projectId, schemas } = params || {};
+            if (!projectId || !schemas) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId or schemas",
+                });
+            }
+
+            const result = await projectStoreInstance.saveSchema(projectId, schemas);
+            this.rpc.sendResponse(id, { ok: true, data: result });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.saveSchema failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleGetERDiagram(params: any, id: number | string) {
+        try {
+            const { projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId",
+                });
+            }
+
+            const diagram = await projectStoreInstance.getERDiagram(projectId);
+            this.rpc.sendResponse(id, { ok: true, data: diagram });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.getERDiagram failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleSaveERDiagram(params: any, id: number | string) {
+        try {
+            const { projectId, nodes, zoom, panX, panY } = params || {};
+            if (!projectId || !nodes) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId or nodes",
+                });
+            }
+
+            const result = await projectStoreInstance.saveERDiagram(projectId, {
+                nodes,
+                zoom,
+                panX,
+                panY,
+            });
+            this.rpc.sendResponse(id, { ok: true, data: result });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.saveERDiagram failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleGetQueries(params: any, id: number | string) {
+        try {
+            const { projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId",
+                });
+            }
+
+            const queries = await projectStoreInstance.getQueries(projectId);
+            this.rpc.sendResponse(id, { ok: true, data: queries });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.getQueries failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleAddQuery(params: any, id: number | string) {
+        try {
+            const { projectId, name, sql, description } = params || {};
+            if (!projectId || !name || !sql) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId, name, or sql",
+                });
+            }
+
+            const query = await projectStoreInstance.addQuery(projectId, {
+                name,
+                sql,
+                description,
+            });
+            this.rpc.sendResponse(id, { ok: true, data: query });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.addQuery failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleUpdateQuery(params: any, id: number | string) {
+        try {
+            const { projectId, queryId, ...updates } = params || {};
+            if (!projectId || !queryId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId or queryId",
+                });
+            }
+
+            const query = await projectStoreInstance.updateQuery(
+                projectId,
+                queryId,
+                updates
+            );
+            if (!query) {
+                return this.rpc.sendError(id, {
+                    code: "NOT_FOUND",
+                    message: "Query not found",
+                });
+            }
+
+            this.rpc.sendResponse(id, { ok: true, data: query });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.updateQuery failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    async handleDeleteQuery(params: any, id: number | string) {
+        try {
+            const { projectId, queryId } = params || {};
+            if (!projectId || !queryId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId or queryId",
+                });
+            }
+
+            await projectStoreInstance.deleteQuery(projectId, queryId);
+            this.rpc.sendResponse(id, { ok: true });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.deleteQuery failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
+    // ==========================================
+    // Export (for future git-native support)
+    // ==========================================
+
+    async handleExportProject(params: any, id: number | string) {
+        try {
+            const { projectId } = params || {};
+            if (!projectId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing projectId",
+                });
+            }
+
+            const bundle = await projectStoreInstance.exportProject(projectId);
+            if (!bundle) {
+                return this.rpc.sendError(id, {
+                    code: "NOT_FOUND",
+                    message: "Project not found",
+                });
+            }
+
+            this.rpc.sendResponse(id, { ok: true, data: bundle });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.export failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+}
diff --git a/bridge/src/jsonRpcHandler.ts b/bridge/src/jsonRpcHandler.ts
index 5c45512..824d823 100644
--- a/bridge/src/jsonRpcHandler.ts
+++ b/bridge/src/jsonRpcHandler.ts
@@ -7,6 +7,7 @@ import { DatabaseHandlers } from "./handlers/databaseHandlers";
 import { SessionHandlers } from "./handlers/sessionHandlers";
 import { StatsHandlers } from "./handlers/statsHandlers";
 import { MigrationHandlers } from "./handlers/migrationHandlers";
+import { ProjectHandlers } from "./handlers/projectHandlers";
 import { discoveryService } from "./services/discoveryService";
 import { Logger } from "pino";
 
@@ -52,6 +53,7 @@ export function registerDbHandlers(
     dbService,
     queryExecutor
   );
+  const projectHandlers = new ProjectHandlers(rpc, logger);
 
   // ==========================================
   // SESSION MANAGEMENT HANDLERS
@@ -168,6 +170,52 @@ export function registerDbHandlers(
     statsHandlers.handleGetTotalStats(p, id)
   );
 
+  // ==========================================
+  // PROJECT HANDLERS
+  // ==========================================
+  rpcRegister("project.list", (p, id) =>
+    projectHandlers.handleListProjects(p, id)
+  );
+  rpcRegister("project.get", (p, id) =>
+    projectHandlers.handleGetProject(p, id)
+  );
+  rpcRegister("project.create", (p, id) =>
+    projectHandlers.handleCreateProject(p, id)
+  );
+  rpcRegister("project.update", (p, id) =>
+    projectHandlers.handleUpdateProject(p, id)
+  );
+  rpcRegister("project.delete", (p, id) =>
+    projectHandlers.handleDeleteProject(p, id)
+  );
+  rpcRegister("project.getSchema", (p, id) =>
+    projectHandlers.handleGetSchema(p, id)
+  );
+  rpcRegister("project.saveSchema", (p, id) =>
+    projectHandlers.handleSaveSchema(p, id)
+  );
+  rpcRegister("project.getERDiagram", (p, id) =>
+    projectHandlers.handleGetERDiagram(p, id)
+  );
+  rpcRegister("project.saveERDiagram", (p, id) =>
+    projectHandlers.handleSaveERDiagram(p, id)
+  );
+  rpcRegister("project.getQueries", (p, id) =>
+    projectHandlers.handleGetQueries(p, id)
+  );
+  rpcRegister("project.addQuery", (p, id) =>
+    projectHandlers.handleAddQuery(p, id)
+  );
+  rpcRegister("project.updateQuery", (p, id) =>
+    projectHandlers.handleUpdateQuery(p, id)
+  );
+  rpcRegister("project.deleteQuery", (p, id) =>
+    projectHandlers.handleDeleteQuery(p, id)
+  );
+  rpcRegister("project.export", (p, id) =>
+    projectHandlers.handleExportProject(p, id)
+  );
+
   // ==========================================
   // DATABASE DISCOVERY HANDLERS
   // ==========================================
diff --git a/bridge/src/services/dbStore.ts b/bridge/src/services/dbStore.ts
index b65757d..e452361 100644
--- a/bridge/src/services/dbStore.ts
+++ b/bridge/src/services/dbStore.ts
@@ -9,34 +9,9 @@ import fsSync from "fs";
 import { v4 as uuidv4 } from "uuid";
 import { createCipheriv, createDecipheriv, randomBytes, scrypt } from "crypto";
 import { promisify } from "util";
-
+import { CONFIG_FOLDER, CONFIG_FILE, CREDENTIALS_FILE } from "../utils/config";
 const scryptAsync = promisify(scrypt);
 
-export const CONFIG_FOLDER =
-  process.env.RELWAVE_HOME ||
-  path.join(
-    os.homedir(),
-    process.platform === "win32"
-      ? "AppData\\Roaming\\relwave"
-      : ".relwave"
-  );
-
-export const CONFIG_FILE = path.join(CONFIG_FOLDER, "databases.json");
-export const CREDENTIALS_FILE = path.join(CONFIG_FOLDER, ".credentials");
-
-export function getConnectionDir(connectionId: string) {
-  return path.join(CONFIG_FOLDER, "connections", connectionId);
-}
-
-export function getMigrationsDir(connectionId: string) {
-  return path.join(CONFIG_FOLDER, "migrations", connectionId);
-}
-
-export function ensureDir(dir: string) {
-  if (!fsSync.existsSync(dir)) {
-    fsSync.mkdirSync(dir, { recursive: true });
-  }
-}
 
 
 // Use machine-specific key for encryption
diff --git a/bridge/src/services/projectStore.ts b/bridge/src/services/projectStore.ts
new file mode 100644
index 0000000..43ece1c
--- /dev/null
+++ b/bridge/src/services/projectStore.ts
@@ -0,0 +1,486 @@
+// ----------------------------
+// services/projectStore.ts
+// ----------------------------
+
+import path from "path";
+import fs from "fs/promises";
+import fsSync from "fs";
+import { v4 as uuidv4 } from "uuid";
+import {
+    PROJECTS_FOLDER,
+    PROJECTS_INDEX_FILE,
+    getProjectDir,
+    ensureDir,
+} from "../utils/config";
+import { dbStoreInstance, DBMeta } from "./dbStore";
+
+// ==========================================
+// Types
+// ==========================================
+
+export type ProjectMetadata = {
+    version: number;
+    id: string;
+    databaseId: string;
+    name: string;
+    description?: string;
+    engine?: string;
+    defaultSchema?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+export type SavedQuery = {
+    id: string;
+    name: string;
+    sql: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+export type QueriesFile = {
+    version: number;
+    projectId: string;
+    queries: SavedQuery[];
+};
+
+export type ERNode = {
+    tableId: string;
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    collapsed?: boolean;
+};
+
+export type ERDiagramFile = {
+    version: number;
+    projectId: string;
+    nodes: ERNode[];
+    zoom?: number;
+    panX?: number;
+    panY?: number;
+    updatedAt: string;
+};
+
+export type SchemaFile = {
+    version: number;
+    projectId: string;
+    databaseId: string;
+    schemas: SchemaSnapshot[];
+    cachedAt: string;
+};
+
+export type SchemaSnapshot = {
+    name: string;
+    tables: TableSnapshot[];
+};
+
+export type TableSnapshot = {
+    name: string;
+    type: string;
+    columns: ColumnSnapshot[];
+};
+
+export type ColumnSnapshot = {
+    name: string;
+    type: string;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+    isForeignKey: boolean;
+    defaultValue: string | null;
+    isUnique: boolean;
+};
+
+export type ProjectSummary = Pick<
+    ProjectMetadata,
+    "id" | "name" | "description" | "engine" | "databaseId" | "createdAt" | "updatedAt"
+>;
+
+
+
+type ProjectIndex = {
+    version: number;
+    projects: ProjectSummary[];
+};
+
+
+const PROJECT_FILES = {
+    metadata: "relwave.json",
+    schema: path.join("schema", "schema.json"),
+    erDiagram: path.join("diagrams", "er.json"),
+    queries: path.join("queries", "queries.json"),
+} as const;
+
+export class ProjectStore {
+    private projectsFolder: string;
+    private indexFile: string;
+
+    constructor(
+        projectsFolder: string = PROJECTS_FOLDER,
+        indexFile: string = PROJECTS_INDEX_FILE
+    ) {
+        this.projectsFolder = projectsFolder;
+        this.indexFile = indexFile;
+    }
+
+    private projectDir(projectId: string): string {
+        return getProjectDir(projectId);
+    }
+
+    private projectFile(projectId: string, file: string): string {
+        return path.join(this.projectDir(projectId), file);
+    }
+
+    /**
+     * Ensure the project directory and sub-folders exist
+     */
+    private async ensureProjectDirs(projectId: string): Promise<void> {
+        const base = this.projectDir(projectId);
+        ensureDir(base);
+        ensureDir(path.join(base, "schema"));
+        ensureDir(path.join(base, "diagrams"));
+        ensureDir(path.join(base, "queries"));
+    }
+
+    /**
+     * Read and parse a JSON file, returns null if missing
+     */
+    private async readJSON<T>(filePath: string): Promise<T | null> {
+        try {
+            if (!fsSync.existsSync(filePath)) return null;
+            const raw = await fs.readFile(filePath, "utf-8");
+            return JSON.parse(raw) as T;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Write JSON atomically (write to tmp then rename)
+     */
+    private async writeJSON(filePath: string, data: unknown): Promise<void> {
+        const dir = path.dirname(filePath);
+        ensureDir(dir);
+        const tmp = filePath + ".tmp";
+        await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+        await fs.rename(tmp, filePath);
+    }
+
+    private async loadIndex(): Promise<ProjectIndex> {
+        const data = await this.readJSON<ProjectIndex>(this.indexFile);
+        return data ?? { version: 1, projects: [] };
+    }
+
+    private async saveIndex(index: ProjectIndex): Promise<void> {
+        ensureDir(this.projectsFolder);
+        await this.writeJSON(this.indexFile, index);
+    }
+
+
+    /**
+     * List all projects (lightweight, from index)
+     */
+    async listProjects(): Promise<ProjectSummary[]> {
+        const index = await this.loadIndex();
+        return index.projects;
+    }
+
+    /**
+     * Get full project metadata
+     */
+    async getProject(projectId: string): Promise<ProjectMetadata | null> {
+        return this.readJSON<ProjectMetadata>(
+            this.projectFile(projectId, PROJECT_FILES.metadata)
+        );
+    }
+
+    /**
+     * Create a new project linked to a database connection
+     */
+    async createProject(params: {
+        databaseId: string;
+        name: string;
+        description?: string;
+        defaultSchema?: string;
+    }): Promise<ProjectMetadata> {
+        // Resolve engine from the linked database
+        let engine: string | undefined;
+        try {
+            const db: DBMeta | null = await dbStoreInstance.getDB(params.databaseId);
+            engine = db?.type;
+        } catch {
+            // db may not exist yet — that's OK
+        }
+
+        const id = uuidv4();
+        const now = new Date().toISOString();
+
+        const meta: ProjectMetadata = {
+            version: 1,
+            id,
+            databaseId: params.databaseId,
+            name: params.name,
+            description: params.description,
+            engine,
+            defaultSchema: params.defaultSchema,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        // Create project directory structure
+        await this.ensureProjectDirs(id);
+
+        // Write metadata
+        await this.writeJSON(
+            this.projectFile(id, PROJECT_FILES.metadata),
+            meta
+        );
+
+        // Initialise empty sub-files
+        const emptySchema: SchemaFile = {
+            version: 1,
+            projectId: id,
+            databaseId: params.databaseId,
+            schemas: [],
+            cachedAt: now,
+        };
+        const emptyER: ERDiagramFile = {
+            version: 1,
+            projectId: id,
+            nodes: [],
+            updatedAt: now,
+        };
+        const emptyQueries: QueriesFile = {
+            version: 1,
+            projectId: id,
+            queries: [],
+        };
+
+        await Promise.all([
+            this.writeJSON(this.projectFile(id, PROJECT_FILES.schema), emptySchema),
+            this.writeJSON(this.projectFile(id, PROJECT_FILES.erDiagram), emptyER),
+            this.writeJSON(this.projectFile(id, PROJECT_FILES.queries), emptyQueries),
+        ]);
+
+        // Update global index
+        const index = await this.loadIndex();
+        index.projects.push({
+            id,
+            name: meta.name,
+            description: meta.description,
+            engine,
+            databaseId: meta.databaseId,
+            createdAt: now,
+            updatedAt: now,
+        });
+        await this.saveIndex(index);
+
+        return meta;
+    }
+
+    /**
+     * Update project metadata (name, description, defaultSchema)
+     */
+    async updateProject(
+        projectId: string,
+        updates: Partial<Pick<ProjectMetadata, "name" | "description" | "defaultSchema">>
+    ): Promise<ProjectMetadata | null> {
+        const meta = await this.getProject(projectId);
+        if (!meta) return null;
+
+        const now = new Date().toISOString();
+        const updated: ProjectMetadata = {
+            ...meta,
+            ...updates,
+            updatedAt: now,
+        };
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.metadata),
+            updated
+        );
+
+        // Sync the index entry
+        const index = await this.loadIndex();
+        const entry = index.projects.find((p) => p.id === projectId);
+        if (entry) {
+            if (updates.name !== undefined) entry.name = updates.name;
+            if (updates.description !== undefined) entry.description = updates.description;
+            entry.updatedAt = now;
+            await this.saveIndex(index);
+        }
+
+        return updated;
+    }
+
+    /**
+     * Delete a project and its directory
+     */
+    async deleteProject(projectId: string): Promise<void> {
+        const dir = this.projectDir(projectId);
+        if (fsSync.existsSync(dir)) {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+
+        // Remove from index
+        const index = await this.loadIndex();
+        index.projects = index.projects.filter((p) => p.id !== projectId);
+        await this.saveIndex(index);
+    }
+
+    async getSchema(projectId: string): Promise<SchemaFile | null> {
+        return this.readJSON<SchemaFile>(
+            this.projectFile(projectId, PROJECT_FILES.schema)
+        );
+    }
+
+    async saveSchema(projectId: string, schemas: SchemaSnapshot[]): Promise<SchemaFile> {
+        const meta = await this.getProject(projectId);
+        if (!meta) throw new Error(`Project ${projectId} not found`);
+
+        const now = new Date().toISOString();
+        const file: SchemaFile = {
+            version: 1,
+            projectId,
+            databaseId: meta.databaseId,
+            schemas,
+            cachedAt: now,
+        };
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.schema),
+            file
+        );
+
+        return file;
+    }
+
+    async getERDiagram(projectId: string): Promise<ERDiagramFile | null> {
+        return this.readJSON<ERDiagramFile>(
+            this.projectFile(projectId, PROJECT_FILES.erDiagram)
+        );
+    }
+
+    async saveERDiagram(
+        projectId: string,
+        data: Pick<ERDiagramFile, "nodes" | "zoom" | "panX" | "panY">
+    ): Promise<ERDiagramFile> {
+        const now = new Date().toISOString();
+        const file: ERDiagramFile = {
+            version: 1,
+            projectId,
+            nodes: data.nodes,
+            zoom: data.zoom,
+            panX: data.panX,
+            panY: data.panY,
+            updatedAt: now,
+        };
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.erDiagram),
+            file
+        );
+
+        return file;
+    }
+
+    async getQueries(projectId: string): Promise<QueriesFile | null> {
+        return this.readJSON<QueriesFile>(
+            this.projectFile(projectId, PROJECT_FILES.queries)
+        );
+    }
+
+    async addQuery(
+        projectId: string,
+        params: { name: string; sql: string; description?: string }
+    ): Promise<SavedQuery> {
+        const file = (await this.getQueries(projectId)) ?? {
+            version: 1,
+            projectId,
+            queries: [],
+        };
+
+        const now = new Date().toISOString();
+        const query: SavedQuery = {
+            id: uuidv4(),
+            name: params.name,
+            sql: params.sql,
+            description: params.description,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        file.queries.push(query);
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.queries),
+            file
+        );
+
+        return query;
+    }
+
+    async updateQuery(
+        projectId: string,
+        queryId: string,
+        updates: Partial<Pick<SavedQuery, "name" | "sql" | "description">>
+    ): Promise<SavedQuery | null> {
+        const file = await this.getQueries(projectId);
+        if (!file) return null;
+
+        const idx = file.queries.findIndex((q) => q.id === queryId);
+        if (idx === -1) return null;
+
+        const now = new Date().toISOString();
+        file.queries[idx] = {
+            ...file.queries[idx],
+            ...updates,
+            updatedAt: now,
+        };
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.queries),
+            file
+        );
+
+        return file.queries[idx];
+    }
+
+    async deleteQuery(projectId: string, queryId: string): Promise<void> {
+        const file = await this.getQueries(projectId);
+        if (!file) return;
+
+        file.queries = file.queries.filter((q) => q.id !== queryId);
+
+        await this.writeJSON(
+            this.projectFile(projectId, PROJECT_FILES.queries),
+            file
+        );
+    }
+
+    /**
+     * Returns the full project bundle — useful for export / git commit
+     */
+    async exportProject(projectId: string): Promise<{
+        metadata: ProjectMetadata;
+        schema: SchemaFile | null;
+        erDiagram: ERDiagramFile | null;
+        queries: QueriesFile | null;
+    } | null> {
+        const metadata = await this.getProject(projectId);
+        if (!metadata) return null;
+
+        const [schema, erDiagram, queries] = await Promise.all([
+            this.getSchema(projectId),
+            this.getERDiagram(projectId),
+            this.getQueries(projectId),
+        ]);
+
+        return { metadata, schema, erDiagram, queries };
+    }
+}
+
+// Singleton instance
+export const projectStoreInstance = new ProjectStore();
\ No newline at end of file
diff --git a/bridge/src/utils/config.ts b/bridge/src/utils/config.ts
new file mode 100644
index 0000000..c1435ec
--- /dev/null
+++ b/bridge/src/utils/config.ts
@@ -0,0 +1,37 @@
+import path from "path";
+import os from "os";
+import fsSync from "fs";
+
+export const CONFIG_FOLDER =
+  process.env.RELWAVE_HOME ||
+  path.join(
+    os.homedir(),
+    process.platform === "win32"
+      ? "AppData\\Roaming\\relwave"
+      : ".relwave"
+  );
+
+export const CONFIG_FILE = path.join(CONFIG_FOLDER, "databases.json");
+export const CREDENTIALS_FILE = path.join(CONFIG_FOLDER, ".credentials");
+
+
+export const PROJECTS_FOLDER = path.join(CONFIG_FOLDER, "projects");
+export const PROJECTS_INDEX_FILE = path.join(PROJECTS_FOLDER, "index.json");
+
+export function getConnectionDir(connectionId: string) {
+  return path.join(CONFIG_FOLDER, "connections", connectionId);
+}
+
+export function getMigrationsDir(connectionId: string) {
+  return path.join(CONFIG_FOLDER, "migrations", connectionId);
+}
+
+export function getProjectDir(projectId: string) {
+  return path.join(PROJECTS_FOLDER, projectId);
+}
+
+export function ensureDir(dir: string) {
+  if (!fsSync.existsSync(dir)) {
+    fsSync.mkdirSync(dir, { recursive: true });
+  }
+}
\ No newline at end of file

From 6407a6c85a51ae6bc4cdbd9ef99c198e1e5b23ea Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Mon, 9 Feb 2026 18:00:36 +0530
Subject: [PATCH 2/9] feat: add project management features including project
 list, detail view, and deletion dialog

- Implemented ProjectList component for displaying and managing projects.
- Created ProjectDetailView component to show detailed information about a selected project.
- Added DeleteProjectDialog component for confirming project deletions.
- Integrated project-related hooks for querying, creating, updating, and deleting projects.
- Updated bridgeApi service to handle project-related API calls.
- Added new Project types to define project metadata, queries, and schemas.
- Created Projects page to manage projects with a sidebar and detail view.
- Enhanced routing to include a dedicated projects page.
---
 src/components/common/VerticalIconBar.tsx     |   3 +-
 .../project/CreateProjectDialog.tsx           | 172 ++++++++++++
 .../project/DeleteProjectDialog.tsx           |  48 ++++
 src/components/project/ProjectDetailView.tsx  | 204 ++++++++++++++
 src/components/project/ProjectList.tsx        | 160 +++++++++++
 src/components/project/index.ts               |   4 +
 src/hooks/useProjectQueries.ts                | 262 ++++++++++++++++++
 src/main.tsx                                  |   2 +
 src/pages/Projects.tsx                        | 219 +++++++++++++++
 src/services/bridgeApi.ts                     | 215 ++++++++++++++
 src/types/project.ts                          | 104 +++++++
 11 files changed, 1392 insertions(+), 1 deletion(-)
 create mode 100644 src/components/project/CreateProjectDialog.tsx
 create mode 100644 src/components/project/DeleteProjectDialog.tsx
 create mode 100644 src/components/project/ProjectDetailView.tsx
 create mode 100644 src/components/project/ProjectList.tsx
 create mode 100644 src/components/project/index.ts
 create mode 100644 src/hooks/useProjectQueries.ts
 create mode 100644 src/pages/Projects.tsx
 create mode 100644 src/types/project.ts

diff --git a/src/components/common/VerticalIconBar.tsx b/src/components/common/VerticalIconBar.tsx
index b77bc86..bd11cfe 100644
--- a/src/components/common/VerticalIconBar.tsx
+++ b/src/components/common/VerticalIconBar.tsx
@@ -1,4 +1,4 @@
-import { Home, Database, Search, GitBranch, Settings, Layers, Terminal } from 'lucide-react';
+import { Home, Database, Search, GitBranch, Settings, Layers, Terminal, FolderOpen } from 'lucide-react';
 import { Link, useLocation } from 'react-router-dom';
 import { Button } from '@/components/ui/button';
 import {
@@ -17,6 +17,7 @@ interface VerticalIconBarProps {
 
 const globalNavigationItems = [
     { icon: Home, label: 'Dashboard', path: '/' },
+    { icon: FolderOpen, label: 'Projects', path: '/projects' },
     { icon: Settings, label: 'Settings', path: '/settings' },
 ];
 
diff --git a/src/components/project/CreateProjectDialog.tsx b/src/components/project/CreateProjectDialog.tsx
new file mode 100644
index 0000000..c23b1b2
--- /dev/null
+++ b/src/components/project/CreateProjectDialog.tsx
@@ -0,0 +1,172 @@
+import { useState } from "react";
+import { Database, Link as LinkIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Textarea } from "@/components/ui/textarea";
+import { DatabaseConnection } from "@/types/database";
+
+interface CreateProjectDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSubmit: (data: {
+    databaseId: string;
+    name: string;
+    description?: string;
+    defaultSchema?: string;
+  }) => void;
+  isLoading?: boolean;
+  databases: DatabaseConnection[];
+}
+
+export function CreateProjectDialog({
+  open,
+  onOpenChange,
+  onSubmit,
+  isLoading,
+  databases,
+}: CreateProjectDialogProps) {
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [databaseId, setDatabaseId] = useState("");
+  const [defaultSchema, setDefaultSchema] = useState("");
+
+  const resetForm = () => {
+    setName("");
+    setDescription("");
+    setDatabaseId("");
+    setDefaultSchema("");
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!name.trim() || !databaseId) return;
+
+    onSubmit({
+      databaseId,
+      name: name.trim(),
+      description: description.trim() || undefined,
+      defaultSchema: defaultSchema.trim() || undefined,
+    });
+
+    resetForm();
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(isOpen) => {
+        onOpenChange(isOpen);
+        if (!isOpen) resetForm();
+      }}
+    >
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Database className="h-5 w-5 text-primary" />
+            Create Project
+          </DialogTitle>
+          <DialogDescription>
+            Create a project to save schema, ER diagrams, and queries offline.
+          </DialogDescription>
+        </DialogHeader>
+
+        <form onSubmit={handleSubmit} className="space-y-4 mt-2">
+          {/* Project Name */}
+          <div className="space-y-2">
+            <Label htmlFor="project-name">Project Name</Label>
+            <Input
+              id="project-name"
+              placeholder="My Project"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              autoFocus
+            />
+          </div>
+
+          {/* Linked Database */}
+          <div className="space-y-2">
+            <Label htmlFor="project-db">
+              <span className="flex items-center gap-1.5">
+                <LinkIcon className="h-3.5 w-3.5" />
+                Linked Database
+              </span>
+            </Label>
+            <Select value={databaseId} onValueChange={setDatabaseId}>
+              <SelectTrigger id="project-db">
+                <SelectValue placeholder="Select a database connection" />
+              </SelectTrigger>
+              <SelectContent>
+                {databases.map((db) => (
+                  <SelectItem key={db.id} value={db.id}>
+                    <span className="flex items-center gap-2">
+                      <Database className="h-3.5 w-3.5 text-muted-foreground" />
+                      {db.name}
+                      <span className="text-xs text-muted-foreground">
+                        ({db.type})
+                      </span>
+                    </span>
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          {/* Default Schema */}
+          <div className="space-y-2">
+            <Label htmlFor="project-schema">Default Schema (optional)</Label>
+            <Input
+              id="project-schema"
+              placeholder="public"
+              value={defaultSchema}
+              onChange={(e) => setDefaultSchema(e.target.value)}
+            />
+          </div>
+
+          {/* Description */}
+          <div className="space-y-2">
+            <Label htmlFor="project-desc">Description (optional)</Label>
+            <Textarea
+              id="project-desc"
+              placeholder="Brief description of this project..."
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              rows={2}
+            />
+          </div>
+
+          {/* Actions */}
+          <div className="flex justify-end gap-2 pt-2">
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => onOpenChange(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              type="submit"
+              disabled={!name.trim() || !databaseId || isLoading}
+            >
+              {isLoading ? "Creating..." : "Create Project"}
+            </Button>
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/components/project/DeleteProjectDialog.tsx b/src/components/project/DeleteProjectDialog.tsx
new file mode 100644
index 0000000..095f055
--- /dev/null
+++ b/src/components/project/DeleteProjectDialog.tsx
@@ -0,0 +1,48 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+
+interface DeleteProjectDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  projectName: string | undefined;
+  onConfirm: () => void;
+}
+
+export function DeleteProjectDialog({
+  open,
+  onOpenChange,
+  projectName,
+  onConfirm,
+}: DeleteProjectDialogProps) {
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Delete Project</AlertDialogTitle>
+          <AlertDialogDescription>
+            Are you sure you want to delete "{projectName}"? This will remove
+            all saved schema caches, ER diagram layouts, and saved queries. This
+            action cannot be undone.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction
+            onClick={onConfirm}
+            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+          >
+            Delete
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/src/components/project/ProjectDetailView.tsx b/src/components/project/ProjectDetailView.tsx
new file mode 100644
index 0000000..6d23764
--- /dev/null
+++ b/src/components/project/ProjectDetailView.tsx
@@ -0,0 +1,204 @@
+import {
+  Database,
+  Clock,
+  Layers,
+  GitBranch,
+  FileCode2,
+  ExternalLink,
+  MoreHorizontal,
+  Trash2,
+  Download,
+  FolderOpen,
+  Pencil,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+import { ProjectSummary } from "@/types/project";
+
+interface ProjectDetailViewProps {
+  project: ProjectSummary;
+  schemaCount?: number;
+  queryCount?: number;
+  hasERLayout?: boolean;
+  onOpen: () => void;
+  onDelete: () => void;
+  onExport: () => void;
+}
+
+function formatRelativeTime(dateStr: string) {
+  const diff = Date.now() - new Date(dateStr).getTime();
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  return new Date(dateStr).toLocaleDateString();
+}
+
+const ENGINE_COLORS: Record<string, { bg: string; text: string }> = {
+  postgres: { bg: "bg-blue-500/10", text: "text-blue-500" },
+  postgresql: { bg: "bg-blue-500/10", text: "text-blue-500" },
+  mysql: { bg: "bg-orange-500/10", text: "text-orange-500" },
+  mariadb: { bg: "bg-sky-500/10", text: "text-sky-500" },
+};
+
+export function ProjectDetailView({
+  project,
+  schemaCount,
+  queryCount,
+  hasERLayout,
+  onOpen,
+  onDelete,
+  onExport,
+}: ProjectDetailViewProps) {
+  const colors =
+    ENGINE_COLORS[project.engine?.toLowerCase() ?? ""] ?? {
+      bg: "bg-primary/10",
+      text: "text-primary",
+    };
+
+  return (
+    <div className="h-full flex flex-col">
+      {/* Header */}
+      <div className="p-6 border-b border-border/50">
+        <div className="flex items-start justify-between">
+          <div className="flex items-center gap-4">
+            <div
+              className={cn(
+                "h-14 w-14 rounded-xl flex items-center justify-center",
+                colors.bg
+              )}
+            >
+              <FolderOpen className={cn("h-7 w-7", colors.text)} />
+            </div>
+            <div>
+              <div className="flex items-center gap-2">
+                <h2 className="text-xl font-semibold">{project.name}</h2>
+                {project.engine && (
+                  <span className="inline-flex items-center px-2 py-0.5 rounded-full text-[10px] font-medium bg-muted text-muted-foreground">
+                    {project.engine}
+                  </span>
+                )}
+              </div>
+              {project.description && (
+                <p className="text-sm text-muted-foreground mt-0.5">
+                  {project.description}
+                </p>
+              )}
+              <div className="flex items-center gap-3 mt-1.5 text-xs text-muted-foreground">
+                <span className="flex items-center gap-1">
+                  <Clock className="h-3 w-3" />
+                  Updated {formatRelativeTime(project.updatedAt)}
+                </span>
+              </div>
+            </div>
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            <Button size="sm" onClick={onOpen}>
+              <ExternalLink className="h-3.5 w-3.5 mr-1.5" />
+              Open
+            </Button>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button variant="ghost" size="icon" className="h-8 w-8">
+                  <MoreHorizontal className="h-4 w-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem onClick={onExport}>
+                  <Download className="h-3.5 w-3.5 mr-2" />
+                  Export Bundle
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  className="text-destructive"
+                  onClick={onDelete}
+                >
+                  <Trash2 className="h-3.5 w-3.5 mr-2" />
+                  Delete Project
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+      </div>
+
+      {/* Content cards */}
+      <div className="flex-1 overflow-y-auto p-6">
+        <h3 className="text-sm font-semibold mb-4">Project Data</h3>
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+          {/* Schema card */}
+          <div className="p-5 rounded-xl border border-border/50 bg-card hover:border-border transition-colors">
+            <div className="flex items-center gap-3 mb-3">
+              <div className="h-9 w-9 rounded-lg bg-violet-500/10 flex items-center justify-center">
+                <Layers className="h-4.5 w-4.5 text-violet-500" />
+              </div>
+              <h4 className="text-sm font-medium">Schema Cache</h4>
+            </div>
+            <p className="text-2xl font-bold tabular-nums font-mono">
+              {schemaCount ?? "—"}
+            </p>
+            <p className="text-xs text-muted-foreground mt-1">
+              Cached schemas
+            </p>
+          </div>
+
+          {/* ER Diagram card */}
+          <div className="p-5 rounded-xl border border-border/50 bg-card hover:border-border transition-colors">
+            <div className="flex items-center gap-3 mb-3">
+              <div className="h-9 w-9 rounded-lg bg-emerald-500/10 flex items-center justify-center">
+                <GitBranch className="h-4.5 w-4.5 text-emerald-500" />
+              </div>
+              <h4 className="text-sm font-medium">ER Diagram</h4>
+            </div>
+            <p className="text-2xl font-bold tabular-nums font-mono">
+              {hasERLayout ? "Saved" : "—"}
+            </p>
+            <p className="text-xs text-muted-foreground mt-1">
+              Diagram layout
+            </p>
+          </div>
+
+          {/* Queries card */}
+          <div className="p-5 rounded-xl border border-border/50 bg-card hover:border-border transition-colors">
+            <div className="flex items-center gap-3 mb-3">
+              <div className="h-9 w-9 rounded-lg bg-amber-500/10 flex items-center justify-center">
+                <FileCode2 className="h-4.5 w-4.5 text-amber-500" />
+              </div>
+              <h4 className="text-sm font-medium">Saved Queries</h4>
+            </div>
+            <p className="text-2xl font-bold tabular-nums font-mono">
+              {queryCount ?? "—"}
+            </p>
+            <p className="text-xs text-muted-foreground mt-1">
+              Stored queries
+            </p>
+          </div>
+        </div>
+
+        {/* Future: git-native section placeholder */}
+        <div className="mt-8 p-4 rounded-xl border border-dashed border-border/50 flex items-center gap-3">
+          <GitBranch className="h-5 w-5 text-muted-foreground/50" />
+          <div>
+            <p className="text-sm font-medium text-muted-foreground/70">
+              Git-native support coming soon
+            </p>
+            <p className="text-xs text-muted-foreground/50">
+              Version-control your project files, track schema changes, and
+              collaborate with your team.
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/project/ProjectList.tsx b/src/components/project/ProjectList.tsx
new file mode 100644
index 0000000..6fb6a00
--- /dev/null
+++ b/src/components/project/ProjectList.tsx
@@ -0,0 +1,160 @@
+import {
+  Plus,
+  FolderOpen,
+  Search,
+  Trash2,
+  Database,
+} from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuTrigger,
+} from "@/components/ui/context-menu";
+import { cn } from "@/lib/utils";
+import { ProjectSummary } from "@/types/project";
+
+interface ProjectListProps {
+  projects: ProjectSummary[];
+  filteredProjects: ProjectSummary[];
+  loading: boolean;
+  searchQuery: string;
+  setSearchQuery: (q: string) => void;
+  selectedProject: string | null;
+  setSelectedProject: (id: string | null) => void;
+  onCreateClick: () => void;
+  onDelete: (id: string, name: string) => void;
+  onOpen: (id: string) => void;
+}
+
+const ENGINE_COLORS: Record<string, string> = {
+  postgres: "text-blue-500",
+  postgresql: "text-blue-500",
+  mysql: "text-orange-500",
+  mariadb: "text-sky-500",
+};
+
+export function ProjectList({
+  projects,
+  filteredProjects,
+  loading,
+  searchQuery,
+  setSearchQuery,
+  selectedProject,
+  setSelectedProject,
+  onCreateClick,
+  onDelete,
+  onOpen,
+}: ProjectListProps) {
+  return (
+    <div className="w-72 border-r border-border/50 flex flex-col bg-muted/20">
+      {/* Header */}
+      <div className="p-4 border-b border-border/50">
+        <div className="flex items-center justify-between mb-3">
+          <h1 className="text-sm font-semibold">Projects</h1>
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-7 w-7"
+            onClick={onCreateClick}
+          >
+            <Plus className="h-4 w-4" />
+          </Button>
+        </div>
+        <div className="relative">
+          <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground/60" />
+          <Input
+            placeholder="Search projects..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="h-8 pl-8 text-xs bg-background/50"
+          />
+        </div>
+      </div>
+
+      {/* List */}
+      <div className="flex-1 overflow-y-auto py-2">
+        {loading ? (
+          <div className="flex items-center justify-center py-8">
+            <div className="h-5 w-5 border-2 border-primary/30 border-t-primary rounded-full animate-spin" />
+          </div>
+        ) : filteredProjects.length === 0 ? (
+          <div className="px-4 py-8 text-center">
+            <FolderOpen className="h-8 w-8 text-muted-foreground/30 mx-auto mb-2" />
+            <p className="text-xs text-muted-foreground">
+              {projects.length === 0
+                ? "No projects yet"
+                : "No matches found"}
+            </p>
+            {projects.length === 0 && (
+              <Button
+                variant="link"
+                size="sm"
+                className="mt-1 text-xs"
+                onClick={onCreateClick}
+              >
+                Create your first project
+              </Button>
+            )}
+          </div>
+        ) : (
+          <div className="space-y-0.5 px-2">
+            {filteredProjects.map((project) => {
+              const isSelected = selectedProject === project.id;
+              const engineColor =
+                ENGINE_COLORS[project.engine?.toLowerCase() ?? ""] ??
+                "text-muted-foreground";
+
+              return (
+                <ContextMenu key={project.id}>
+                  <ContextMenuTrigger asChild>
+                    <button
+                      onClick={() => setSelectedProject(project.id)}
+                      onDoubleClick={() => onOpen(project.id)}
+                      className={cn(
+                        "w-full flex items-center gap-2.5 px-2.5 py-2 rounded-md text-left transition-colors",
+                        isSelected
+                          ? "bg-accent text-accent-foreground"
+                          : "hover:bg-accent/50"
+                      )}
+                    >
+                      <Database className={cn("h-4 w-4 shrink-0", engineColor)} />
+                      <div className="flex-1 min-w-0">
+                        <p className="text-sm font-medium truncate">
+                          {project.name}
+                        </p>
+                        <p className="text-[10px] text-muted-foreground truncate">
+                          {project.engine ?? "—"}{" "}
+                          {project.description
+                            ? `• ${project.description}`
+                            : ""}
+                        </p>
+                      </div>
+                    </button>
+                  </ContextMenuTrigger>
+                  <ContextMenuContent>
+                    <ContextMenuItem onClick={() => onOpen(project.id)}>
+                      <FolderOpen className="h-3.5 w-3.5 mr-2" />
+                      Open Project
+                    </ContextMenuItem>
+                    <ContextMenuSeparator />
+                    <ContextMenuItem
+                      className="text-destructive"
+                      onClick={() => onDelete(project.id, project.name)}
+                    >
+                      <Trash2 className="h-3.5 w-3.5 mr-2" />
+                      Delete
+                    </ContextMenuItem>
+                  </ContextMenuContent>
+                </ContextMenu>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/project/index.ts b/src/components/project/index.ts
new file mode 100644
index 0000000..4cace25
--- /dev/null
+++ b/src/components/project/index.ts
@@ -0,0 +1,4 @@
+export { ProjectList } from "./ProjectList";
+export { CreateProjectDialog } from "./CreateProjectDialog";
+export { DeleteProjectDialog } from "./DeleteProjectDialog";
+export { ProjectDetailView } from "./ProjectDetailView";
diff --git a/src/hooks/useProjectQueries.ts b/src/hooks/useProjectQueries.ts
new file mode 100644
index 0000000..86df2d8
--- /dev/null
+++ b/src/hooks/useProjectQueries.ts
@@ -0,0 +1,262 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { bridgeApi } from "@/services/bridgeApi";
+import { isBridgeReady } from "@/services/bridgeClient";
+import {
+  CreateProjectParams,
+  UpdateProjectParams,
+  SchemaSnapshot,
+  ERNode,
+} from "@/types/project";
+
+// ============================================
+// Query Keys
+// ============================================
+export const projectKeys = {
+  all: ["projects"] as const,
+  detail: (id: string) => ["projects", id] as const,
+  schema: (id: string) => ["projects", id, "schema"] as const,
+  erDiagram: (id: string) => ["projects", id, "erDiagram"] as const,
+  queries: (id: string) => ["projects", id, "queries"] as const,
+  export: (id: string) => ["projects", id, "export"] as const,
+};
+
+// ============================================
+// Stale times
+// ============================================
+const STALE_TIMES = {
+  list: 5 * 60 * 1000,        // 5 min — project list rarely changes
+  detail: 5 * 60 * 1000,
+  schema: 10 * 60 * 1000,     // 10 min — cached schema
+  erDiagram: 10 * 60 * 1000,
+  queries: 2 * 60 * 1000,     // 2 min — queries update more often
+};
+
+// ============================================
+// List Projects
+// ============================================
+export function useProjects() {
+  const queryClient = useQueryClient();
+  const bridgeReady =
+    queryClient.getQueryData<boolean>(["bridge-ready"]) ?? isBridgeReady();
+
+  return useQuery({
+    queryKey: projectKeys.all,
+    queryFn: () => bridgeApi.listProjects(),
+    staleTime: STALE_TIMES.list,
+    gcTime: 10 * 60 * 1000,
+    enabled: bridgeReady,
+  });
+}
+
+// ============================================
+// Get Single Project
+// ============================================
+export function useProject(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.detail(projectId!),
+    queryFn: () => bridgeApi.getProject(projectId!),
+    staleTime: STALE_TIMES.detail,
+    enabled: !!projectId,
+  });
+}
+
+// ============================================
+// Create Project
+// ============================================
+export function useCreateProject() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (params: CreateProjectParams) => bridgeApi.createProject(params),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: projectKeys.all });
+    },
+  });
+}
+
+// ============================================
+// Update Project
+// ============================================
+export function useUpdateProject() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (params: UpdateProjectParams) => bridgeApi.updateProject(params),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({ queryKey: projectKeys.all });
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.detail(variables.id),
+      });
+    },
+  });
+}
+
+// ============================================
+// Delete Project
+// ============================================
+export function useDeleteProject() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (projectId: string) => bridgeApi.deleteProject(projectId),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: projectKeys.all });
+    },
+  });
+}
+
+// ============================================
+// Project Schema (cached offline data)
+// ============================================
+export function useProjectSchema(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.schema(projectId!),
+    queryFn: () => bridgeApi.getProjectSchema(projectId!),
+    staleTime: STALE_TIMES.schema,
+    enabled: !!projectId,
+  });
+}
+
+export function useSaveProjectSchema() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      projectId,
+      schemas,
+    }: {
+      projectId: string;
+      schemas: SchemaSnapshot[];
+    }) => bridgeApi.saveProjectSchema(projectId, schemas),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.schema(variables.projectId),
+      });
+    },
+  });
+}
+
+// ============================================
+// ER Diagram
+// ============================================
+export function useProjectERDiagram(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.erDiagram(projectId!),
+    queryFn: () => bridgeApi.getProjectERDiagram(projectId!),
+    staleTime: STALE_TIMES.erDiagram,
+    enabled: !!projectId,
+  });
+}
+
+export function useSaveProjectERDiagram() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      projectId,
+      nodes,
+      zoom,
+      panX,
+      panY,
+    }: {
+      projectId: string;
+      nodes: ERNode[];
+      zoom?: number;
+      panX?: number;
+      panY?: number;
+    }) => bridgeApi.saveProjectERDiagram(projectId, { nodes, zoom, panX, panY }),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.erDiagram(variables.projectId),
+      });
+    },
+  });
+}
+
+// ============================================
+// Saved Queries
+// ============================================
+export function useProjectQueries(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.queries(projectId!),
+    queryFn: () => bridgeApi.getProjectQueries(projectId!),
+    staleTime: STALE_TIMES.queries,
+    enabled: !!projectId,
+  });
+}
+
+export function useAddProjectQuery() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      projectId,
+      name,
+      sql,
+      description,
+    }: {
+      projectId: string;
+      name: string;
+      sql: string;
+      description?: string;
+    }) => bridgeApi.addProjectQuery(projectId, { name, sql, description }),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.queries(variables.projectId),
+      });
+    },
+  });
+}
+
+export function useUpdateProjectQuery() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      projectId,
+      queryId,
+      ...updates
+    }: {
+      projectId: string;
+      queryId: string;
+      name?: string;
+      sql?: string;
+      description?: string;
+    }) => bridgeApi.updateProjectQuery(projectId, queryId, updates),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.queries(variables.projectId),
+      });
+    },
+  });
+}
+
+export function useDeleteProjectQuery() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      projectId,
+      queryId,
+    }: {
+      projectId: string;
+      queryId: string;
+    }) => bridgeApi.deleteProjectQuery(projectId, queryId),
+    onSuccess: (_data, variables) => {
+      queryClient.invalidateQueries({
+        queryKey: projectKeys.queries(variables.projectId),
+      });
+    },
+  });
+}
+
+// ============================================
+// Export
+// ============================================
+export function useExportProject(projectId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.export(projectId!),
+    queryFn: () => bridgeApi.exportProject(projectId!),
+    enabled: false, // Manual trigger only
+  });
+}
diff --git a/src/main.tsx b/src/main.tsx
index b43ff90..cfc47e4 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -5,6 +5,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { BrowserRouter, Routes, Route } from "react-router-dom";
 import Index from "./pages/Index";
 import DatabaseDetail from './pages/DatabaseDetails';
+import Projects from './pages/Projects';
 import NotFound from './pages/NotFound';
 import { ThemeProvider } from './components/common/ThemeProvider';
 import Settings from './pages/Settings';
@@ -51,6 +52,7 @@ function AppRoot() {
               <BrowserRouter>
                 <Routes>
                   <Route path="/" element={<Index />} />
+                  <Route path="/projects" element={<Projects />} />
                   <Route path="/:id" element={<DatabaseDetail />} />
                   <Route path="/settings" element={<Settings />} />
                   <Route path="*" element={<NotFound />} />
diff --git a/src/pages/Projects.tsx b/src/pages/Projects.tsx
new file mode 100644
index 0000000..c380293
--- /dev/null
+++ b/src/pages/Projects.tsx
@@ -0,0 +1,219 @@
+import { useState, useMemo } from "react";
+import { toast } from "sonner";
+import { useNavigate } from "react-router-dom";
+import { useBridgeQuery } from "@/hooks/useBridgeQuery";
+import { useDatabases } from "@/hooks/useDbQueries";
+import {
+  useProjects,
+  useCreateProject,
+  useDeleteProject,
+  useProjectSchema,
+  useProjectERDiagram,
+  useProjectQueries,
+} from "@/hooks/useProjectQueries";
+import { bridgeApi } from "@/services/bridgeApi";
+import BridgeLoader from "@/components/feedback/BridgeLoader";
+import BridgeFailed from "@/components/feedback/BridgeFailed";
+import VerticalIconBar from "@/components/common/VerticalIconBar";
+import {
+  ProjectList,
+  CreateProjectDialog,
+  DeleteProjectDialog,
+  ProjectDetailView,
+} from "@/components/project";
+import { FolderOpen, Sparkles } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+const Projects = () => {
+  const navigate = useNavigate();
+  const { data: bridgeReady, isLoading: bridgeLoading } = useBridgeQuery();
+
+  // Data queries
+  const { data: projects = [], isLoading: projectsLoading } = useProjects();
+  const { data: databases = [] } = useDatabases();
+
+  // Mutations
+  const createProjectMutation = useCreateProject();
+  const deleteProjectMutation = useDeleteProject();
+
+  // Local state
+  const [searchQuery, setSearchQuery] = useState("");
+  const [selectedProject, setSelectedProject] = useState<string | null>(null);
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
+  const [projectToDelete, setProjectToDelete] = useState<{
+    id: string;
+    name: string;
+  } | null>(null);
+
+  // Sub-resource queries for the selected project
+  const { data: schemaData } = useProjectSchema(selectedProject ?? undefined);
+  const { data: erData } = useProjectERDiagram(selectedProject ?? undefined);
+  const { data: queriesData } = useProjectQueries(selectedProject ?? undefined);
+
+  // Filtering
+  const filteredProjects = useMemo(
+    () =>
+      projects.filter(
+        (p) =>
+          p.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
+          (p.description ?? "").toLowerCase().includes(searchQuery.toLowerCase())
+      ),
+    [projects, searchQuery]
+  );
+
+  const selectedProjectData = useMemo(
+    () => projects.find((p) => p.id === selectedProject) ?? null,
+    [projects, selectedProject]
+  );
+
+  // ---- Handlers ----
+
+  const handleCreate = async (data: {
+    databaseId: string;
+    name: string;
+    description?: string;
+    defaultSchema?: string;
+  }) => {
+    try {
+      const created = await createProjectMutation.mutateAsync(data);
+      toast.success("Project created", { description: created.name });
+      setIsCreateOpen(false);
+      setSelectedProject(created.id);
+    } catch (err: any) {
+      toast.error("Failed to create project", { description: err.message });
+    }
+  };
+
+  const handleDelete = async () => {
+    if (!projectToDelete) return;
+    try {
+      await deleteProjectMutation.mutateAsync(projectToDelete.id);
+      toast.success("Project deleted");
+      setDeleteDialogOpen(false);
+      setProjectToDelete(null);
+      if (selectedProject === projectToDelete.id) setSelectedProject(null);
+    } catch (err: any) {
+      toast.error("Failed to delete", { description: err.message });
+    }
+  };
+
+  const handleExport = async (projectId: string) => {
+    try {
+      const bundle = await bridgeApi.exportProject(projectId);
+      if (!bundle) {
+        toast.error("Project not found");
+        return;
+      }
+      // Download as JSON file
+      const blob = new Blob([JSON.stringify(bundle, null, 2)], {
+        type: "application/json",
+      });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = `${bundle.metadata.name.replace(/\s+/g, "-").toLowerCase()}-export.json`;
+      a.click();
+      URL.revokeObjectURL(url);
+      toast.success("Project exported");
+    } catch (err: any) {
+      toast.error("Export failed", { description: err.message });
+    }
+  };
+
+  const handleOpen = (projectId: string) => {
+    const project = projects.find((p) => p.id === projectId);
+    if (project) {
+      // Navigate to the linked database detail page
+      navigate(`/${project.databaseId}`);
+    }
+  };
+
+  // ---- Loading / Error states ----
+  if (bridgeLoading || bridgeReady === undefined) return <BridgeLoader />;
+  if (!bridgeReady) return <BridgeFailed />;
+
+  return (
+    <div className="h-[calc(100vh-32px)] flex bg-background text-foreground overflow-hidden">
+      <VerticalIconBar />
+      <main className="flex-1 ml-[60px] flex">
+        {/* Left panel */}
+        <ProjectList
+          projects={projects}
+          filteredProjects={filteredProjects}
+          loading={projectsLoading}
+          searchQuery={searchQuery}
+          setSearchQuery={setSearchQuery}
+          selectedProject={selectedProject}
+          setSelectedProject={setSelectedProject}
+          onCreateClick={() => setIsCreateOpen(true)}
+          onDelete={(id: string, name: string) => {
+            setProjectToDelete({ id, name });
+            setDeleteDialogOpen(true);
+          }}
+          onOpen={handleOpen}
+        />
+
+        {/* Right panel */}
+        <div className="flex-1 overflow-y-auto">
+          {selectedProjectData ? (
+            <ProjectDetailView
+              project={selectedProjectData}
+              schemaCount={schemaData?.schemas?.length}
+              queryCount={queriesData?.queries?.length}
+              hasERLayout={(erData?.nodes?.length ?? 0) > 0}
+              onOpen={() => handleOpen(selectedProjectData.id)}
+              onDelete={() => {
+                setProjectToDelete({
+                  id: selectedProjectData.id,
+                  name: selectedProjectData.name,
+                });
+                setDeleteDialogOpen(true);
+              }}
+              onExport={() => handleExport(selectedProjectData.id)}
+            />
+          ) : (
+            /* Empty state */
+            <div className="h-full flex flex-col items-center justify-center p-6">
+              <div className="flex items-center gap-3 mb-4">
+                <div className="h-10 w-10 rounded-xl bg-primary/10 flex items-center justify-center">
+                  <FolderOpen className="h-5 w-5 text-primary" />
+                </div>
+                <div>
+                  <h1 className="text-xl font-semibold">Projects</h1>
+                  <p className="text-sm text-muted-foreground">
+                    Save database details, ER diagrams &amp; queries offline
+                  </p>
+                </div>
+              </div>
+              {projects.length === 0 && (
+                <Button onClick={() => setIsCreateOpen(true)} className="mt-4">
+                  <Sparkles className="h-4 w-4 mr-2" />
+                  Create Your First Project
+                </Button>
+              )}
+            </div>
+          )}
+        </div>
+      </main>
+
+      {/* Dialogs */}
+      <CreateProjectDialog
+        open={isCreateOpen}
+        onOpenChange={setIsCreateOpen}
+        onSubmit={handleCreate}
+        isLoading={createProjectMutation.isPending}
+        databases={databases}
+      />
+
+      <DeleteProjectDialog
+        open={deleteDialogOpen}
+        onOpenChange={setDeleteDialogOpen}
+        projectName={projectToDelete?.name}
+        onConfirm={handleDelete}
+      />
+    </div>
+  );
+};
+
+export default Projects;
diff --git a/src/services/bridgeApi.ts b/src/services/bridgeApi.ts
index a0eefe1..a21996b 100644
--- a/src/services/bridgeApi.ts
+++ b/src/services/bridgeApi.ts
@@ -1,4 +1,5 @@
 import { AddDatabaseParams, ConnectionTestResult, CreateTableColumn, DatabaseConnection, DatabaseSchemaDetails, DatabaseStats, DiscoveredDatabase, RunQueryParams, TableRow, UpdateDatabaseParams } from "@/types/database";
+import { ProjectSummary, ProjectMetadata, CreateProjectParams, UpdateProjectParams, SchemaFile, SchemaSnapshot, ERDiagramFile, ERNode, QueriesFile, SavedQuery, ProjectExport } from "@/types/project";
 import { bridgeRequest } from "./bridgeClient";
 
 
@@ -793,6 +794,220 @@ class BridgeApiService {
       return []; // Return empty array on error, don't throw
     }
   }
+
+  // ------------------------------------
+  // 6. PROJECT METHODS (project.*)
+  // ------------------------------------
+
+  /**
+   * List all projects
+   */
+  async listProjects(): Promise<ProjectSummary[]> {
+    try {
+      const result = await bridgeRequest("project.list", {});
+      return result?.data || [];
+    } catch (error: any) {
+      console.error("Failed to list projects:", error);
+      throw new Error(`Failed to list projects: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get a single project by ID
+   */
+  async getProject(projectId: string): Promise<ProjectMetadata | null> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.get", { id: projectId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to get project:", error);
+      throw new Error(`Failed to get project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create a new project linked to a database connection
+   */
+  async createProject(params: CreateProjectParams): Promise<ProjectMetadata> {
+    try {
+      if (!params.databaseId || !params.name) {
+        throw new Error("databaseId and name are required");
+      }
+      const result = await bridgeRequest("project.create", params);
+      if (!result?.data) throw new Error("Failed to create project");
+      return result.data;
+    } catch (error: any) {
+      console.error("Failed to create project:", error);
+      throw new Error(`Failed to create project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Update a project's metadata
+   */
+  async updateProject(params: UpdateProjectParams): Promise<ProjectMetadata> {
+    try {
+      if (!params.id) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.update", params);
+      if (!result?.data) throw new Error("Project not found");
+      return result.data;
+    } catch (error: any) {
+      console.error("Failed to update project:", error);
+      throw new Error(`Failed to update project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a project and all its files
+   */
+  async deleteProject(projectId: string): Promise<void> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      await bridgeRequest("project.delete", { id: projectId });
+    } catch (error: any) {
+      console.error("Failed to delete project:", error);
+      throw new Error(`Failed to delete project: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get cached schema for a project
+   */
+  async getProjectSchema(projectId: string): Promise<SchemaFile | null> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.getSchema", { projectId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to get project schema:", error);
+      throw new Error(`Failed to get project schema: ${error.message}`);
+    }
+  }
+
+  /**
+   * Save/cache schema data for a project
+   */
+  async saveProjectSchema(projectId: string, schemas: SchemaSnapshot[]): Promise<SchemaFile> {
+    try {
+      if (!projectId || !schemas) throw new Error("projectId and schemas are required");
+      const result = await bridgeRequest("project.saveSchema", { projectId, schemas });
+      return result?.data;
+    } catch (error: any) {
+      console.error("Failed to save project schema:", error);
+      throw new Error(`Failed to save project schema: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get ER diagram layout for a project
+   */
+  async getProjectERDiagram(projectId: string): Promise<ERDiagramFile | null> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.getERDiagram", { projectId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to get ER diagram:", error);
+      throw new Error(`Failed to get ER diagram: ${error.message}`);
+    }
+  }
+
+  /**
+   * Save ER diagram layout for a project
+   */
+  async saveProjectERDiagram(
+    projectId: string,
+    data: { nodes: ERNode[]; zoom?: number; panX?: number; panY?: number }
+  ): Promise<ERDiagramFile> {
+    try {
+      if (!projectId || !data.nodes) throw new Error("projectId and nodes are required");
+      const result = await bridgeRequest("project.saveERDiagram", { projectId, ...data });
+      return result?.data;
+    } catch (error: any) {
+      console.error("Failed to save ER diagram:", error);
+      throw new Error(`Failed to save ER diagram: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get saved queries for a project
+   */
+  async getProjectQueries(projectId: string): Promise<QueriesFile | null> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.getQueries", { projectId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to get project queries:", error);
+      throw new Error(`Failed to get project queries: ${error.message}`);
+    }
+  }
+
+  /**
+   * Add a saved query to a project
+   */
+  async addProjectQuery(
+    projectId: string,
+    params: { name: string; sql: string; description?: string }
+  ): Promise<SavedQuery> {
+    try {
+      if (!projectId || !params.name || !params.sql) {
+        throw new Error("projectId, name, and sql are required");
+      }
+      const result = await bridgeRequest("project.addQuery", { projectId, ...params });
+      return result?.data;
+    } catch (error: any) {
+      console.error("Failed to add project query:", error);
+      throw new Error(`Failed to add project query: ${error.message}`);
+    }
+  }
+
+  /**
+   * Update a saved query in a project
+   */
+  async updateProjectQuery(
+    projectId: string,
+    queryId: string,
+    updates: { name?: string; sql?: string; description?: string }
+  ): Promise<SavedQuery> {
+    try {
+      if (!projectId || !queryId) throw new Error("projectId and queryId are required");
+      const result = await bridgeRequest("project.updateQuery", { projectId, queryId, ...updates });
+      if (!result?.data) throw new Error("Query not found");
+      return result.data;
+    } catch (error: any) {
+      console.error("Failed to update project query:", error);
+      throw new Error(`Failed to update project query: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a saved query from a project
+   */
+  async deleteProjectQuery(projectId: string, queryId: string): Promise<void> {
+    try {
+      if (!projectId || !queryId) throw new Error("projectId and queryId are required");
+      await bridgeRequest("project.deleteQuery", { projectId, queryId });
+    } catch (error: any) {
+      console.error("Failed to delete project query:", error);
+      throw new Error(`Failed to delete project query: ${error.message}`);
+    }
+  }
+
+  /**
+   * Export full project bundle (metadata + schema + ER + queries)
+   */
+  async exportProject(projectId: string): Promise<ProjectExport | null> {
+    try {
+      if (!projectId) throw new Error("Project ID is required");
+      const result = await bridgeRequest("project.export", { projectId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to export project:", error);
+      throw new Error(`Failed to export project: ${error.message}`);
+    }
+  }
 }
 
 // Export singleton instance
diff --git a/src/types/project.ts b/src/types/project.ts
new file mode 100644
index 0000000..4b2e268
--- /dev/null
+++ b/src/types/project.ts
@@ -0,0 +1,104 @@
+// ==========================================
+// Project Types — mirrors bridge ProjectStore types
+// ==========================================
+
+export interface ProjectMetadata {
+  version: number;
+  id: string;
+  databaseId: string;
+  name: string;
+  description?: string;
+  engine?: string;
+  defaultSchema?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type ProjectSummary = Pick<
+  ProjectMetadata,
+  "id" | "name" | "description" | "engine" | "databaseId" | "createdAt" | "updatedAt"
+>;
+
+export interface SavedQuery {
+  id: string;
+  name: string;
+  sql: string;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface QueriesFile {
+  version: number;
+  projectId: string;
+  queries: SavedQuery[];
+}
+
+export interface ERNode {
+  tableId: string;
+  x: number;
+  y: number;
+  width?: number;
+  height?: number;
+  collapsed?: boolean;
+}
+
+export interface ERDiagramFile {
+  version: number;
+  projectId: string;
+  nodes: ERNode[];
+  zoom?: number;
+  panX?: number;
+  panY?: number;
+  updatedAt: string;
+}
+
+export interface SchemaSnapshot {
+  name: string;
+  tables: TableSnapshot[];
+}
+
+export interface TableSnapshot {
+  name: string;
+  type: string;
+  columns: ColumnSnapshot[];
+}
+
+export interface ColumnSnapshot {
+  name: string;
+  type: string;
+  nullable: boolean;
+  isPrimaryKey: boolean;
+  isForeignKey: boolean;
+  defaultValue: string | null;
+  isUnique: boolean;
+}
+
+export interface SchemaFile {
+  version: number;
+  projectId: string;
+  databaseId: string;
+  schemas: SchemaSnapshot[];
+  cachedAt: string;
+}
+
+export interface CreateProjectParams {
+  databaseId: string;
+  name: string;
+  description?: string;
+  defaultSchema?: string;
+}
+
+export interface UpdateProjectParams {
+  id: string;
+  name?: string;
+  description?: string;
+  defaultSchema?: string;
+}
+
+export interface ProjectExport {
+  metadata: ProjectMetadata;
+  schema: SchemaFile | null;
+  erDiagram: ERDiagramFile | null;
+  queries: QueriesFile | null;
+}

From e7ea0d4a42d38ce3cfa613093fa3dda4bec2a31d Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Mon, 9 Feb 2026 18:07:40 +0530
Subject: [PATCH 3/9] feat: implement project retrieval by database ID and
 auto-sync schema data

---
 bridge/src/handlers/projectHandlers.ts        |  19 +
 bridge/src/jsonRpcHandler.ts                  |   3 +
 bridge/src/services/projectStore.ts           |  11 +
 .../er-diagram/ERDiagramContent.tsx           |  57 ++-
 src/components/er-diagram/ERDiagramPanel.tsx  |   8 +-
 src/hooks/useProjectQueries.ts                |  13 +
 src/hooks/useProjectSync.ts                   | 112 +++++
 src/pages/DatabaseDetails.tsx                 |  11 +-
 src/pages/Projects.tsx                        | 394 +++++++++---------
 src/services/bridgeApi.ts                     |  15 +
 10 files changed, 439 insertions(+), 204 deletions(-)
 create mode 100644 src/hooks/useProjectSync.ts

diff --git a/bridge/src/handlers/projectHandlers.ts b/bridge/src/handlers/projectHandlers.ts
index 98a0a35..0858c05 100644
--- a/bridge/src/handlers/projectHandlers.ts
+++ b/bridge/src/handlers/projectHandlers.ts
@@ -48,6 +48,25 @@ export class ProjectHandlers {
         }
     }
 
+    async handleGetProjectByDatabaseId(params: any, id: number | string) {
+        try {
+            const { databaseId } = params || {};
+            if (!databaseId) {
+                return this.rpc.sendError(id, {
+                    code: "BAD_REQUEST",
+                    message: "Missing databaseId",
+                });
+            }
+
+            const project = await projectStoreInstance.getProjectByDatabaseId(databaseId);
+            // Return null (not an error) when no project is linked
+            this.rpc.sendResponse(id, { ok: true, data: project });
+        } catch (e: any) {
+            this.logger?.error({ e }, "project.getByDatabaseId failed");
+            this.rpc.sendError(id, { code: "IO_ERROR", message: String(e) });
+        }
+    }
+
     async handleCreateProject(params: any, id: number | string) {
         try {
             const { databaseId, name, description, defaultSchema } = params || {};
diff --git a/bridge/src/jsonRpcHandler.ts b/bridge/src/jsonRpcHandler.ts
index 824d823..fb33bcc 100644
--- a/bridge/src/jsonRpcHandler.ts
+++ b/bridge/src/jsonRpcHandler.ts
@@ -179,6 +179,9 @@ export function registerDbHandlers(
   rpcRegister("project.get", (p, id) =>
     projectHandlers.handleGetProject(p, id)
   );
+  rpcRegister("project.getByDatabaseId", (p, id) =>
+    projectHandlers.handleGetProjectByDatabaseId(p, id)
+  );
   rpcRegister("project.create", (p, id) =>
     projectHandlers.handleCreateProject(p, id)
   );
diff --git a/bridge/src/services/projectStore.ts b/bridge/src/services/projectStore.ts
index 43ece1c..d8cf8ce 100644
--- a/bridge/src/services/projectStore.ts
+++ b/bridge/src/services/projectStore.ts
@@ -196,6 +196,17 @@ export class ProjectStore {
         );
     }
 
+    /**
+     * Find a project linked to a specific database ID.
+     * Returns the first matching project or null.
+     */
+    async getProjectByDatabaseId(databaseId: string): Promise<ProjectMetadata | null> {
+        const index = await this.loadIndex();
+        const entry = index.projects.find((p) => p.databaseId === databaseId);
+        if (!entry) return null;
+        return this.getProject(entry.id);
+    }
+
     /**
      * Create a new project linked to a database connection
      */
diff --git a/src/components/er-diagram/ERDiagramContent.tsx b/src/components/er-diagram/ERDiagramContent.tsx
index 5261db7..035ce8b 100644
--- a/src/components/er-diagram/ERDiagramContent.tsx
+++ b/src/components/er-diagram/ERDiagramContent.tsx
@@ -1,6 +1,6 @@
 import { toPng, toSvg } from "html-to-image";
 import { ArrowLeft, ChevronDown, Database, Download, Filter, LayoutGrid, Layers, Search, X } from "lucide-react";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 import {
     Background,
@@ -19,7 +19,9 @@ import { toast } from "sonner";
 import { transformSchemaToER } from "@/lib/schemaTransformer";
 import { Spinner } from "@/components/ui/spinner";
 import { useFullSchema } from "@/hooks/useDbQueries";
+import { bridgeApi } from "@/services/bridgeApi";
 import { ColumnDetails, DatabaseSchemaDetails, ForeignKeyInfo, TableSchemaDetails } from "@/types/database";
+import type { ERNode } from "@/types/project";
 import {
     Tooltip,
     TooltipContent,
@@ -55,9 +57,12 @@ interface ERDiagramContentProps {
     nodeTypes: {
         table: React.FC<{ data: TableNodeData }>;
     };
+    projectId?: string | null;
 }
 
-const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes }) => {
+const ER_SAVE_DEBOUNCE_MS = 2000;
+
+const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectId }) => {
     const { id: dbId } = useParams<{ id: string }>();
     const reactFlowInstance = useReactFlow();
 
@@ -95,7 +100,7 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes }) => {
     const filteredSchemaData = useMemo((): DatabaseSchemaDetails | null => {
         if (!schemaData) return null;
         if (selectedSchema === "__all__") return schemaData;
-        
+
         return {
             ...schemaData,
             schemas: schemaData.schemas.filter(s => s.name === selectedSchema)
@@ -116,6 +121,52 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes }) => {
         }
     }, [filteredSchemaData, setNodes, setEdges, reactFlowInstance]);
 
+    // -----------------------------------------
+    // Auto-save ER node positions to project
+    // Debounced: only fires ER_SAVE_DEBOUNCE_MS after last node movement
+    // -----------------------------------------
+    const erSaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const initialLayoutDoneRef = useRef(false);
+
+    // Mark that the initial layout just happened so we skip saving it
+    useEffect(() => {
+        initialLayoutDoneRef.current = false;
+        const id = setTimeout(() => { initialLayoutDoneRef.current = true; }, 500);
+        return () => clearTimeout(id);
+    }, [filteredSchemaData]);
+
+    useEffect(() => {
+        // Don't save during initial layout or if no project linked
+        if (!projectId || !initialLayoutDoneRef.current || nodes.length === 0) return;
+
+        if (erSaveTimerRef.current) clearTimeout(erSaveTimerRef.current);
+
+        erSaveTimerRef.current = setTimeout(() => {
+            const viewport = reactFlowInstance?.getViewport();
+            const erNodes: ERNode[] = nodes.map((n) => ({
+                tableId: n.id,
+                x: n.position.x,
+                y: n.position.y,
+                width: n.width ?? undefined,
+                height: n.height ?? undefined,
+            }));
+
+            bridgeApi
+                .saveProjectERDiagram(projectId, {
+                    nodes: erNodes,
+                    zoom: viewport?.zoom,
+                    panX: viewport?.x,
+                    panY: viewport?.y,
+                })
+                .then(() => console.debug("[ProjectSync] ER diagram saved"))
+                .catch((err) => console.warn("[ProjectSync] ER diagram save failed:", err.message));
+        }, ER_SAVE_DEBOUNCE_MS);
+
+        return () => {
+            if (erSaveTimerRef.current) clearTimeout(erSaveTimerRef.current);
+        };
+    }, [nodes, projectId, reactFlowInstance]);
+
     // Filter nodes based on search query
     const filteredNodes = useMemo(() => {
         if (!searchQuery.trim()) return nodes;
diff --git a/src/components/er-diagram/ERDiagramPanel.tsx b/src/components/er-diagram/ERDiagramPanel.tsx
index 5a17f9c..0946a7d 100644
--- a/src/components/er-diagram/ERDiagramPanel.tsx
+++ b/src/components/er-diagram/ERDiagramPanel.tsx
@@ -7,11 +7,15 @@ const nodeTypes = {
     table: TableNode,
 } as const;
 
-export default function ERDiagramPanel() {
+interface ERDiagramPanelProps {
+    projectId?: string | null;
+}
+
+export default function ERDiagramPanel({ projectId }: ERDiagramPanelProps) {
     return (
         <div className="h-full flex flex-col bg-background text-foreground overflow-hidden">
             <ReactFlowProvider>
-                <ERDiagramContent nodeTypes={nodeTypes} />
+                <ERDiagramContent nodeTypes={nodeTypes} projectId={projectId} />
             </ReactFlowProvider>
         </div>
     );
diff --git a/src/hooks/useProjectQueries.ts b/src/hooks/useProjectQueries.ts
index 86df2d8..777078b 100644
--- a/src/hooks/useProjectQueries.ts
+++ b/src/hooks/useProjectQueries.ts
@@ -14,6 +14,7 @@ import {
 export const projectKeys = {
   all: ["projects"] as const,
   detail: (id: string) => ["projects", id] as const,
+  byDatabaseId: (dbId: string) => ["projects", "byDb", dbId] as const,
   schema: (id: string) => ["projects", id, "schema"] as const,
   erDiagram: (id: string) => ["projects", id, "erDiagram"] as const,
   queries: (id: string) => ["projects", id, "queries"] as const,
@@ -60,6 +61,18 @@ export function useProject(projectId: string | undefined) {
   });
 }
 
+// ============================================
+// Get Project by Database ID (for auto-sync)
+// ============================================
+export function useProjectByDatabaseId(databaseId: string | undefined) {
+  return useQuery({
+    queryKey: projectKeys.byDatabaseId(databaseId!),
+    queryFn: () => bridgeApi.getProjectByDatabaseId(databaseId!),
+    staleTime: STALE_TIMES.detail,
+    enabled: !!databaseId,
+  });
+}
+
 // ============================================
 // Create Project
 // ============================================
diff --git a/src/hooks/useProjectSync.ts b/src/hooks/useProjectSync.ts
new file mode 100644
index 0000000..c5a2d96
--- /dev/null
+++ b/src/hooks/useProjectSync.ts
@@ -0,0 +1,112 @@
+import { useEffect, useRef, useCallback } from "react";
+import { bridgeApi } from "@/services/bridgeApi";
+import { useProjectByDatabaseId } from "@/hooks/useProjectQueries";
+import type { DatabaseSchemaDetails, SchemaGroup, TableSchemaDetails } from "@/types/database";
+import type { SchemaSnapshot, TableSnapshot, ColumnSnapshot, ERNode } from "@/types/project";
+
+// ==========================================
+// Schema data transformer
+// Live DB format → Project store format
+// ==========================================
+
+function transformToSchemaSnapshots(schemas: SchemaGroup[]): SchemaSnapshot[] {
+    return schemas.map((sg) => ({
+        name: sg.name,
+        tables: (sg.tables || []).map(
+            (t): TableSnapshot => ({
+                name: t.name,
+                type: t.type || "BASE TABLE",
+                columns: (t.columns || []).map(
+                    (c): ColumnSnapshot => ({
+                        name: c.name,
+                        type: c.type,
+                        nullable: c.nullable ?? true,
+                        isPrimaryKey: c.isPrimaryKey ?? false,
+                        isForeignKey: c.isForeignKey ?? false,
+                        defaultValue: c.defaultValue ?? null,
+                        isUnique: c.isUnique ?? false,
+                    })
+                ),
+            })
+        ),
+    }));
+}
+
+// ==========================================
+// Hook: useProjectSync
+//
+// Automatically syncs live database data into the linked project's
+// JSON files whenever fresh data is fetched.
+//
+// Usage:  const { projectId } = useProjectSync(dbId, schemaData);
+//
+// It also exposes helpers for ER diagram and query sync.
+// ==========================================
+
+interface UseProjectSyncReturn {
+    /** The linked project's ID, or null if no project is linked */
+    projectId: string | null;
+    /** Whether the project lookup is still loading */
+    isLoading: boolean;
+    /** Save ER diagram node positions (debounced externally by caller) */
+    saveERDiagram: (nodes: ERNode[], zoom?: number, panX?: number, panY?: number) => void;
+}
+
+export function useProjectSync(
+    dbId: string | undefined,
+    schemaData: DatabaseSchemaDetails | undefined
+): UseProjectSyncReturn {
+    const { data: project, isLoading } = useProjectByDatabaseId(dbId);
+    const projectId = project?.id ?? null;
+
+    // Track what we last synced to avoid redundant writes
+    const lastSyncedSchemaRef = useRef<string | null>(null);
+
+    // -----------------------------------------
+    // Auto-sync schema when fresh data arrives
+    // -----------------------------------------
+    useEffect(() => {
+        if (!projectId || !schemaData?.schemas?.length) return;
+
+        // Build a lightweight fingerprint to avoid re-saving identical data.
+        // We use schema/table count as a quick check (cheap to compute).
+        const fingerprint = schemaData.schemas
+            .map((s) => `${s.name}:${s.tables?.length ?? 0}`)
+            .join("|");
+
+        if (fingerprint === lastSyncedSchemaRef.current) return;
+
+        const snapshots = transformToSchemaSnapshots(schemaData.schemas);
+
+        // Fire-and-forget — sync in the background without blocking UI
+        bridgeApi
+            .saveProjectSchema(projectId, snapshots)
+            .then(() => {
+                lastSyncedSchemaRef.current = fingerprint;
+                console.debug("[ProjectSync] Schema synced for project", projectId);
+            })
+            .catch((err) => {
+                console.warn("[ProjectSync] Schema sync failed:", err.message);
+            });
+    }, [projectId, schemaData]);
+
+    // -----------------------------------------
+    // ER Diagram save helper
+    // -----------------------------------------
+    const saveERDiagram = useCallback(
+        (nodes: ERNode[], zoom?: number, panX?: number, panY?: number) => {
+            if (!projectId) return;
+            bridgeApi
+                .saveProjectERDiagram(projectId, { nodes, zoom, panX, panY })
+                .then(() => {
+                    console.debug("[ProjectSync] ER diagram synced for project", projectId);
+                })
+                .catch((err) => {
+                    console.warn("[ProjectSync] ER diagram sync failed:", err.message);
+                });
+        },
+        [projectId]
+    );
+
+    return { projectId, isLoading, saveERDiagram };
+}
diff --git a/src/pages/DatabaseDetails.tsx b/src/pages/DatabaseDetails.tsx
index 429be47..e73678f 100644
--- a/src/pages/DatabaseDetails.tsx
+++ b/src/pages/DatabaseDetails.tsx
@@ -11,8 +11,9 @@ import {
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { useBridgeQuery } from "@/hooks/useBridgeQuery";
 import { useDatabaseDetails } from "@/hooks/useDatabaseDetails";
-import { useMigrations } from "@/hooks/useDbQueries";
+import { useMigrations, useFullSchema } from "@/hooks/useDbQueries";
 import { useExport } from "@/hooks/useExport";
+import { useProjectSync } from "@/hooks/useProjectSync";
 import BridgeLoader from "@/components/feedback/BridgeLoader";
 import { Spinner } from "@/components/ui/spinner";
 import VerticalIconBar, { PanelType } from "@/components/common/VerticalIconBar";
@@ -90,6 +91,12 @@ const DatabaseDetail = () => {
   };
   const baselined = migrationsResponse?.baselined || false;
 
+  // --- Project auto-sync ---
+  // Fetches schema (React Query deduplicates with child components)
+  // and auto-saves to the linked project's JSON files in the background.
+  const { data: schemaData } = useFullSchema(dbId);
+  const { projectId } = useProjectSync(dbId, schemaData ?? undefined);
+
   if (bridgeLoading || bridgeReady === undefined) {
     return <BridgeLoader />;
   }
@@ -139,7 +146,7 @@ const DatabaseDetail = () => {
       case 'schema-explorer':
         return <SchemaExplorerPanel dbId={dbId || ''} />;
       case 'er-diagram':
-        return <ERDiagramPanel />;
+        return <ERDiagramPanel projectId={projectId} />;
       case 'data':
       default:
         return (
diff --git a/src/pages/Projects.tsx b/src/pages/Projects.tsx
index c380293..920ff37 100644
--- a/src/pages/Projects.tsx
+++ b/src/pages/Projects.tsx
@@ -4,216 +4,216 @@ import { useNavigate } from "react-router-dom";
 import { useBridgeQuery } from "@/hooks/useBridgeQuery";
 import { useDatabases } from "@/hooks/useDbQueries";
 import {
-  useProjects,
-  useCreateProject,
-  useDeleteProject,
-  useProjectSchema,
-  useProjectERDiagram,
-  useProjectQueries,
+    useProjects,
+    useCreateProject,
+    useDeleteProject,
+    useProjectSchema,
+    useProjectERDiagram,
+    useProjectQueries,
 } from "@/hooks/useProjectQueries";
 import { bridgeApi } from "@/services/bridgeApi";
 import BridgeLoader from "@/components/feedback/BridgeLoader";
 import BridgeFailed from "@/components/feedback/BridgeFailed";
 import VerticalIconBar from "@/components/common/VerticalIconBar";
 import {
-  ProjectList,
-  CreateProjectDialog,
-  DeleteProjectDialog,
-  ProjectDetailView,
+    ProjectList,
+    CreateProjectDialog,
+    DeleteProjectDialog,
+    ProjectDetailView,
 } from "@/components/project";
 import { FolderOpen, Sparkles } from "lucide-react";
 import { Button } from "@/components/ui/button";
 
 const Projects = () => {
-  const navigate = useNavigate();
-  const { data: bridgeReady, isLoading: bridgeLoading } = useBridgeQuery();
-
-  // Data queries
-  const { data: projects = [], isLoading: projectsLoading } = useProjects();
-  const { data: databases = [] } = useDatabases();
-
-  // Mutations
-  const createProjectMutation = useCreateProject();
-  const deleteProjectMutation = useDeleteProject();
-
-  // Local state
-  const [searchQuery, setSearchQuery] = useState("");
-  const [selectedProject, setSelectedProject] = useState<string | null>(null);
-  const [isCreateOpen, setIsCreateOpen] = useState(false);
-  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
-  const [projectToDelete, setProjectToDelete] = useState<{
-    id: string;
-    name: string;
-  } | null>(null);
-
-  // Sub-resource queries for the selected project
-  const { data: schemaData } = useProjectSchema(selectedProject ?? undefined);
-  const { data: erData } = useProjectERDiagram(selectedProject ?? undefined);
-  const { data: queriesData } = useProjectQueries(selectedProject ?? undefined);
-
-  // Filtering
-  const filteredProjects = useMemo(
-    () =>
-      projects.filter(
-        (p) =>
-          p.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
-          (p.description ?? "").toLowerCase().includes(searchQuery.toLowerCase())
-      ),
-    [projects, searchQuery]
-  );
-
-  const selectedProjectData = useMemo(
-    () => projects.find((p) => p.id === selectedProject) ?? null,
-    [projects, selectedProject]
-  );
-
-  // ---- Handlers ----
-
-  const handleCreate = async (data: {
-    databaseId: string;
-    name: string;
-    description?: string;
-    defaultSchema?: string;
-  }) => {
-    try {
-      const created = await createProjectMutation.mutateAsync(data);
-      toast.success("Project created", { description: created.name });
-      setIsCreateOpen(false);
-      setSelectedProject(created.id);
-    } catch (err: any) {
-      toast.error("Failed to create project", { description: err.message });
-    }
-  };
-
-  const handleDelete = async () => {
-    if (!projectToDelete) return;
-    try {
-      await deleteProjectMutation.mutateAsync(projectToDelete.id);
-      toast.success("Project deleted");
-      setDeleteDialogOpen(false);
-      setProjectToDelete(null);
-      if (selectedProject === projectToDelete.id) setSelectedProject(null);
-    } catch (err: any) {
-      toast.error("Failed to delete", { description: err.message });
-    }
-  };
-
-  const handleExport = async (projectId: string) => {
-    try {
-      const bundle = await bridgeApi.exportProject(projectId);
-      if (!bundle) {
-        toast.error("Project not found");
-        return;
-      }
-      // Download as JSON file
-      const blob = new Blob([JSON.stringify(bundle, null, 2)], {
-        type: "application/json",
-      });
-      const url = URL.createObjectURL(blob);
-      const a = document.createElement("a");
-      a.href = url;
-      a.download = `${bundle.metadata.name.replace(/\s+/g, "-").toLowerCase()}-export.json`;
-      a.click();
-      URL.revokeObjectURL(url);
-      toast.success("Project exported");
-    } catch (err: any) {
-      toast.error("Export failed", { description: err.message });
-    }
-  };
-
-  const handleOpen = (projectId: string) => {
-    const project = projects.find((p) => p.id === projectId);
-    if (project) {
-      // Navigate to the linked database detail page
-      navigate(`/${project.databaseId}`);
-    }
-  };
-
-  // ---- Loading / Error states ----
-  if (bridgeLoading || bridgeReady === undefined) return <BridgeLoader />;
-  if (!bridgeReady) return <BridgeFailed />;
-
-  return (
-    <div className="h-[calc(100vh-32px)] flex bg-background text-foreground overflow-hidden">
-      <VerticalIconBar />
-      <main className="flex-1 ml-[60px] flex">
-        {/* Left panel */}
-        <ProjectList
-          projects={projects}
-          filteredProjects={filteredProjects}
-          loading={projectsLoading}
-          searchQuery={searchQuery}
-          setSearchQuery={setSearchQuery}
-          selectedProject={selectedProject}
-          setSelectedProject={setSelectedProject}
-          onCreateClick={() => setIsCreateOpen(true)}
-          onDelete={(id: string, name: string) => {
-            setProjectToDelete({ id, name });
-            setDeleteDialogOpen(true);
-          }}
-          onOpen={handleOpen}
-        />
-
-        {/* Right panel */}
-        <div className="flex-1 overflow-y-auto">
-          {selectedProjectData ? (
-            <ProjectDetailView
-              project={selectedProjectData}
-              schemaCount={schemaData?.schemas?.length}
-              queryCount={queriesData?.queries?.length}
-              hasERLayout={(erData?.nodes?.length ?? 0) > 0}
-              onOpen={() => handleOpen(selectedProjectData.id)}
-              onDelete={() => {
-                setProjectToDelete({
-                  id: selectedProjectData.id,
-                  name: selectedProjectData.name,
-                });
-                setDeleteDialogOpen(true);
-              }}
-              onExport={() => handleExport(selectedProjectData.id)}
-            />
-          ) : (
-            /* Empty state */
-            <div className="h-full flex flex-col items-center justify-center p-6">
-              <div className="flex items-center gap-3 mb-4">
-                <div className="h-10 w-10 rounded-xl bg-primary/10 flex items-center justify-center">
-                  <FolderOpen className="h-5 w-5 text-primary" />
-                </div>
-                <div>
-                  <h1 className="text-xl font-semibold">Projects</h1>
-                  <p className="text-sm text-muted-foreground">
-                    Save database details, ER diagrams &amp; queries offline
-                  </p>
+    const navigate = useNavigate();
+    const { data: bridgeReady, isLoading: bridgeLoading } = useBridgeQuery();
+
+    // Data queries
+    const { data: projects = [], isLoading: projectsLoading } = useProjects();
+    const { data: databases = [] } = useDatabases();
+
+    // Mutations
+    const createProjectMutation = useCreateProject();
+    const deleteProjectMutation = useDeleteProject();
+
+    // Local state
+    const [searchQuery, setSearchQuery] = useState("");
+    const [selectedProject, setSelectedProject] = useState<string | null>(null);
+    const [isCreateOpen, setIsCreateOpen] = useState(false);
+    const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
+    const [projectToDelete, setProjectToDelete] = useState<{
+        id: string;
+        name: string;
+    } | null>(null);
+
+    // Sub-resource queries for the selected project
+    const { data: schemaData } = useProjectSchema(selectedProject ?? undefined);
+    const { data: erData } = useProjectERDiagram(selectedProject ?? undefined);
+    const { data: queriesData } = useProjectQueries(selectedProject ?? undefined);
+
+    // Filtering
+    const filteredProjects = useMemo(
+        () =>
+            projects.filter(
+                (p) =>
+                    p.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
+                    (p.description ?? "").toLowerCase().includes(searchQuery.toLowerCase())
+            ),
+        [projects, searchQuery]
+    );
+
+    const selectedProjectData = useMemo(
+        () => projects.find((p) => p.id === selectedProject) ?? null,
+        [projects, selectedProject]
+    );
+
+    // ---- Handlers ----
+
+    const handleCreate = async (data: {
+        databaseId: string;
+        name: string;
+        description?: string;
+        defaultSchema?: string;
+    }) => {
+        try {
+            const created = await createProjectMutation.mutateAsync(data);
+            toast.success("Project created", { description: created.name });
+            setIsCreateOpen(false);
+            setSelectedProject(created.id);
+        } catch (err: any) {
+            toast.error("Failed to create project", { description: err.message });
+        }
+    };
+
+    const handleDelete = async () => {
+        if (!projectToDelete) return;
+        try {
+            await deleteProjectMutation.mutateAsync(projectToDelete.id);
+            toast.success("Project deleted");
+            setDeleteDialogOpen(false);
+            setProjectToDelete(null);
+            if (selectedProject === projectToDelete.id) setSelectedProject(null);
+        } catch (err: any) {
+            toast.error("Failed to delete", { description: err.message });
+        }
+    };
+
+    const handleExport = async (projectId: string) => {
+        try {
+            const bundle = await bridgeApi.exportProject(projectId);
+            if (!bundle) {
+                toast.error("Project not found");
+                return;
+            }
+            // Download as JSON file
+            const blob = new Blob([JSON.stringify(bundle, null, 2)], {
+                type: "application/json",
+            });
+            const url = URL.createObjectURL(blob);
+            const a = document.createElement("a");
+            a.href = url;
+            a.download = `${bundle.metadata.name.replace(/\s+/g, "-").toLowerCase()}-export.json`;
+            a.click();
+            URL.revokeObjectURL(url);
+            toast.success("Project exported");
+        } catch (err: any) {
+            toast.error("Export failed", { description: err.message });
+        }
+    };
+
+    const handleOpen = (projectId: string) => {
+        const project = projects.find((p) => p.id === projectId);
+        if (project) {
+            // Navigate to the linked database detail page
+            navigate(`/${project.databaseId}`);
+        }
+    };
+
+    // ---- Loading / Error states ----
+    if (bridgeLoading || bridgeReady === undefined) return <BridgeLoader />;
+    if (!bridgeReady) return <BridgeFailed />;
+
+    return (
+        <div className="h-[calc(100vh-32px)] flex bg-background text-foreground overflow-hidden">
+            <VerticalIconBar />
+            <main className="flex-1 ml-[60px] flex">
+                {/* Left panel */}
+                <ProjectList
+                    projects={projects}
+                    filteredProjects={filteredProjects}
+                    loading={projectsLoading}
+                    searchQuery={searchQuery}
+                    setSearchQuery={setSearchQuery}
+                    selectedProject={selectedProject}
+                    setSelectedProject={setSelectedProject}
+                    onCreateClick={() => setIsCreateOpen(true)}
+                    onDelete={(id: string, name: string) => {
+                        setProjectToDelete({ id, name });
+                        setDeleteDialogOpen(true);
+                    }}
+                    onOpen={handleOpen}
+                />
+
+                {/* Right panel */}
+                <div className="flex-1 overflow-y-auto">
+                    {selectedProjectData ? (
+                        <ProjectDetailView
+                            project={selectedProjectData}
+                            schemaCount={schemaData?.schemas?.length}
+                            queryCount={queriesData?.queries?.length}
+                            hasERLayout={(erData?.nodes?.length ?? 0) > 0}
+                            onOpen={() => handleOpen(selectedProjectData.id)}
+                            onDelete={() => {
+                                setProjectToDelete({
+                                    id: selectedProjectData.id,
+                                    name: selectedProjectData.name,
+                                });
+                                setDeleteDialogOpen(true);
+                            }}
+                            onExport={() => handleExport(selectedProjectData.id)}
+                        />
+                    ) : (
+                        /* Empty state */
+                        <div className="h-full flex flex-col items-center justify-center p-6">
+                            <div className="flex items-center gap-3 mb-4">
+                                <div className="h-10 w-10 rounded-xl bg-primary/10 flex items-center justify-center">
+                                    <FolderOpen className="h-5 w-5 text-primary" />
+                                </div>
+                                <div>
+                                    <h1 className="text-xl font-semibold">Projects</h1>
+                                    <p className="text-sm text-muted-foreground">
+                                        Save database details, ER diagrams &amp; queries offline
+                                    </p>
+                                </div>
+                            </div>
+                            {projects.length === 0 && (
+                                <Button onClick={() => setIsCreateOpen(true)} className="mt-4">
+                                    <Sparkles className="h-4 w-4 mr-2" />
+                                    Create Your First Project
+                                </Button>
+                            )}
+                        </div>
+                    )}
                 </div>
-              </div>
-              {projects.length === 0 && (
-                <Button onClick={() => setIsCreateOpen(true)} className="mt-4">
-                  <Sparkles className="h-4 w-4 mr-2" />
-                  Create Your First Project
-                </Button>
-              )}
-            </div>
-          )}
+            </main>
+
+            {/* Dialogs */}
+            <CreateProjectDialog
+                open={isCreateOpen}
+                onOpenChange={setIsCreateOpen}
+                onSubmit={handleCreate}
+                isLoading={createProjectMutation.isPending}
+                databases={databases}
+            />
+
+            <DeleteProjectDialog
+                open={deleteDialogOpen}
+                onOpenChange={setDeleteDialogOpen}
+                projectName={projectToDelete?.name}
+                onConfirm={handleDelete}
+            />
         </div>
-      </main>
-
-      {/* Dialogs */}
-      <CreateProjectDialog
-        open={isCreateOpen}
-        onOpenChange={setIsCreateOpen}
-        onSubmit={handleCreate}
-        isLoading={createProjectMutation.isPending}
-        databases={databases}
-      />
-
-      <DeleteProjectDialog
-        open={deleteDialogOpen}
-        onOpenChange={setDeleteDialogOpen}
-        projectName={projectToDelete?.name}
-        onConfirm={handleDelete}
-      />
-    </div>
-  );
+    );
 };
 
 export default Projects;
diff --git a/src/services/bridgeApi.ts b/src/services/bridgeApi.ts
index a21996b..decb2a2 100644
--- a/src/services/bridgeApi.ts
+++ b/src/services/bridgeApi.ts
@@ -826,6 +826,21 @@ class BridgeApiService {
     }
   }
 
+  /**
+   * Find a project linked to a specific database connection.
+   * Returns null when no project is linked (not an error).
+   */
+  async getProjectByDatabaseId(databaseId: string): Promise<ProjectMetadata | null> {
+    try {
+      if (!databaseId) throw new Error("Database ID is required");
+      const result = await bridgeRequest("project.getByDatabaseId", { databaseId });
+      return result?.data || null;
+    } catch (error: any) {
+      console.error("Failed to get project by database ID:", error);
+      throw new Error(`Failed to get project by database ID: ${error.message}`);
+    }
+  }
+
   /**
    * Create a new project linked to a database connection
    */

From 34d603ab053220460404df06541912e2c27def30 Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 20:47:21 +0530
Subject: [PATCH 4/9] feat: enhance ER diagram with live sync and layout
 management

---
 .../er-diagram/ERDiagramContent.tsx           | 147 +++++++++--
 src/hooks/useERDiagramData.ts                 | 245 ++++++++++++++++++
 src/lib/schemaTransformer.ts                  |  24 +-
 3 files changed, 385 insertions(+), 31 deletions(-)
 create mode 100644 src/hooks/useERDiagramData.ts

diff --git a/src/components/er-diagram/ERDiagramContent.tsx b/src/components/er-diagram/ERDiagramContent.tsx
index 035ce8b..e1adab1 100644
--- a/src/components/er-diagram/ERDiagramContent.tsx
+++ b/src/components/er-diagram/ERDiagramContent.tsx
@@ -1,5 +1,5 @@
 import { toPng, toSvg } from "html-to-image";
-import { ArrowLeft, ChevronDown, Database, Download, Filter, LayoutGrid, Layers, Search, X } from "lucide-react";
+import { ChevronDown, Cloud, Database, Download, Filter, HardDrive, LayoutGrid, Layers, RefreshCw, Search, WifiOff, X } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 import {
@@ -18,7 +18,7 @@ import {
 import { toast } from "sonner";
 import { transformSchemaToER } from "@/lib/schemaTransformer";
 import { Spinner } from "@/components/ui/spinner";
-import { useFullSchema } from "@/hooks/useDbQueries";
+import { useERDiagramData } from "@/hooks/useERDiagramData";
 import { bridgeApi } from "@/services/bridgeApi";
 import { ColumnDetails, DatabaseSchemaDetails, ForeignKeyInfo, TableSchemaDetails } from "@/types/database";
 import type { ERNode } from "@/types/project";
@@ -74,17 +74,21 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
     const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
     const [hoveredEdge, setHoveredEdge] = useState<Edge | null>(null);
     const [selectedSchema, setSelectedSchema] = useState<string>("__all__");
+    const [isSyncing, setIsSyncing] = useState(false);
 
-    // Use React Query for schema data (cached!)
+    // Use the smart data source hook (offline-first + live fallback)
     const {
-        data: schemaData,
+        schemaData,
+        savedLayout,
         isLoading,
-        error: queryError
-    } = useFullSchema(dbId);
-
-
-    const error = queryError ? (queryError as Error).message :
-        (schemaData && !schemaData.schemas?.some(s => s.tables?.length))
+        dataSource,
+        hasLiveSchema,
+        syncFromDatabase,
+    } = useERDiagramData(dbId, projectId);
+
+    const error = !isLoading && !schemaData
+        ? "No schema data available. Connect to a database or open a project."
+        : (schemaData && !schemaData.schemas?.some(s => s.tables?.length))
             ? "Schema data found, but no tables to render."
             : null;
 
@@ -108,18 +112,37 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
     }, [schemaData, selectedSchema]);
 
     // Transform schema to ER nodes/edges when data or filter changes
+    // Merges saved layout positions with schema data:
+    //   - Table in schema + in saved layout → use saved position
+    //   - Table in schema but NOT in saved layout → auto-place (new table)
+    //   - Table in saved layout but NOT in schema → ignored (removed table)
     useEffect(() => {
         if (filteredSchemaData && filteredSchemaData.schemas?.some(s => s.tables?.length)) {
-            const { nodes: newNodes, edges: newEdges } = transformSchemaToER(filteredSchemaData);
+            const layoutNodes = savedLayout?.nodes ?? null;
+            const { nodes: newNodes, edges: newEdges } = transformSchemaToER(
+                filteredSchemaData,
+                true,
+                layoutNodes
+            );
             setNodes(newNodes as typeof nodes);
             setEdges(newEdges);
             // Fit view after layout change
-            setTimeout(() => reactFlowInstance?.fitView({ padding: 0.2, duration: 300 }), 100);
+            setTimeout(() => {
+                if (savedLayout?.zoom != null && savedLayout?.panX != null && savedLayout?.panY != null) {
+                    reactFlowInstance?.setViewport({
+                        zoom: savedLayout.zoom,
+                        x: savedLayout.panX,
+                        y: savedLayout.panY,
+                    });
+                } else {
+                    reactFlowInstance?.fitView({ padding: 0.2, duration: 300 });
+                }
+            }, 100);
         } else {
             setNodes([]);
             setEdges([]);
         }
-    }, [filteredSchemaData, setNodes, setEdges, reactFlowInstance]);
+    }, [filteredSchemaData, savedLayout, setNodes, setEdges, reactFlowInstance]);
 
     // -----------------------------------------
     // Auto-save ER node positions to project
@@ -131,9 +154,9 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
     // Mark that the initial layout just happened so we skip saving it
     useEffect(() => {
         initialLayoutDoneRef.current = false;
-        const id = setTimeout(() => { initialLayoutDoneRef.current = true; }, 500);
+        const id = setTimeout(() => { initialLayoutDoneRef.current = true; }, 800);
         return () => clearTimeout(id);
-    }, [filteredSchemaData]);
+    }, [filteredSchemaData, savedLayout]);
 
     useEffect(() => {
         // Don't save during initial layout or if no project linked
@@ -261,10 +284,10 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
         }
     }, [filteredNodes, reactFlowInstance]);
 
-    // Re-layout with dagre
+    // Re-layout with dagre (ignores saved layout to generate fresh positions)
     const reLayout = useCallback(() => {
         if (filteredSchemaData) {
-            const { nodes: newNodes, edges: newEdges } = transformSchemaToER(filteredSchemaData, true);
+            const { nodes: newNodes, edges: newEdges } = transformSchemaToER(filteredSchemaData, true, null);
             setNodes(newNodes as typeof nodes);
             setEdges(newEdges);
             setTimeout(() => reactFlowInstance?.fitView({ padding: 0.2, duration: 500 }), 100);
@@ -335,15 +358,35 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
     if (error || !schemaData || nodes.length === 0) {
         return (
             <div className="h-screen flex items-center justify-center bg-background">
-                <div className="text-center p-6 border border-border rounded-lg bg-card">
+                <div className="text-center p-6 border border-border rounded-lg bg-card max-w-sm">
                     <Database className="h-8 w-8 mx-auto mb-3 text-muted-foreground" />
                     <h2 className="text-base font-medium mb-1">Diagram Unavailable</h2>
                     <p className="text-sm text-muted-foreground mb-4">{error || "No tables found."}</p>
-                    <Link to={`/${dbId}`}>
-                        <button className="px-4 py-2 rounded-md text-sm bg-primary text-primary-foreground hover:bg-primary/90">
-                            Go Back
-                        </button>
-                    </Link>
+                    <div className="flex gap-2 justify-center">
+                        {hasLiveSchema && projectId && (
+                            <Button
+                                size="sm"
+                                onClick={async () => {
+                                    setIsSyncing(true);
+                                    await syncFromDatabase();
+                                    setIsSyncing(false);
+                                }}
+                                disabled={isSyncing}
+                            >
+                                {isSyncing ? (
+                                    <Spinner className="h-3.5 w-3.5 mr-1.5" />
+                                ) : (
+                                    <RefreshCw className="h-3.5 w-3.5 mr-1.5" />
+                                )}
+                                Pull from Database
+                            </Button>
+                        )}
+                        <Link to={`/${dbId}`}>
+                            <Button variant="outline" size="sm">
+                                Go Back
+                            </Button>
+                        </Link>
+                    </div>
                 </div>
             </div>
         );
@@ -359,6 +402,27 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
                         <span className="text-sm font-medium">{schemaData.name || 'Database'}</span>
                         <span className="text-muted-foreground/50">•</span>
                         <span className="text-sm font-medium text-foreground">ER Diagram</span>
+                        {/* Data source badge */}
+                        <Tooltip>
+                            <TooltipTrigger asChild>
+                                <span className={`inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-medium ${dataSource === "live"
+                                    ? "bg-emerald-500/10 text-emerald-600 border border-emerald-500/20"
+                                    : "bg-amber-500/10 text-amber-600 border border-amber-500/20"
+                                    }`}>
+                                    {dataSource === "live" ? (
+                                        <Cloud className="h-3 w-3" />
+                                    ) : (
+                                        <HardDrive className="h-3 w-3" />
+                                    )}
+                                    {dataSource === "live" ? "Live" : "Offline"}
+                                </span>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom" sideOffset={8}>
+                                {dataSource === "live"
+                                    ? "Schema loaded from live database connection"
+                                    : "Schema loaded from saved project files (offline)"}
+                            </TooltipContent>
+                        </Tooltip>
                     </div>
 
                     {/* Schema filter dropdown */}
@@ -436,6 +500,34 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
                                 Clear
                             </button>
                         )}
+                        {/* Sync from Database button */}
+                        {projectId && (
+                            <Tooltip>
+                                <TooltipTrigger asChild>
+                                    <Button
+                                        variant="outline"
+                                        size="sm"
+                                        className="h-8 text-xs"
+                                        onClick={async () => {
+                                            setIsSyncing(true);
+                                            await syncFromDatabase();
+                                            setIsSyncing(false);
+                                        }}
+                                        disabled={isSyncing || !hasLiveSchema}
+                                    >
+                                        {isSyncing ? (
+                                            <Spinner className="h-3.5 w-3.5 mr-1.5" />
+                                        ) : (
+                                            <RefreshCw className="h-3.5 w-3.5 mr-1.5" />
+                                        )}
+                                        Sync
+                                    </Button>
+                                </TooltipTrigger>
+                                <TooltipContent side="bottom" sideOffset={8}>
+                                    Pull fresh schema from database (keeps your layout)
+                                </TooltipContent>
+                            </Tooltip>
+                        )}
                         <Tooltip>
                             <TooltipTrigger asChild>
                                 <button
@@ -445,7 +537,7 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
                                     <LayoutGrid className="h-4 w-4" />
                                 </button>
                             </TooltipTrigger>
-                            <TooltipContent>Re-layout diagram</TooltipContent>
+                            <TooltipContent side="bottom" sideOffset={8}>Re-layout diagram</TooltipContent>
                         </Tooltip>
                         {["png", "svg"].map((format) => (
                             <button
@@ -533,7 +625,12 @@ const ERDiagramContent: React.FC<ERDiagramContentProps> = ({ nodeTypes, projectI
                         {selectedSchema !== "__all__" && ` • Schema: ${selectedSchema}`}
                         {selectedNodeId && ` • Selected: ${selectedNodeId.split('.')[1]}`}
                     </span>
-                    <span>Click table to highlight • Drag to pan • Scroll to zoom</span>
+                    <span className="flex items-center gap-3">
+                        {savedLayout && (
+                            <span className="text-muted-foreground/60">Layout saved</span>
+                        )}
+                        <span>Click table to highlight • Drag to pan • Scroll to zoom</span>
+                    </span>
                 </div>
             </div>
         </TooltipProvider >
diff --git a/src/hooks/useERDiagramData.ts b/src/hooks/useERDiagramData.ts
new file mode 100644
index 0000000..843f055
--- /dev/null
+++ b/src/hooks/useERDiagramData.ts
@@ -0,0 +1,245 @@
+import { useMemo, useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import { useFullSchema } from "@/hooks/useDbQueries";
+import {
+    useProjectSchema,
+    useProjectERDiagram,
+    projectKeys,
+} from "@/hooks/useProjectQueries";
+import { bridgeApi } from "@/services/bridgeApi";
+import type {
+    DatabaseSchemaDetails,
+    SchemaGroup,
+    TableSchemaDetails,
+    ColumnDetails,
+} from "@/types/database";
+import type {
+    SchemaSnapshot,
+    TableSnapshot,
+    ColumnSnapshot,
+    ERDiagramFile,
+    ERNode,
+} from "@/types/project";
+
+// ================================================================
+// useERDiagramData
+//
+// Smart data source for the ER diagram that:
+//
+// 1. OFFLINE-FIRST: Loads from project files (schema.json + er-diagram.json)
+//    even when the database is not connected.
+//
+// 2. LIVE FALLBACK: Falls back to live DB schema via useFullSchema when
+//    project files are empty or projectId is not provided.
+//
+// 3. MERGE: Merges saved ER layout positions (er-diagram.json) with the
+//    current schema data. Tables in schema but missing from ER layout
+//    are auto-placed. Tables in ER layout but removed from schema are
+//    ignored.
+//
+// 4. SYNC: Provides a `syncFromDatabase` callback that pulls fresh
+//    schema from the live DB, saves it to project files (schema.json),
+//    and does NOT touch the ER layout (er-diagram.json).
+// ================================================================
+
+/**
+ * Convert project SchemaSnapshot[] to DatabaseSchemaDetails
+ * (the format the ER diagram renderer expects)
+ */
+function snapshotToSchemaDetails(
+    dbName: string,
+    snapshots: SchemaSnapshot[]
+): DatabaseSchemaDetails {
+    return {
+        name: dbName,
+        schemas: snapshots.map(
+            (snap): SchemaGroup => ({
+                name: snap.name,
+                tables: snap.tables.map(
+                    (t): TableSchemaDetails => ({
+                        name: t.name,
+                        type: t.type || "BASE TABLE",
+                        columns: t.columns.map(
+                            (c): ColumnDetails => ({
+                                name: c.name,
+                                type: c.type,
+                                nullable: c.nullable,
+                                isPrimaryKey: c.isPrimaryKey,
+                                isForeignKey: c.isForeignKey,
+                                isUnique: c.isUnique,
+                                defaultValue: c.defaultValue,
+                            })
+                        ),
+                        // Snapshots don't store FK/index details — they're
+                        // only available from live DB. This is fine for
+                        // offline rendering (columns still show FK badges).
+                    })
+                ),
+            })
+        ),
+    };
+}
+
+/**
+ * Convert live SchemaGroup[] → SchemaSnapshot[] for saving
+ */
+function schemaGroupsToSnapshots(groups: SchemaGroup[]): SchemaSnapshot[] {
+    return groups.map((sg) => ({
+        name: sg.name,
+        tables: (sg.tables || []).map(
+            (t): TableSnapshot => ({
+                name: t.name,
+                type: t.type || "BASE TABLE",
+                columns: (t.columns || []).map(
+                    (c): ColumnSnapshot => ({
+                        name: c.name,
+                        type: c.type,
+                        nullable: c.nullable ?? true,
+                        isPrimaryKey: c.isPrimaryKey ?? false,
+                        isForeignKey: c.isForeignKey ?? false,
+                        defaultValue: c.defaultValue ?? null,
+                        isUnique: c.isUnique ?? false,
+                    })
+                ),
+            })
+        ),
+    }));
+}
+
+// ================================================================
+
+export interface UseERDiagramDataReturn {
+    /** The resolved schema data that the diagram should render */
+    schemaData: DatabaseSchemaDetails | null;
+
+    /** Saved ER layout (node positions, zoom, pan) — may be null */
+    savedLayout: ERDiagramFile | null;
+
+    /** True while initial data is still loading */
+    isLoading: boolean;
+
+    /** Data source: "live" = from DB, "project" = from project files */
+    dataSource: "live" | "project" | "none";
+
+    /** Whether live DB schema is available (for sync button state) */
+    hasLiveSchema: boolean;
+
+    /** Pull fresh schema from DB → save to project files → reload */
+    syncFromDatabase: () => Promise<void>;
+
+    /** Whether sync is currently in progress */
+    isSyncing: boolean;
+}
+
+export function useERDiagramData(
+    dbId: string | undefined,
+    projectId: string | null | undefined
+): UseERDiagramDataReturn {
+    const queryClient = useQueryClient();
+
+    // ---- Live DB schema ----
+    const {
+        data: liveSchema,
+        isLoading: liveLoading,
+        error: liveError,
+    } = useFullSchema(dbId);
+
+    // ---- Project files ----
+    const {
+        data: projectSchemaFile,
+        isLoading: projectSchemaLoading,
+    } = useProjectSchema(projectId ?? undefined);
+
+    const {
+        data: savedLayout,
+        isLoading: erLayoutLoading,
+    } = useProjectERDiagram(projectId ?? undefined);
+
+    // ---- Determine the best schema source ----
+    const { schemaData, dataSource } = useMemo(() => {
+        // Prefer live DB if available (most up-to-date, has FK/index data)
+        if (liveSchema && liveSchema.schemas?.some((s) => s.tables?.length)) {
+            return { schemaData: liveSchema, dataSource: "live" as const };
+        }
+
+        // Fall back to project cached schema (offline mode)
+        if (projectSchemaFile?.schemas?.length) {
+            const converted = snapshotToSchemaDetails(
+                projectSchemaFile.databaseId || "Database",
+                projectSchemaFile.schemas
+            );
+            if (converted.schemas.some((s) => s.tables?.length)) {
+                return { schemaData: converted, dataSource: "project" as const };
+            }
+        }
+
+        return { schemaData: null, dataSource: "none" as const };
+    }, [liveSchema, projectSchemaFile]);
+
+    // ---- Loading state ----
+    const isLoading = liveLoading || projectSchemaLoading || erLayoutLoading;
+    const hasLiveSchema = !!liveSchema && !liveError;
+
+    // ---- Sync from Database ----
+    const syncFromDatabase = useCallback(async () => {
+        if (!dbId) {
+            toast.error("No database connected");
+            return;
+        }
+
+        if (!projectId) {
+            toast.error("No project linked to this database");
+            return;
+        }
+
+        try {
+            // 1. Fetch fresh schema from live database
+            const freshSchema = await bridgeApi.getSchema(dbId);
+
+            if (!freshSchema?.schemas?.length) {
+                toast.warning("Database returned no schemas");
+                return;
+            }
+
+            // 2. Convert to snapshots and save to project schema.json
+            //    ❗ This does NOT touch er-diagram.json
+            const snapshots = schemaGroupsToSnapshots(freshSchema.schemas);
+            await bridgeApi.saveProjectSchema(projectId, snapshots);
+
+            // 3. Invalidate React Query caches to trigger re-render
+            queryClient.invalidateQueries({
+                queryKey: projectKeys.schema(projectId),
+            });
+            // Also refresh the live schema cache
+            queryClient.invalidateQueries({
+                queryKey: ["fullSchema", dbId],
+            });
+
+            toast.success("Schema synced from database", {
+                description: `${freshSchema.schemas.reduce(
+                    (acc, s) => acc + (s.tables?.length || 0),
+                    0
+                )} tables across ${freshSchema.schemas.length} schemas`,
+            });
+
+            console.debug("[ERDiagramData] Schema synced from DB, ER layout untouched");
+        } catch (err: any) {
+            console.error("[ERDiagramData] Sync failed:", err);
+            toast.error("Schema sync failed", {
+                description: err.message || "Could not pull schema from database",
+            });
+        }
+    }, [dbId, projectId, queryClient]);
+
+    return {
+        schemaData,
+        savedLayout: savedLayout ?? null,
+        isLoading,
+        dataSource,
+        hasLiveSchema,
+        syncFromDatabase,
+        // isSyncing is tracked by the caller if needed
+        isSyncing: false,
+    };
+}
diff --git a/src/lib/schemaTransformer.ts b/src/lib/schemaTransformer.ts
index ac99030..8699cc4 100644
--- a/src/lib/schemaTransformer.ts
+++ b/src/lib/schemaTransformer.ts
@@ -1,4 +1,5 @@
 import { ColumnDetails, DatabaseSchemaDetails, ForeignKeyInfo, TableSchemaDetails } from "@/types/database";
+import type { ERNode } from "@/types/project";
 import { Edge, MarkerType, Node } from "reactflow";
 import dagre from "dagre";
 
@@ -82,7 +83,8 @@ const applyDagreLayout = (
 
 export const transformSchemaToER = (
   schema: DatabaseSchemaDetails,
-  useDagreLayout: boolean = true
+  useDagreLayout: boolean = true,
+  savedLayout?: ERNode[] | null
 ): TransformedERData => {
   const nodes: Node<TableNodeData>[] = [];
   const edges: Edge<any>[] = [];
@@ -106,6 +108,12 @@ export const transformSchemaToER = (
     return map;
   };
 
+  // Build saved layout lookup: tableId → ERNode
+  const layoutMap = new Map<string, ERNode>();
+  if (savedLayout) {
+    savedLayout.forEach(n => layoutMap.set(n.tableId, n));
+  }
+
   // First pass: Create all nodes with enriched column data
   schema.schemas.forEach((schemaGroup) => {
     const schemaColor = SCHEMA_COLORS[schemaGroup.name] || "#6B7280";
@@ -124,9 +132,10 @@ export const transformSchemaToER = (
         };
       });
 
-      // Grid fallback position
-      const x = (nodeIndex % 3) * 350;
-      const y = Math.floor(nodeIndex / 3) * 350;
+      // Use saved position if available, otherwise grid fallback
+      const savedNode = layoutMap.get(tableName);
+      const x = savedNode ? savedNode.x : (nodeIndex % 3) * 350;
+      const y = savedNode ? savedNode.y : Math.floor(nodeIndex / 3) * 350;
 
       nodes.push({
         id: tableName,
@@ -220,8 +229,11 @@ export const transformSchemaToER = (
     });
   });
 
-  // Apply Dagre layout if enabled and there are edges
-  const layoutedNodes = useDagreLayout && edges.length > 0 
+  // Apply Dagre layout when:
+  //  - Dagre is requested AND there are edges
+  //  - AND there is NO saved layout (would overwrite user-saved positions)
+  const hasSavedPositions = savedLayout && savedLayout.length > 0;
+  const layoutedNodes = useDagreLayout && edges.length > 0 && !hasSavedPositions
     ? applyDagreLayout(nodes, edges, "LR")
     : nodes;
 

From b6e2b9b0d726d50544358b0a80230c80989576d7 Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 22:55:33 +0530
Subject: [PATCH 5/9] feat: implement schema explorer data handling with
 offline support and live sync

---
 .../schema-explorer/SchemaExplorerPanel.tsx   | 101 ++++++++---
 src/hooks/useERDiagramData.ts                 |  71 +-------
 src/hooks/useSchemaExplorerData.ts            | 161 ++++++++++++++++++
 src/lib/schemaConverters.ts                   |  81 +++++++++
 src/pages/DatabaseDetails.tsx                 |   2 +-
 5 files changed, 321 insertions(+), 95 deletions(-)
 create mode 100644 src/hooks/useSchemaExplorerData.ts
 create mode 100644 src/lib/schemaConverters.ts

diff --git a/src/components/schema-explorer/SchemaExplorerPanel.tsx b/src/components/schema-explorer/SchemaExplorerPanel.tsx
index 24b665e..7ff4692 100644
--- a/src/components/schema-explorer/SchemaExplorerPanel.tsx
+++ b/src/components/schema-explorer/SchemaExplorerPanel.tsx
@@ -1,9 +1,10 @@
 import { useState, useEffect } from "react";
 import { toast } from "sonner";
-import { AlertCircle, RefreshCw } from "lucide-react";
+import { AlertCircle, RefreshCw, Download, Wifi, WifiOff } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Spinner } from "@/components/ui/spinner";
-import { useFullSchema, useInvalidateCache } from "@/hooks/useDbQueries";
+import { useInvalidateCache } from "@/hooks/useDbQueries";
+import { useSchemaExplorerData } from "@/hooks/useSchemaExplorerData";
 import { ColumnDetails, DatabaseSchemaDetails, SchemaGroup, TableSchemaDetails } from "@/types/database";
 import TreeViewPanel from "@/components/schema-explorer/TreeViewPanel";
 import SchemaExplorerHeader from "@/components/schema-explorer/SchemaExplorerHeader";
@@ -27,19 +28,23 @@ interface DatabaseSchema extends DatabaseSchemaDetails {
 
 interface SchemaExplorerPanelProps {
     dbId: string;
+    projectId?: string | null;
 }
 
-export default function SchemaExplorerPanel({ dbId }: SchemaExplorerPanelProps) {
-    // Use React Query for schema data (cached!)
+export default function SchemaExplorerPanel({ dbId, projectId }: SchemaExplorerPanelProps) {
+    // Offline-first data source: prefers live DB, falls back to project files
     const {
-        data: schemaData,
+        schemaData,
         isLoading,
-        error: queryError,
-        refetch
-    } = useFullSchema(dbId);
+        dataSource,
+        hasLiveSchema,
+        syncFromDatabase,
+        refetch,
+    } = useSchemaExplorerData(dbId, projectId);
 
+    const [isSyncing, setIsSyncing] = useState(false);
     const { invalidateDatabase } = useInvalidateCache();
-    const error = queryError ? (queryError as Error).message : null;
+    const error = dataSource === "none" && !isLoading ? "No schema data available" : null;
 
     const [expandedSchemas, setExpandedSchemas] = useState<Set<string>>(new Set());
     const [expandedTables, setExpandedTables] = useState<Set<string>>(new Set());
@@ -139,17 +144,34 @@ export default function SchemaExplorerPanel({ dbId }: SchemaExplorerPanelProps)
             <div className="h-full flex items-center justify-center bg-background">
                 <div className="text-center p-8 border border-destructive/30 rounded-xl bg-destructive/10 text-destructive">
                     <AlertCircle className="h-10 w-10 text-destructive mx-auto mb-4" />
-                    <h2 className="text-xl font-bold mb-2">Error</h2>
-                    <p className="text-sm text-muted-foreground">{error || "No schema data could be loaded."}</p>
-                    <Button
-                        onClick={() => {
-                            if (dbId) invalidateDatabase(dbId);
-                            refetch();
-                        }}
-                        className="mt-4 bg-primary hover:bg-primary/90 text-white shadow-md shadow-primary/30"
-                    >
-                        <RefreshCw className="h-4 w-4 mr-2" /> Retry Load
-                    </Button>
+                    <h2 className="text-xl font-bold mb-2">No Schema Available</h2>
+                    <p className="text-sm text-muted-foreground mb-1">{typeof error === "string" ? error : "No schema data could be loaded."}</p>
+                    <p className="text-xs text-muted-foreground mb-4">Connect to a database or sync schema to use offline.</p>
+                    <div className="flex gap-2 justify-center">
+                        <Button
+                            onClick={() => {
+                                if (dbId) invalidateDatabase(dbId);
+                                refetch();
+                            }}
+                            variant="outline"
+                            size="sm"
+                        >
+                            <RefreshCw className="h-4 w-4 mr-2" /> Retry
+                        </Button>
+                        {projectId && (
+                            <Button
+                                onClick={async () => {
+                                    setIsSyncing(true);
+                                    try { await syncFromDatabase(); } finally { setIsSyncing(false); }
+                                }}
+                                size="sm"
+                                disabled={isSyncing || !hasLiveSchema}
+                            >
+                                {isSyncing ? <Spinner className="h-4 w-4 mr-2" /> : <Download className="h-4 w-4 mr-2" />}
+                                Sync from Database
+                            </Button>
+                        )}
+                    </div>
                 </div>
             </div>
         );
@@ -191,10 +213,41 @@ export default function SchemaExplorerPanel({ dbId }: SchemaExplorerPanelProps)
             {/* Footer */}
             <div className="border-t border-border bg-card px-4 py-2">
                 <div className="container mx-auto flex items-center justify-between text-xs text-muted-foreground">
-                    <span>
-                        {schemaData?.schemas?.length} Schemas • {schemaData?.schemas?.flatMap(s => s.tables).length} Tables
-                    </span>
-                    <span>Click table to highlight • Drag to pan • Scroll to zoom</span>
+                    <div className="flex items-center gap-3">
+                        <span>
+                            {schemaData?.schemas?.length} Schemas • {schemaData?.schemas?.flatMap(s => s.tables).length} Tables
+                        </span>
+                        {/* Data source badge */}
+                        {dataSource === "live" ? (
+                            <span className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded-full text-[10px] font-medium bg-emerald-500/15 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20">
+                                <Wifi className="h-2.5 w-2.5" />
+                                Live
+                            </span>
+                        ) : dataSource === "project" ? (
+                            <span className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded-full text-[10px] font-medium bg-amber-500/15 text-amber-600 dark:text-amber-400 border border-amber-500/20">
+                                <WifiOff className="h-2.5 w-2.5" />
+                                Offline
+                            </span>
+                        ) : null}
+                    </div>
+                    <div className="flex items-center gap-2">
+                        {dataSource === "project" && hasLiveSchema && (
+                            <Button
+                                variant="ghost"
+                                size="sm"
+                                className="h-6 text-xs px-2"
+                                onClick={async () => {
+                                    setIsSyncing(true);
+                                    try { await syncFromDatabase(); } finally { setIsSyncing(false); }
+                                }}
+                                disabled={isSyncing}
+                            >
+                                {isSyncing ? <Spinner className="h-3 w-3 mr-1" /> : <Download className="h-3 w-3 mr-1" />}
+                                Sync
+                            </Button>
+                        )}
+                        <span>Click table to highlight • Drag to pan • Scroll to zoom</span>
+                    </div>
                 </div>
             </div>
         </div>
diff --git a/src/hooks/useERDiagramData.ts b/src/hooks/useERDiagramData.ts
index 843f055..3a69f2c 100644
--- a/src/hooks/useERDiagramData.ts
+++ b/src/hooks/useERDiagramData.ts
@@ -8,16 +8,11 @@ import {
     projectKeys,
 } from "@/hooks/useProjectQueries";
 import { bridgeApi } from "@/services/bridgeApi";
+import { snapshotToSchemaDetails, schemaGroupsToSnapshots } from "@/lib/schemaConverters";
 import type {
     DatabaseSchemaDetails,
-    SchemaGroup,
-    TableSchemaDetails,
-    ColumnDetails,
 } from "@/types/database";
 import type {
-    SchemaSnapshot,
-    TableSnapshot,
-    ColumnSnapshot,
     ERDiagramFile,
     ERNode,
 } from "@/types/project";
@@ -43,70 +38,6 @@ import type {
 //    and does NOT touch the ER layout (er-diagram.json).
 // ================================================================
 
-/**
- * Convert project SchemaSnapshot[] to DatabaseSchemaDetails
- * (the format the ER diagram renderer expects)
- */
-function snapshotToSchemaDetails(
-    dbName: string,
-    snapshots: SchemaSnapshot[]
-): DatabaseSchemaDetails {
-    return {
-        name: dbName,
-        schemas: snapshots.map(
-            (snap): SchemaGroup => ({
-                name: snap.name,
-                tables: snap.tables.map(
-                    (t): TableSchemaDetails => ({
-                        name: t.name,
-                        type: t.type || "BASE TABLE",
-                        columns: t.columns.map(
-                            (c): ColumnDetails => ({
-                                name: c.name,
-                                type: c.type,
-                                nullable: c.nullable,
-                                isPrimaryKey: c.isPrimaryKey,
-                                isForeignKey: c.isForeignKey,
-                                isUnique: c.isUnique,
-                                defaultValue: c.defaultValue,
-                            })
-                        ),
-                        // Snapshots don't store FK/index details — they're
-                        // only available from live DB. This is fine for
-                        // offline rendering (columns still show FK badges).
-                    })
-                ),
-            })
-        ),
-    };
-}
-
-/**
- * Convert live SchemaGroup[] → SchemaSnapshot[] for saving
- */
-function schemaGroupsToSnapshots(groups: SchemaGroup[]): SchemaSnapshot[] {
-    return groups.map((sg) => ({
-        name: sg.name,
-        tables: (sg.tables || []).map(
-            (t): TableSnapshot => ({
-                name: t.name,
-                type: t.type || "BASE TABLE",
-                columns: (t.columns || []).map(
-                    (c): ColumnSnapshot => ({
-                        name: c.name,
-                        type: c.type,
-                        nullable: c.nullable ?? true,
-                        isPrimaryKey: c.isPrimaryKey ?? false,
-                        isForeignKey: c.isForeignKey ?? false,
-                        defaultValue: c.defaultValue ?? null,
-                        isUnique: c.isUnique ?? false,
-                    })
-                ),
-            })
-        ),
-    }));
-}
-
 // ================================================================
 
 export interface UseERDiagramDataReturn {
diff --git a/src/hooks/useSchemaExplorerData.ts b/src/hooks/useSchemaExplorerData.ts
new file mode 100644
index 0000000..618800a
--- /dev/null
+++ b/src/hooks/useSchemaExplorerData.ts
@@ -0,0 +1,161 @@
+import { useMemo, useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import { useFullSchema } from "@/hooks/useDbQueries";
+import {
+    useProjectSchema,
+    projectKeys,
+} from "@/hooks/useProjectQueries";
+import { bridgeApi } from "@/services/bridgeApi";
+import { snapshotToSchemaDetails, schemaGroupsToSnapshots } from "@/lib/schemaConverters";
+import type { DatabaseSchemaDetails } from "@/types/database";
+
+// ================================================================
+// useSchemaExplorerData
+//
+// Smart data source for the Schema Explorer that:
+//
+// 1. OFFLINE-FIRST: Loads from project files (schema.json) even
+//    when the database is not connected.
+//
+// 2. LIVE FALLBACK: Falls back to live DB schema via useFullSchema
+//    when project files are empty or projectId is not provided.
+//
+// 3. SYNC: Provides a `syncFromDatabase` callback that pulls fresh
+//    schema from the live DB and saves it to project files.
+// ================================================================
+
+export interface UseSchemaExplorerDataReturn {
+    /** The resolved schema data for the explorer to render */
+    schemaData: DatabaseSchemaDetails | null;
+
+    /** True while initial data is loading */
+    isLoading: boolean;
+
+    /** Data source: "live" = from DB, "project" = from project files */
+    dataSource: "live" | "project" | "none";
+
+    /** Whether live DB schema is available (for sync button state) */
+    hasLiveSchema: boolean;
+
+    /** Pull fresh schema from DB → save to project files → reload */
+    syncFromDatabase: () => Promise<void>;
+
+    /** Refetch from existing source (not a DB sync — just re-queries) */
+    refetch: () => void;
+}
+
+export function useSchemaExplorerData(
+    dbId: string | undefined,
+    projectId: string | null | undefined
+): UseSchemaExplorerDataReturn {
+    const queryClient = useQueryClient();
+
+    // ---- Live DB schema ----
+    const {
+        data: liveSchema,
+        isLoading: liveLoading,
+        error: liveError,
+        refetch: refetchLive,
+    } = useFullSchema(dbId);
+
+    // ---- Project files ----
+    const {
+        data: projectSchemaFile,
+        isLoading: projectSchemaLoading,
+        refetch: refetchProject,
+    } = useProjectSchema(projectId ?? undefined);
+
+    // ---- Determine the best schema source ----
+    const { schemaData, dataSource } = useMemo(() => {
+        // Prefer live DB if available (most up-to-date, has FK/index data)
+        if (liveSchema && liveSchema.schemas?.some((s) => s.tables?.length)) {
+            return { schemaData: liveSchema, dataSource: "live" as const };
+        }
+
+        // Fall back to project cached schema (offline mode)
+        if (projectSchemaFile?.schemas?.length) {
+            const converted = snapshotToSchemaDetails(
+                projectSchemaFile.databaseId || "Database",
+                projectSchemaFile.schemas
+            );
+            if (converted.schemas.some((s) => s.tables?.length)) {
+                return { schemaData: converted, dataSource: "project" as const };
+            }
+        }
+
+        return { schemaData: null, dataSource: "none" as const };
+    }, [liveSchema, projectSchemaFile]);
+
+    // ---- Loading state ----
+    const isLoading = liveLoading || projectSchemaLoading;
+    const hasLiveSchema = !!liveSchema && !liveError;
+
+    // ---- Refetch from current source ----
+    const refetch = useCallback(() => {
+        if (dataSource === "live") {
+            refetchLive();
+        } else if (dataSource === "project") {
+            refetchProject();
+        } else {
+            refetchLive();
+            refetchProject();
+        }
+    }, [dataSource, refetchLive, refetchProject]);
+
+    // ---- Sync from Database ----
+    const syncFromDatabase = useCallback(async () => {
+        if (!dbId) {
+            toast.error("No database connected");
+            return;
+        }
+
+        if (!projectId) {
+            toast.error("No project linked to this database");
+            return;
+        }
+
+        try {
+            // 1. Fetch fresh schema from live database
+            const freshSchema = await bridgeApi.getSchema(dbId);
+
+            if (!freshSchema?.schemas?.length) {
+                toast.warning("Database returned no schemas");
+                return;
+            }
+
+            // 2. Convert to snapshots and save to project schema.json
+            const snapshots = schemaGroupsToSnapshots(freshSchema.schemas);
+            await bridgeApi.saveProjectSchema(projectId, snapshots);
+
+            // 3. Invalidate React Query caches to trigger re-render
+            queryClient.invalidateQueries({
+                queryKey: projectKeys.schema(projectId),
+            });
+            queryClient.invalidateQueries({
+                queryKey: ["fullSchema", dbId],
+            });
+
+            toast.success("Schema synced from database", {
+                description: `${freshSchema.schemas.reduce(
+                    (acc, s) => acc + (s.tables?.length || 0),
+                    0
+                )} tables across ${freshSchema.schemas.length} schemas`,
+            });
+        } catch (err: any) {
+            console.error("[SchemaExplorerData] Sync failed:", err);
+            toast.error("Schema sync failed", {
+                description: err.message || "Could not pull schema from database",
+            });
+        }
+    }, [dbId, projectId, queryClient]);
+
+    return {
+        schemaData,
+        isLoading,
+        dataSource,
+        hasLiveSchema,
+        syncFromDatabase,
+        refetch,
+    };
+}
diff --git a/src/lib/schemaConverters.ts b/src/lib/schemaConverters.ts
new file mode 100644
index 0000000..10c14ad
--- /dev/null
+++ b/src/lib/schemaConverters.ts
@@ -0,0 +1,81 @@
+import type {
+    DatabaseSchemaDetails,
+    SchemaGroup,
+    TableSchemaDetails,
+    ColumnDetails,
+} from "@/types/database";
+import type {
+    SchemaSnapshot,
+    TableSnapshot,
+    ColumnSnapshot,
+} from "@/types/project";
+
+// ================================================================
+// Shared converters between project snapshot format and live DB format.
+// Used by useERDiagramData, useSchemaExplorerData, and useProjectSync.
+// ================================================================
+
+/**
+ * Convert project SchemaSnapshot[] → DatabaseSchemaDetails
+ * (the format that ER diagram and Schema Explorer expect)
+ *
+ * Note: Snapshots don't store FK/index details — those are only
+ * available from a live DB. Columns still carry isPrimaryKey /
+ * isForeignKey flags for badge rendering.
+ */
+export function snapshotToSchemaDetails(
+    dbName: string,
+    snapshots: SchemaSnapshot[]
+): DatabaseSchemaDetails {
+    return {
+        name: dbName,
+        schemas: snapshots.map(
+            (snap): SchemaGroup => ({
+                name: snap.name,
+                tables: snap.tables.map(
+                    (t): TableSchemaDetails => ({
+                        name: t.name,
+                        type: t.type || "BASE TABLE",
+                        columns: t.columns.map(
+                            (c): ColumnDetails => ({
+                                name: c.name,
+                                type: c.type,
+                                nullable: c.nullable,
+                                isPrimaryKey: c.isPrimaryKey,
+                                isForeignKey: c.isForeignKey,
+                                isUnique: c.isUnique,
+                                defaultValue: c.defaultValue,
+                            })
+                        ),
+                    })
+                ),
+            })
+        ),
+    };
+}
+
+/**
+ * Convert live SchemaGroup[] → SchemaSnapshot[] for saving to project files
+ */
+export function schemaGroupsToSnapshots(groups: SchemaGroup[]): SchemaSnapshot[] {
+    return groups.map((sg) => ({
+        name: sg.name,
+        tables: (sg.tables || []).map(
+            (t): TableSnapshot => ({
+                name: t.name,
+                type: t.type || "BASE TABLE",
+                columns: (t.columns || []).map(
+                    (c): ColumnSnapshot => ({
+                        name: c.name,
+                        type: c.type,
+                        nullable: c.nullable ?? true,
+                        isPrimaryKey: c.isPrimaryKey ?? false,
+                        isForeignKey: c.isForeignKey ?? false,
+                        defaultValue: c.defaultValue ?? null,
+                        isUnique: c.isUnique ?? false,
+                    })
+                ),
+            })
+        ),
+    }));
+}
diff --git a/src/pages/DatabaseDetails.tsx b/src/pages/DatabaseDetails.tsx
index e73678f..21860a4 100644
--- a/src/pages/DatabaseDetails.tsx
+++ b/src/pages/DatabaseDetails.tsx
@@ -144,7 +144,7 @@ const DatabaseDetail = () => {
       case 'query-builder':
         return <QueryBuilderPanel dbId={dbId || ''} />;
       case 'schema-explorer':
-        return <SchemaExplorerPanel dbId={dbId || ''} />;
+        return <SchemaExplorerPanel dbId={dbId || ''} projectId={projectId} />;
       case 'er-diagram':
         return <ERDiagramPanel projectId={projectId} />;
       case 'data':

From f577e14a9c05fbcb7b5a78c43850e3e99d09528b Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 23:15:26 +0530
Subject: [PATCH 6/9] Update bridge/src/services/projectStore.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 bridge/src/services/projectStore.ts | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/bridge/src/services/projectStore.ts b/bridge/src/services/projectStore.ts
index d8cf8ce..2a07d77 100644
--- a/bridge/src/services/projectStore.ts
+++ b/bridge/src/services/projectStore.ts
@@ -302,9 +302,24 @@ export class ProjectStore {
         if (!meta) return null;
 
         const now = new Date().toISOString();
+
+        // Whitelist only allowed fields from updates to avoid overwriting
+        // sensitive metadata (e.g., id, databaseId, version, timestamps).
+        const { name, description, defaultSchema } = updates;
+        const safeUpdates: Partial<Pick<ProjectMetadata, "name" | "description" | "defaultSchema">> = {};
+        if (name !== undefined) {
+            safeUpdates.name = name;
+        }
+        if (description !== undefined) {
+            safeUpdates.description = description;
+        }
+        if (defaultSchema !== undefined) {
+            safeUpdates.defaultSchema = defaultSchema;
+        }
+
         const updated: ProjectMetadata = {
             ...meta,
-            ...updates,
+            ...safeUpdates,
             updatedAt: now,
         };
 

From 949f7851bb8670f6a87bd01e372eb54b3b83fc43 Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 23:16:03 +0530
Subject: [PATCH 7/9] Update bridge/src/services/projectStore.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 bridge/src/services/projectStore.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bridge/src/services/projectStore.ts b/bridge/src/services/projectStore.ts
index 2a07d77..115091a 100644
--- a/bridge/src/services/projectStore.ts
+++ b/bridge/src/services/projectStore.ts
@@ -163,7 +163,7 @@ export class ProjectStore {
     private async writeJSON(filePath: string, data: unknown): Promise<void> {
         const dir = path.dirname(filePath);
         ensureDir(dir);
-        const tmp = filePath + ".tmp";
+        const tmp = `${filePath}.${process.pid}.${uuidv4()}.tmp`;
         await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
         await fs.rename(tmp, filePath);
     }

From 1054fc0062b9271aca907ec940e578c5dc0853df Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 23:16:40 +0530
Subject: [PATCH 8/9] Update src/pages/Projects.tsx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/pages/Projects.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/pages/Projects.tsx b/src/pages/Projects.tsx
index 920ff37..701147f 100644
--- a/src/pages/Projects.tsx
+++ b/src/pages/Projects.tsx
@@ -114,7 +114,9 @@ const Projects = () => {
             a.href = url;
             a.download = `${bundle.metadata.name.replace(/\s+/g, "-").toLowerCase()}-export.json`;
             a.click();
-            URL.revokeObjectURL(url);
+            setTimeout(() => {
+                URL.revokeObjectURL(url);
+            }, 0);
             toast.success("Project exported");
         } catch (err: any) {
             toast.error("Export failed", { description: err.message });

From be56b92cf27947f6540ddfb1b2a4ed0b235cb982 Mon Sep 17 00:00:00 2001
From: Yash <yashsaini18166@gmail.com>
Date: Tue, 10 Feb 2026 23:41:13 +0530
Subject: [PATCH 9/9] refactor schema transformation logic in useProjectSync
 hook

---
 src/hooks/useProjectSync.ts | 35 ++++-------------------------------
 1 file changed, 4 insertions(+), 31 deletions(-)

diff --git a/src/hooks/useProjectSync.ts b/src/hooks/useProjectSync.ts
index c5a2d96..c42ee8d 100644
--- a/src/hooks/useProjectSync.ts
+++ b/src/hooks/useProjectSync.ts
@@ -1,36 +1,9 @@
 import { useEffect, useRef, useCallback } from "react";
 import { bridgeApi } from "@/services/bridgeApi";
 import { useProjectByDatabaseId } from "@/hooks/useProjectQueries";
-import type { DatabaseSchemaDetails, SchemaGroup, TableSchemaDetails } from "@/types/database";
-import type { SchemaSnapshot, TableSnapshot, ColumnSnapshot, ERNode } from "@/types/project";
-
-// ==========================================
-// Schema data transformer
-// Live DB format → Project store format
-// ==========================================
-
-function transformToSchemaSnapshots(schemas: SchemaGroup[]): SchemaSnapshot[] {
-    return schemas.map((sg) => ({
-        name: sg.name,
-        tables: (sg.tables || []).map(
-            (t): TableSnapshot => ({
-                name: t.name,
-                type: t.type || "BASE TABLE",
-                columns: (t.columns || []).map(
-                    (c): ColumnSnapshot => ({
-                        name: c.name,
-                        type: c.type,
-                        nullable: c.nullable ?? true,
-                        isPrimaryKey: c.isPrimaryKey ?? false,
-                        isForeignKey: c.isForeignKey ?? false,
-                        defaultValue: c.defaultValue ?? null,
-                        isUnique: c.isUnique ?? false,
-                    })
-                ),
-            })
-        ),
-    }));
-}
+import { schemaGroupsToSnapshots } from "@/lib/schemaConverters";
+import type { DatabaseSchemaDetails } from "@/types/database";
+import type { ERNode } from "@/types/project";
 
 // ==========================================
 // Hook: useProjectSync
@@ -76,7 +49,7 @@ export function useProjectSync(
 
         if (fingerprint === lastSyncedSchemaRef.current) return;
 
-        const snapshots = transformToSchemaSnapshots(schemaData.schemas);
+        const snapshots = schemaGroupsToSnapshots(schemaData.schemas);
 
         // Fire-and-forget — sync in the background without blocking UI
         bridgeApi