Architecture

Titanbase is a local-first visual schema designer. It separates three concerns: the editor that you interact with, the core that owns the schema model and validation, and the exporters that turn a schema into target-specific output. The .titan.json file is your source of truth.

Visual Editor  →  .titan.json  →  Exporters
                  (your file)      (pure transforms)

Each layer is independent:

• The editor is one way to create a .titan.json — you can also write or generate it programmatically.
• @titanbase/core owns the schema types, normalization, validation, and diagnostics.
• Exporters are pure transforms: a TitanSchema in, deterministic output (with warnings) out. No network calls, no state.

The local product never requires the cloud.

@titanbase/core#

@titanbase/core is the heart of the project. It owns:

• the schema types (TitanSchema and friends) that define the .titan.json structure;
• the Zod schemas that parse and structurally validate a file;
• diagnostics — semantic checks beyond structural parsing (see Diagnostics);
• normalization — a canonical form that trims strings and sorts tables, enums, and relations by name;
• the schema diff engine (diffSchemas) that powers Compare and migration drafts (see Schema diff & migrations);
• the shared export result types (ExportFile, ExportWarning, ExportResult) that exporters return.

React and editor code display schema state and diagnostics, but they do not own core validation logic — that lives in @titanbase/core so every consumer (editor and exporters) shares one source of truth.

The schema model#

The schema describes a relational database in a target-oriented but portable way:

• Tables hold columns and indexes.
• Columns are typed fields with nullable, primaryKey, unique, and an optional string default.
• Relations are foreign-key relationships with a cardinality and referential actions. They support composite (multi-column) keys.
• Enums are shared value lists, referenced by a column's type.
• A top-level dialect (postgres, mysql, sqlite, or generic) tells diagnostics which types to recognize.
• metadata.editor holds editor-only data such as table positions, separate from the schema itself.

See the full .titan.json format reference and the type system.

Exporters#

Each target is an independent function that takes a TitanSchema and returns its output:

import type { TitanSchema, ExportResult } from "@titanbase/core";

// Mermaid, Prisma, and Drizzle return ExportResult:
//   { files: { path: string; content: string }[]; warnings: ExportWarning[] }
export function exportMermaid(schema: TitanSchema): ExportResult;

Exporters are pure functions. Their responsibilities are type mapping, output generation, applying constraints and defaults where the target supports them, and emitting warnings for features the target cannot represent. See Exporters and the Plugin API.

Visual editor#

The editor is a React application with a canvas view of the schema. Editor state is the schema — every visual action mutates the schema, and the canvas renders from it.

• Save serializes the schema to .titan.json.
• Export runs the same schema the canvas displays through an exporter.
• Visual-only data (table positions) lives in metadata.editor, keyed by table id, so layout never pollutes the schema's meaning.

Packages#

These packages are implemented today:

Planned packages#

These are on the roadmap and not implemented yet: