Open Data Modelling Application

A domain-centric data modelling application built with React and Electron. Create data architectures, models, and flow diagrams entirely offline.

⚠️ IMPORTANT: This application currently only supports OFFLINE MODE.

Features

• Data Modelling: Conceptual, logical, and physical models with crow's feet notation
• Infinite Canvas: ReactFlow-based canvas for visualizing data models
• Git Integration (v3.0.0): Full Git version control - staging, commits, branches, stash, rebase, tags, blame
• GitHub Integration (v3.0.0): Pull requests, reviews, comments, merge with PAT and OAuth authentication
• Excalidraw Sketches (v2.5.0+): Freeform diagramming for architecture, dataflow, ER, sequence, flowchart, wireframe, and infrastructure diagrams
• Help Panel (v3.0.0): Searchable in-app documentation with keyboard shortcuts (F1, Cmd+?)
• Offline First: Works without backend; GitHub features available when authenticated
• Databricks Metric Views (v3.3.0): Standard and materialized metric views with dimensions, measures, filters, joins — analytical tab only
• Catalog, Schema & Resource Type (v3.4.0): Per-table catalog/schema fields with scoped uniqueness; Table/View/Materialized View resource type with canvas badges
• Import/Export: Support for ODCS, DBMV, SQL, AVRO, JSON Schema, and Protobuf formats
• Cross-Platform: Electron desktop app (macOS, Windows, Linux)
• Domain-Centric: Organize data models by business domains with systems, tables, relationships, BPMN processes, and DMN decisions
• Read-Only Viewer (v3.1.0): Separate Cloudflare Pages deployment for sharing private models via GitHub App proxy
• Decision Logs (SDK 1.13.6+): MADR-format Architecture Decision Records with status workflow
• Knowledge Base (SDK 1.13.6+): Documentation articles with types (Guide, Tutorial, Reference, etc.)

Prerequisites

• Node.js 20+ (LTS version)
• npm or pnpm
• Rust and wasm-pack (for building WASM SDK)

  # Install Rust
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  
  # Install wasm-pack
  cargo install wasm-pack

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. After cloning, run:

cd frontend
npm install

The hooks will automatically run on git commit and check:

• Linting (ESLint) - Auto-fixes issues
• Formatting (Prettier) - Ensures consistent code style
• Type Checking (TypeScript) - Validates types
• Tests (Vitest) - Runs unit and integration tests
• Security Audit (npm audit) - Checks for vulnerabilities (non-blocking)

See frontend/PRE_COMMIT_SETUP.md for detailed setup instructions.

Quick Start

Option 1: Docker (Web Version)

Build and run the web version using Docker:

# Build and start the frontend service
docker-compose up -d

# View logs
docker-compose logs -f frontend

# Access the application
# Web: http://localhost:5173

See docker/README.md for detailed Docker setup instructions.

Option 2: Local Development (Electron App)

Installation

# Install dependencies
cd frontend
npm install

# Build WASM SDK (required for offline mode)
npm run build:wasm

Development

# Start Electron app in development mode
cd frontend
npm run electron:dev

# This will:
# 1. Build Electron main/preload scripts
# 2. Start Vite dev server (http://localhost:5173)
# 3. Launch Electron app connected to dev server

Note: The development script (scripts/dev.sh) will automatically:

• Check Node.js version
• Install dependencies if needed
• Build WASM SDK if not present
• Start the development server

Building WASM SDK

The WASM SDK is automatically built before the main build, but you can build it manually:

npm run build:wasm

This will:

1. Build the Rust SDK as a WASM module
2. Copy the WASM files to frontend/public/wasm/
3. Make them available for offline mode

Testing

# Run all tests
npm test

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Type check
npm run type-check

# Lint
npm run lint

Building Electron Application

See frontend/ELECTRON_BUILD_GUIDE.md for detailed build instructions.

Quick build commands:

cd frontend

# Build WASM SDK (required)
npm run build:wasm

# Build frontend
npm run build

# Build Electron main/preload scripts
npm run build:electron

# Build production Electron app (creates installers)
npm run electron:build

This creates platform-specific installers:

• macOS: .dmg or .pkg files
• Windows: .exe or .msi files
• Linux: .AppImage or .deb files

Project Structure

frontend/
├── src/
│   ├── components/     # React components
│   ├── services/       # API, SDK, storage services
│   ├── stores/         # Zustand state management
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   └── pages/          # Page components
├── tests/              # Test files
├── electron/           # Electron-specific code
├── public/
│   └── wasm/           # WASM SDK files (built from data-modelling-sdk)
├── scripts/
│   ├── build-wasm.sh   # Build script for WASM SDK
│   └── dev.sh          # Development server script
└── package.json

Environment Variables

Note: Since the app operates in offline mode only, environment variables are not required. The app uses local file storage and WASM SDK for all operations.

WASM SDK Integration

The application uses a WASM build of the data-modelling-sdk (version 2.4.0) for offline functionality:

1. SDK Version: Requires @offenedatenmodellierung/data-modelling-sdk = "^2.4.0" npm package
2. Build Process: The SDK is built using wasm-pack and copied to public/wasm/
3. Automatic Build: Runs automatically before npm run build via prebuild script
4. Development: Can be built manually with npm run build:wasm
5. Fallback: If WASM SDK is not available, the app uses a JavaScript YAML parser fallback

Note: The SDK must be version 2.4.0 or compatible for full DBMV and sketch support.

SDK 2.4.0 Features

The SDK 2.4.0 release includes these capabilities:

• Excalidraw Sketches (NEW in v2.5.0): Freeform diagramming integration

  • Sketch types: architecture, dataflow, entity-relationship, sequence, flowchart, wireframe, concept, infrastructure
  • Status workflow: draft → review → published → archived
  • Link sketches to tables, systems, decisions, and knowledge articles
  • Export to PNG, SVG, and JSON formats
  • v3.0.1: Fixed sketch persistence to disk and GitHub sync

• Decision Logs (MADR): Architecture Decision Records following the MADR format

  • Status workflow: Draft → Proposed → Accepted/Rejected → Superseded
  • Categories: Architecture, Technology, Process, Security, Data, Integration
  • Related decisions and knowledge articles linking
  • Markdown export

• Knowledge Base: Documentation and knowledge management

  • Article types: Guide, Tutorial, Reference, Concept, Troubleshooting, Runbook
  • Publishing workflow: Draft → Review → Published → Archived
  • Full-text search across articles
  • Related articles and decisions linking

See the following documentation for more details:

• Configuration Guide
• Decision Logs Guide
• Knowledge Base Guide

Git/GitHub Integration (v3.0.0)

Full Git version control and GitHub integration for collaborative workflows:

Git Features (Electron Only):

• Repository initialization and status monitoring
• File staging with diff preview
• Commit history with full diff display
• Branch management (create, switch, delete, merge)
• Remote operations (push, pull, fetch)
• Stash management (save, apply, pop, drop)
• Advanced: cherry-pick, rebase, tags, blame

GitHub Features (Browser + Electron):

• Personal Access Token (PAT) authentication
• GitHub App OAuth authentication
• Pull request management:
  • List and view pull requests
  • Create PRs with template support
  • Add comments and review comments
  • Submit reviews (approve, request changes)
  • Merge PRs (merge, squash, rebase)
  • Conflict detection before merge
• Issue viewing and management

Authentication Options:

1. PAT (Personal Access Token): Best for individual users

   • Go to GitHub → Settings → Developer settings → Personal access tokens
   • Generate token with repo scope
   • Paste in the app's GitHub connection dialog

2. GitHub App (OAuth): Best for organizations

   • Admin creates GitHub App in org settings
   • Configure app credentials in the application
   • Users authenticate via OAuth flow

Help System (v3.0.0)

Press F1 or Cmd+? (Ctrl+? on Windows) to open the searchable help panel:

• Comprehensive Git/GitHub documentation
• Getting started guides
• Keyboard shortcuts reference
• Contextual help based on current view

Read-Only Viewer Mode (v3.1.0)

Deploy a separate, read-only instance of the modeller to share private data models with stakeholders. The viewer uses the same codebase with build-time feature flags — no fork required.

Key Features:

• Locked to a single private GitHub repo (configured at build time)
• Server-side GitHub App authentication via Cloudflare Pages Function — no credentials in the browser
• GET-only proxy restricts API access to the configured repository
• All editing UI hidden: no save, commit, create, delete, or drag-and-drop
• Canvas is view-only: click to select and inspect, but no modifications
• Access controlled via Cloudflare Access IP restrictions

Deployment:

1. Create a GitHub App with contents:read + metadata:read permissions
2. Create a Cloudflare Pages project with build command: cd frontend && bash cloudflare-build-viewer.sh
3. Set secrets: GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_INSTALLATION_ID
4. Set env vars: VIEWER_OWNER, VIEWER_REPO, VIEWER_BRANCH, VIEWER_WORKSPACE_PATH
5. Attach a Cloudflare Access policy with IP allowlist

See CHANGELOG.md for full details.

Offline-First Architecture

The application operates offline-first with optional GitHub connectivity:

Core Features (Fully Offline):

• WASM SDK: Direct use of data-modelling-sdk compiled to WebAssembly
• Local File System: Electron file system access for saving/loading workspaces
• Git Operations: Full local Git via simple-git (Electron only)

GitHub Features (Requires Authentication):

• Pull request management
• Code reviews and comments
• Remote repository operations
• Issue tracking

Note: All core data modelling functionality works completely offline. GitHub integration is optional and only needed for collaborative workflows.

CI/CD

The GitHub Actions workflow (.github/workflows/build-release.yml):

• Lint and Format: Runs ESLint and Prettier checks
• Test: Runs test suite with 95% coverage requirement
• Build: Builds WASM SDK, frontend, and Electron applications for all platforms
• Release: Creates GitHub releases with installers when tags are pushed
• Security: Performs npm security audits

The workflow runs on:

• Push to main or develop branches
• Pull requests to main or develop
• Tags starting with v* (creates release)
• Manual workflow dispatch

Building from Source

Prerequisites

• Node.js 20+ (LTS version recommended)
• Rust and wasm-pack (for building WASM SDK)

  # Install Rust
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  
  # Install wasm-pack
  cargo install wasm-pack

Build Steps

1. Clone the repository

   git clone <repository-url>
   cd dm

2. Install dependencies

   cd frontend
   npm install

3. Build WASM SDK

   npm run build:wasm

   Note: This requires the data-modelling-sdk repository to be accessible. See frontend/ELECTRON_BUILD_GUIDE.md for details.

4. Build Electron application

   npm run build
   npm run build:electron
   npm run electron:build

See frontend/ELECTRON_BUILD_GUIDE.md for complete build instructions.

Development

Rebuilding Example Workspaces

The application includes bundled example workspaces in frontend/public/examples/. When adding, modifying, or removing example workspaces, you must rebuild the examples index.

cd frontend

# Rebuild the examples index (scans public/examples/ and updates index.json)
npm run rebuild:examples

# Rebuild with ODCS migration (converts legacy 'custom' to 'customProperties' array format)
npm run rebuild:examples:migrate

# Preview changes without modifying files
node scripts/rebuild-examples.cjs --dry-run

# Verbose output for debugging
node scripts/rebuild-examples.cjs --verbose

The rebuild script:

1. Scans all subdirectories in public/examples/
2. Parses workspace files to extract metadata (name, description)
3. Counts file types (ODCS, ODPS, BPMN, KB, ADR) for feature lists
4. Generates public/examples/index.json used by the application

Adding a new example workspace:

1. Create a new folder in frontend/public/examples/ (e.g., my-example/)
2. Add a .workspace.yaml file with workspace metadata
3. Add ODCS, ODPS, BPMN, or other supported files
4. Run npm run rebuild:examples to update the index
5. Test by loading the app and checking the Home page workspace list

ODCS Migration Script

For migrating ODCS files in external directories (outside the app):

cd frontend

# Migrate ODCS files in a directory
node scripts/migrate-odcs.cjs --path /path/to/odcs/files

# Merge contracts by system (uses workspace.yaml for system-contract mapping)
node scripts/migrate-odcs.cjs --path /path/to/workspace --merge-by-system

# Preview changes without modifying files
node scripts/migrate-odcs.cjs --path /path/to/files --dry-run

Contributing

1. Follow the project constitution (.specify/memory/constitution.md)
2. Maintain 95% test coverage
3. No partial implementations or TODOs without explicit authorization
4. Follow conventional commit messages
5. Run tests before committing: npm test

Changelog

See CHANGELOG.md for a detailed list of changes.

License

MIT License

Copyright (c) 2026 OffeneDatenmodellierung