No native modules, pod installs, or Expo prebuild steps are required. This is a pure web project. A Vite build pipeline is expected; if you are integrating into a non-Vite project, add path alias support (see setup below).

Project setup

1. Copy source files. Place the contents of source/ into src/ in your project root (or a subdirectory like src/chartdb/).

2. Configure path aliases. The source uses @/ to refer to src/. In tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@/*": ["src/*"]
       }
     }
   }
   

   In vite.config.ts:

   import { defineConfig } from 'vite';
   import react from '@vitejs/plugin-react';
   import path from 'path';
   
   export default defineConfig({
     plugins: [react()],
     resolve: {
       alias: { '@': path.resolve(__dirname, 'src') },
     },
   });
   

3. Set environment variables. Create a .env file:

   VITE_OPENAI_API_KEY=sk-...   # Optional: enables AI-powered DDL export
   

4. Entry point. Use src/main.tsx as the Vite entry point. It mounts <App /> from app.tsx into #root.

5. Styles. Import src/index.css and src/globals.css in your entry file or CSS bundle. Tailwind CSS is expected; ensure a tailwind.config.js covers the src/ directory.

6. TypeScript strictness. The source targets "strict": true. Loosen only if you encounter third-party type errors.

Public API

loadFromDatabaseMetadata

import { loadFromDatabaseMetadata } from '@/lib/data/import-metadata/import';
import { DatabaseType } from '@/lib/domain';

const diagram = await loadFromDatabaseMetadata({
    databaseType: DatabaseType.POSTGRESQL,
    databaseMetadata: metadata,      // DatabaseMetadata object from smart query result
    diagramNumber?: number,           // optional: used to name the diagram
    databaseEdition?: DatabaseEdition // optional: e.g. supabase, timescale
}): Promise<Diagram>

Use this when you have already executed the ChartDB "smart query" against a live database and received a DatabaseMetadata JSON object. It parses tables, relationships, custom types, views, and dependencies, then adjusts table positions for a clean initial layout.

hasCrossDialectSupport

import { hasCrossDialectSupport } from '@/lib/data/sql-export/cross-dialect';
import { DatabaseType } from '@/lib/domain';

function hasCrossDialectSupport(
    sourceDatabaseType: DatabaseType,
    targetDatabaseType: DatabaseType
): boolean

Call this before presenting dialect conversion options in your UI. Returns true only when a deterministic (non-AI) conversion path exists between the two database types. Currently, PostgreSQL → MySQL, MariaDB, and SQL Server are supported.

exportPostgreSQLToMySQL / exportPostgreSQLToMSSQL

import {
    exportPostgreSQLToMySQL,
    exportPostgreSQLToMSSQL,
} from '@/lib/data/sql-export/cross-dialect';

These functions perform deterministic cross-dialect DDL conversion from a PostgreSQL diagram to MySQL/MariaDB or SQL Server syntax, respectively. Use them when the user wants to migrate or compare schemas across database engines without requiring an OpenAI key.

Working examples

Scenario - Parse database metadata into a Diagram

You have the JSON output from ChartDB's smart query (run against a PostgreSQL database) and want to construct a Diagram object for rendering or further processing.

import { loadFromDatabaseMetadata } from '@/lib/data/import-metadata/import';
import { DatabaseType } from '@/lib/domain';
import type { DatabaseMetadata } from '@/lib/data/import-metadata/metadata-types/database-metadata';

const rawMetadata: DatabaseMetadata = JSON.parse(process.env.DB_METADATA_JSON!);

async function buildDiagram() {
    const diagram = await loadFromDatabaseMetadata({
        databaseType: DatabaseType.POSTGRESQL,
        databaseMetadata: rawMetadata,
        diagramNumber: 1,
    });

    console.log('Tables:', diagram.tables?.length);
    console.log('Relationships:', diagram.relationships?.length);
    return diagram;
}

buildDiagram().catch(console.error);

Scenario - Check and perform cross-dialect SQL export

Before showing a "Export to MySQL" button, verify the conversion is supported, then run it.

import {
    hasCrossDialectSupport,
    exportPostgreSQLToMySQL,
} from '@/lib/data/sql-export/cross-dialect';
import { DatabaseType } from '@/lib/domain';
import type { Diagram } from '@/lib/domain';

function exportDiagram(diagram: Diagram, target: DatabaseType): string | null {
    const source = DatabaseType.POSTGRESQL;

    if (!hasCrossDialectSupport(source, target)) {
        console.warn(`No deterministic conversion from ${source} to ${target}`);
        return null;
    }

    if (target === DatabaseType.MYSQL || target === DatabaseType.MARIADB) {
        return exportPostgreSQLToMySQL(diagram);
    }

    if (target === DatabaseType.SQL_SERVER) {
        return exportPostgreSQLToMSSQL(diagram);
    }

    return null;
}

Scenario - Import a raw SQL DDL string into a Diagram

Use the SQL import pipeline to parse a user-supplied DDL script (auto-detected dialect).

import { importSQL } from '@/lib/data/sql-import';
import { DatabaseType } from '@/lib/domain';

async function parseDDL(sql: string) {
    // importSQL auto-detects pg_dump, SQL Server, Oracle, MySQL, SQLite
    const diagram = await importSQL(sql, DatabaseType.POSTGRESQL);
    if (!diagram) {
        throw new Error('Failed to parse SQL DDL');
    }
    console.log('Parsed tables:', diagram.tables?.map(t => t.name));
    return diagram;
}

parseDDL(`
    CREATE TABLE users (
        id SERIAL PRIMARY KEY,
        email TEXT NOT NULL UNIQUE
    );
`).catch(console.error);

File walkthrough

• assets/ - All static image assets; database vendor logos in light/dark variants plus example and template screenshots.
• components/ - Reusable React UI components used across pages and dialogs.
• context/ - React contexts that hold global diagram state, storage, and configuration; wrap your app with these providers.
• dialogs/ - Self-contained dialog components for operations like import from SQL, export DDL, table editing.
• helmet/ - Page-level <Helmet> components for setting <title> and meta tags per route.
• hooks/ - Custom hooks abstracting diagram data queries and UI state (e.g., undo/redo, selected table).
• i18n/ - i18next initialization and all locale JSON files; add translations here.
• lib/ - The engine: lib/domain defines all core types; lib/data/sql-import parses SQL; lib/data/sql-export generates SQL; lib/data/import-metadata converts smart-query JSON to diagrams.
• pages/ - Route-level page components connected to the router.
• templates-data/ - Hardcoded schema templates (e.g., Airbnb, Akaunting) available in the template gallery.
• types/ - Shared TypeScript interfaces not tied to a specific module.
• app.tsx - Composes providers, router, and global layout.
• main.tsx - Vite entry; calls ReactDOM.createRoot.
• router.tsx - React Router createBrowserRouter configuration.
• polyfills.ts - Polyfills for older browser APIs.
• safari-compat.ts - Patches for Safari-specific rendering bugs.

Common pitfalls and fixes

• @/ alias not resolved at runtime - Ensure both tsconfig.json paths and vite.config.ts resolve.alias point @ to the same absolute src/ directory; one without the other causes silent failures.
• VITE_OPENAI_API_KEY missing causes AI export to silently fail - The key is optional but must be present in .env at build time; runtime injection does not work with Vite's import.meta.env baking.
• @dbml/core ESM/CJS interop errors - If bundling for Node.js (e.g., an Express backend using the import pipeline), set "type": "module" in your package.json or use a dynamic import() wrapper; @dbml/core ships ESM only.
• Tailwind classes missing in production - Add './src/**/*.{ts,tsx}' to tailwind.config.js content; the source uses Tailwind utility classes throughout and they will be purged if the path is not covered.
• adjustTablePositions returns empty array - This happens when tables is an empty array before relationships are built; ensure createTablesFromMetadata receives a valid DatabaseMetadata object with a non-empty tables key.
• Monaco Editor blank in SSR/Node context - @monaco-editor/react requires a browser DOM; do not import diagram editor page components in server-rendered code; use dynamic imports with ssr: false if using Next.js.

Vibe-coding prompt template

I have integrated the ChartDB source (chartdb@1.20.1) into my project under src/.
The USAGE.md file is at the root of this block and describes all real exports and file locations.

Please help me integrate ChartDB step by step into my existing [describe your project: e.g., "Express + React app"].

Context:
- Source lives in src/ with path alias @/ mapped to src/
- Core imports come from @/lib/domain, @/lib/data/import-metadata/import, @/lib/data/sql-import, @/lib/data/sql-export/cross-dialect
- Key functions: loadFromDatabaseMetadata, hasCrossDialectSupport, exportPostgreSQLToMySQL, exportPostgreSQLToMSSQL
- The app entry is src/main.tsx; providers are in src/context/

Tasks:
1. Wire the path alias in my vite.config.ts and tsconfig.json
2. Mount the ChartDB <App /> inside my existing React shell
3. Show me how to call loadFromDatabaseMetadata with a sample DatabaseMetadata payload
4. Add a UI button that calls hasCrossDialectSupport and, if true, calls exportPostgreSQLToMySQL and downloads the result as a .sql file
5. Point out any missing dependencies I need to install based on USAGE.md

Only use imports and function signatures documented in USAGE.md. Do not invent new APIs.

License and credit

ChartDB is released under the AGPL-3.0 license (GNU Affero General Public License v3.0). Any modifications to the source that are deployed as a network service must be made available to users under the same license. See source/LICENSE if present, or the upstream repository at https://github.com/chartdb/chartdb. The upstream npm package is user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.