Conduit is a local-first desktop application for designing data systems as typed architecture graphs.

It is built for:

• entity-relationship diagrams
• ingestion and transformation pipelines
• event-driven architectures
• storage and indexing layers
• data lineage
• canonical-versus-derived state modeling
• architecture validation
• implementation planning

Every box and arrow on the canvas is backed by structured data. The diagram is a view of the architecture, not the authoritative architecture itself.

Current Status

Conduit is an early working prototype.

Version 0.2.0 replaces browser-local storage with portable SQLite project files and adds a desktop persistence boundary.

The current build supports:

• multiple architecture projects
• one portable .conduit SQLite file per project
• opening existing project files
• typed architecture nodes
• typed edges and cardinalities
• independent authority and persistence classifications
• multiple saved diagram views
• manual node placement
• automatic layout
• node and edge inspection
• architecture validation
• undo and redo
• JSON, YAML, and SVG export
• optional AI-generated graph proposals

Core Rule

The .conduit file is the canonical project database.

The recent-project registry only remembers file locations. Removing a project from the recent list does not delete the project file.

Application Architecture

React renderer
    ↓
Preload bridge
    ↓
Explicit Electron IPC calls
    ↓
ProjectStore
    ↓
One SQLite database per .conduit file

The renderer cannot access Node.js or the filesystem directly.

electron/preload.cjs exposes a narrow API. electron/main.js handles native dialogs and IPC. electron/project-store.js owns SQLite schema creation, transactions, identity, integrity checks, and project-file access.

Project File Format

A .conduit file is a normal SQLite database with these tables:

conduit_meta
projects
architecture_objects
architecture_edges
views

conduit_meta

Identifies the file as a Conduit project and records its schema version.

projects

Contains exactly one project record per file.

architecture_objects

Stores typed architecture nodes such as entities, databases, queues, transformations, APIs, dashboards, and policies.

architecture_edges

Stores typed relationships such as reads_from, writes_to, emits, consumes, derives, and contains.

Foreign keys connect every edge to valid source and target objects. Deleting a node deletes its connected edges in the same database transaction.

views

Stores presentation state such as node positions. Layout changes remain separate from semantic graph records.

Storage Invariants

The current persistence layer enforces these rules:

• one project per .conduit file
• every architecture object belongs to that project
• every edge connects two objects from the same project
• foreign keys are enabled
• node deletion cascades to connected edges
• removed nodes are also removed from saved view positions
• graph replacement is transactional
• schema version is checked whenever a project file is opened
• recent-project removal never deletes the project file

Requirements

• Node.js 22.5.0 or newer
• npm 10 or newer
• Linux, macOS, or Windows

Conduit uses the SQLite interface bundled with modern Node.js and Electron. It does not require a separate database server or a native SQLite npm module.

Install

npm install

The first install downloads the Electron runtime.

Run in Development

npm run dev

This starts Vite, waits for the renderer, and launches the Electron desktop window.

Do not use npm run dev:renderer as the normal application entry point. That command runs only the browser renderer, which does not have access to the SQLite desktop bridge.

Build and Run the Production Renderer

npm run build
npm start

npm run build writes the renderer bundle to dist/. npm start launches Electron and loads that bundle.

A packaged installer is not included yet.

Test

npm test
npm run build

The project-store tests use temporary .conduit files and verify:

• schema creation
• SQLite metadata
• graph persistence
• foreign-key behavior
• node-delete cascades
• view-position cleanup
• atomic graph replacement
• recent-project removal without file deletion
• missing-file detection

Creating a Project

1. Launch Conduit.
2. Select New Project.
3. Enter the project name and description.
4. Choose where to save the .conduit file.
5. Add architecture nodes and connect them on the canvas.

The save location is not an export destination. It is the live project database.

Opening a Project

Select Open Project and choose any valid .conduit file. A ready-to-open example is included at examples/research-pipeline.conduit.

Opening a project adds it to the recent-project registry. The file can be moved, copied, backed up, or placed under normal file synchronization outside Conduit. If it is moved, reopen it from its new location.

Recent Projects

The project list displays the full file path for each recent project.

Removing a card from the recent list only removes the registry entry. It never deletes the .conduit file.

Missing or invalid files remain visible as explicit problem states until removed from the recent list or reopened from the correct location.

Optional AI Proposals

The architecture editor works without AI.

The AI assistant is a provider-neutral client for an OpenAI-compatible chat-completions endpoint. AI output is treated as a proposal and is not written into the graph until the user accepts it.

Copy the example environment file:

cp .env.example .env.local

Then configure an endpoint:

VITE_CONDUIT_AI_ENDPOINT=http://localhost:11434/v1/chat/completions
VITE_CONDUIT_AI_MODEL=qwen3:8b
# VITE_CONDUIT_AI_API_KEY=

Vite exposes every VITE_ value to renderer code. Do not place a private production credential in a distributed renderer build. Use a local model or a server-side credential proxy when the key must remain secret.

Project Structure

conduit/
├── electron/
│   ├── main.js
│   ├── preload.js
│   └── project-store.js
├── examples/
│   ├── README.md
│   └── research-pipeline.conduit
├── public/
│   ├── conduit.svg
│   └── manifest.webmanifest
├── scripts/
│   └── dev.mjs
├── src/
│   ├── components/
│   │   ├── conduit/
│   │   └── ui/
│   ├── lib/
│   │   ├── ai-provider.js
│   │   ├── conduit-constants.js
│   │   ├── conduit-db.js
│   │   ├── conduit-export.js
│   │   └── conduit-validation.js
│   ├── pages/
│   │   ├── ProjectList.jsx
│   │   └── Workspace.jsx
│   ├── App.jsx
│   ├── index.css
│   └── main.jsx
├── tests/
│   └── project-store.test.mjs
├── .env.example
├── package.json
└── vite.config.js

Architecture Boundaries

Canonical graph

Projects, architecture objects, and architecture edges form the semantic model.

Presentation state

Views store node positions and diagram-specific presentation data. Moving a node does not change the semantic architecture object.

Renderer repository

src/lib/conduit-db.js preserves the UI-facing repository interface. It delegates every operation to the desktop preload bridge and contains no filesystem or SQLite implementation.

Desktop bridge

electron/preload.cjs exposes explicit operations through contextBridge. The renderer receives no general IPC, filesystem, shell, or Node.js access.

Native persistence

electron/project-store.js owns project-file creation, schema validation, SQL transactions, record identity, and integrity behavior.

Native application shell

electron/main.js owns windows, save/open dialogs, recent-project registration, and IPC handlers.

Validation

src/lib/conduit-validation.js evaluates the graph and returns structured problems for the Problems panel.

Export

src/lib/conduit-export.js converts the active graph into JSON, YAML, and SVG outputs. These are derived exports, not the canonical project database.

AI

src/lib/ai-provider.js is the only AI network boundary. The editor remains usable when it is unconfigured.

Design Principles

Architecture is data

A database is not an arbitrary rectangle. It is a typed object with explicit properties and relationships.

One graph, many views

The same architecture object may appear in several diagrams without being duplicated semantically.

Semantic and visual state remain separate

Layout movement must not become an architecture mutation.

Independent dimensions stay independent

Authority, persistence, maturity, lifecycle, processing mode, and relationship type are not collapsed into one status field.

Derived state identifies its source

Indexes, caches, projections, and aggregates should declare which canonical records can rebuild them.

AI proposes; the user governs

Generated changes remain reviewable proposals until explicitly accepted.

Project custody belongs to the user

The user chooses where each project file is stored. Conduit does not require a hosted account or proprietary backend.

Known Limits

• The previous browser-local-storage prototype is not migrated automatically.
• JSON and YAML import are not implemented yet.
• There is no packaged installer yet.
• Undo and redo still use graph snapshots rather than a persistent command log.
• Project schema migrations beyond version 1 are not implemented yet.
• Collaboration and synchronization are outside the current prototype.

Near-Term Roadmap

1. Add import from the previous JSON workspace format.
2. Add complete project backup and restore commands.
3. Add persistent command history and semantic commits.
4. Add deterministic graph serialization and semantic diffs.
5. Add lineage traversal and dependency queries.
6. Add physical ERD details such as indexes, constraints, and database types.
7. Add scenario and failure-path modeling.
8. Add implementation references for source files, migrations, tests, and deployment units.
9. Add signed release packaging for Linux, Windows, and macOS.

License

No license has been selected yet. Until a license file is added, the repository should be treated as all rights reserved.