# tableproapp/tablepro architecture

> Architecture diagram of the GitHub repository tableproapp/tablepro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tableproapp/tablepro
- Repository: https://github.com/tableproapp/tablepro

## Overview

1. **Repository shape**
   - This is a multi-target Apple-native database client, not a single app. The top-level product is the macOS app `TablePro`, with a companion iOS app `TableProMobile` and a `TableProWidget`.
   - Shared functionality is split across local Swift packages and plugin bundles, with `Packages/TableProCore` acting as the main reusable domain layer.

2. **Primary runtime boundary**
   - The macOS app is the richest client: it owns the main windowing, sidebar, query tabs, data grid, settings, AI chat, MCP server, plugin management, SSH/tunnel orchestration, and sync.
   - `TableProMobile` reimplements a smaller mobile-first browsing/query flow with its own drivers, storage, and iOS platform services.
   - The widget is a lightweight extension that exposes quick-connect and live activity views.

3. **Core data model and persistence**
   - The app stores connections, groups, tags, query history, favorites, settings, SSH profiles, licenses, and tab/session state in local storage abstractions under `TablePro/Core/Storage`.
   - Sensitive data is isolated through keychain helpers and secure-store abstractions; connection records carry only the metadata needed to reconstruct sessions.
   - CloudKit sync exists for selected user data such as connections, groups, tags, and settings, with conflict resolution and record mapping in `TablePro/Core/Sync`.

4. **Connection and transport pipeline**
   - User-entered connection settings flow through parsers, validators, and platform-specific helpers before reaching `DatabaseManager`.
   - `DatabaseManager` coordinates the active connection state, health monitoring, metadata loading, query execution, schema discovery, and tunnel setup.
   - The transport chain can include direct DB sockets, SSH tunnels, Cloudflare tunnels, and per-database auth flows such as AWS credentials, token stores, or SSL/TLS negotiation.

5. **Database execution layer**
   - Query execution is centralized in services/coordinators under `TablePro/Core/Services/Query` and `TablePro/Core/Coordinators`.
   - Those components build SQL, route multi-statement requests, fetch schema and metadata, page through rows, and convert results into app models.
   - Row editing and schema mutations are treated separately from read-only query flows so the UI can gate destructive operations and generate the correct SQL per dialect.

6. **Built-in drivers vs plugin drivers**
   - Some database support ships in the app, while heavier or less common engines are delivered as plugins from `Plugins/`.
   - Built-in support covers engines like PostgreSQL, MySQL/MariaDB, SQLite, ClickHouse, Redis, and related variants through native Swift code plus C bridges.
   - Plugin drivers extend the same core plugin protocol through `TableProPluginKit`, letting the app discover capabilities, validate signatures, install/update plugins, and adapt them into the shared query/metadata model.

7. **Native C library boundary**
   - Many drivers wrap native C clients rather than JDBC or JS runtimes: libpq, MariaDB, FreeTDS, libssh2, hiredis, mongoc, and DuckDB are all present as bridged dependencies.
   - This means the app’s driver architecture is close to the metal: Swift orchestrates native network/database libraries, while the C layer handles protocol specifics and performance-sensitive I/O.

8. **Editor and results UI**
   - The main editing surface is split between a SQL editor and a data grid.
   - The SQL editor is backed by dedicated editor packages (`CodeEditTextView`, `CodeEditSourceEditor`, and `CodeEditLanguages`) for text layout, syntax highlighting, completions, and tree-sitter language support.
   - The results side uses a custom data grid with inline editing, selection, filtering, sorting, undo/redo, row overlays, and specialized viewers for JSON, PHP serialized data, hex, and text.

9. **UI composition and windowing**
   - The app follows a coordinator-heavy UI structure: view models and coordinators mediate between services and SwiftUI/AppKit views.
   - Main app areas include the sidebar tree, query tabs, results tabs, structure editor, server dashboard, quick switcher, and right-side inspector/panel flows.
   - Window management, tab persistence, split views, and restoration are first-class infrastructure rather than incidental UI details.

10. **Import/export and foreign app migration**
   - TablePro includes import/export as a core capability, not an add-on.
   - Data can move through CSV, JSON, SQL, XLSX, and connection-export/import flows, with dedicated services and plugin-based import/export adapters.
   - There is also support for importing connection metadata from other database tools such as DBeaver, DataGrip, Navicat, TablePlus, Sequel Ace, and Beekeeper Studio.

11. **AI subsystem**
   - AI is treated as an integrated feature set with its own provider registry, prompt templates, tool framework, and streaming transport handling.
   - Providers include local and remote backends such as Ollama, OpenAI-compatible APIs, Anthropic, Gemini, Cursor, and ChatGPT Codex integrations.
   - The AI layer can read schema context, trigger tools like list tables or execute query, and render inline suggestions or chat-based assistance inside the app.

12. **MCP and external automation**
   - The app exposes an MCP server stack under `TablePro/Core/MCP` so external clients can interact with connections, schemas, queries, and tabs.
   - The MCP layer includes its own wire protocol, transports, JSON-RPC/SSE codecs, auth, session management, rate limiting, and tool registry.
   - This is a distinct boundary from the normal UI: it lets tools like Cursor, Claude Desktop, and Raycast control TablePro through a controlled protocol rather than direct UI automation.

13. **Mobile-specific architecture**
   - `TableProMobile` mirrors the product in a constrained form: connection management, browsing, query editing, row detail, import/export, and sync.
   - The mobile app uses its own platform abstractions for biometrics, app lock state, local network permissions, file bookmarks, and keychain-backed secure storage.
   - It also includes a widget/live-activity surface for quick connection access, sharing data with the main app through shared storage models.

14. **Operational concerns and tooling**
   - The repository is built and tested as a large Swift/Xcode workspace with Swift Package Manager modules, CI workflows, and per-platform test suites.
   - Release engineering includes plugin builds, artifact packaging, appcast generation, and native library build scripts.
   - Documentation is part of the architecture: the repo contains docs for features, database support, plugin registry, external APIs, and development workflows, which is important because the product surface is spread across app, plugins, AI, and automation integrations.

Main entry points: [`TablePro/Core/Database/DatabaseManager.swift`](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Database/DatabaseManager.swift) (Database Core), [`TablePro/Core/Services/Query/QueryExecutor.swift`](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Services/Query/QueryExecutor.swift) (Query Services), [`TablePro/Core/Storage/ConnectionStorage.swift`](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Storage/ConnectionStorage.swift) (Storage), [`TablePro/TableProApp.swift`](https://github.com/tableproapp/tablepro/blob/main/TablePro/TableProApp.swift) (TablePro)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop App"]
  node_tablepro_app["TablePro<br/>macOS app<br/>[TableProApp.swift]"]
  node_tablepro_main_ui["Main UI<br/>coordinator UI"]
  node_tablepro_editor["SQL Editor<br/>editor shell"]
  node_tablepro_results["Results Grid<br/>data grid UI<br/>[DataGridView.swift]"]
  node_tablepro_settings["Settings<br/>preferences UI<br/>[SettingsView.swift]"]
end

subgraph group_mobile["Mobile Suite"]
  node_tablepro_mobile_app["TableProMobile<br/>iOS app"]
  node_tablepro_widget["Widget<br/>extension"]
end

subgraph group_core["Shared Core"]
  node_tablepro_ai["AI Layer<br/>assistant stack<br/>[AIProvider.swift]"]
  node_tablepro_mcp["MCP Server<br/>automation stack"]
  node_tablepro_database["Database Core<br/>connection pipeline"]
  node_tablepro_query["Query Services<br/>query engine"]
  node_tablepro_storage[("Storage<br/>local persistence")]
  node_tablepro_sync["Sync"]
  node_tablepro_export_import["Import/Export<br/>data exchange"]
  node_tablepro_ssh["SSH/Tunnels<br/>transport layer"]
  node_tablepro_plugins_core["Plugin Manager<br/>plugin runtime"]
end

subgraph group_plugins["Plugin Layer"]
  node_pluginkit["PluginKit<br/>plugin protocol"]
  node_builtin_drivers["Built-in Drivers<br/>native drivers"]
  node_external_plugins["Driver Plugins<br/>plugin bundles"]
end

subgraph group_editors["Editor Packages"]
  node_codeedit_textview["CodeEditTextView<br/>text editor package"]
  node_codeedit_sourceeditor["CodeEditSourceEditor<br/>source editor package<br/>[SourceEditor.swift]"]
  node_codeedit_languages["CodeEditLanguages<br/>language pack<br/>[CodeLanguage.swift]"]
end

node_tablepro_app -->|"hosts"| node_tablepro_main_ui
node_tablepro_app -->|"uses"| node_tablepro_editor
node_tablepro_app -->|"renders"| node_tablepro_results
node_tablepro_app -->|"configures"| node_tablepro_settings
node_tablepro_main_ui -->|"drives"| node_tablepro_database
node_tablepro_editor -->|"built on"| node_codeedit_sourceeditor
node_tablepro_editor -->|"built on"| node_codeedit_textview
node_tablepro_editor -->|"highlights with"| node_codeedit_languages
node_tablepro_results -->|"reads from"| node_tablepro_query
node_tablepro_results -->|"writes through"| node_tablepro_database
node_tablepro_database -->|"tunnels via"| node_tablepro_ssh
node_tablepro_database -->|"executes on"| node_builtin_drivers
node_tablepro_database -->|"adapts"| node_external_plugins
node_tablepro_plugins_core -->|"implements"| node_pluginkit
node_external_plugins -->|"conforms to"| node_pluginkit
node_tablepro_query -->|"queries"| node_builtin_drivers
node_tablepro_query -->|"persists"| node_tablepro_storage
node_tablepro_storage -->|"syncs"| node_tablepro_sync
node_tablepro_ai -->|"calls"| node_tablepro_query
node_tablepro_ai -->|"stores"| node_tablepro_storage
node_tablepro_mcp -->|"exposes"| node_tablepro_query
node_tablepro_mcp -->|"bridges"| node_tablepro_database
node_tablepro_export_import -->|"imports into"| node_tablepro_storage
node_tablepro_export_import -->|"extends"| node_external_plugins
node_tablepro_mobile_app -->|"shares"| node_tablepro_storage
node_tablepro_mobile_app -->|"syncs with"| node_tablepro_sync
node_tablepro_mobile_app -->|"connects via"| node_tablepro_ssh
node_tablepro_mobile_app -->|"extends"| node_tablepro_widget

click node_tablepro_app "https://github.com/tableproapp/tablepro/blob/main/TablePro/TableProApp.swift"
click node_tablepro_main_ui "https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Main/MainContentView.swift"
click node_tablepro_editor "https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Editor/SQLEditorView.swift"
click node_tablepro_results "https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Results/DataGridView.swift"
click node_tablepro_settings "https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Settings/SettingsView.swift"
click node_tablepro_ai "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/AI/AIProvider.swift"
click node_tablepro_mcp "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/MCP/MCPServerManager.swift"
click node_tablepro_database "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Database/DatabaseManager.swift"
click node_tablepro_query "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Services/Query/QueryExecutor.swift"
click node_tablepro_storage "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Storage/ConnectionStorage.swift"
click node_tablepro_sync "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Sync/CloudKitSyncEngine.swift"
click node_tablepro_export_import "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Services/Export/ImportService.swift"
click node_tablepro_ssh "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/SSH/SSHTunnelManager.swift"
click node_tablepro_plugins_core "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Plugins/PluginManager.swift"
click node_pluginkit "https://github.com/tableproapp/tablepro/blob/main/Plugins/TableProPluginKit/TableProPlugin.swift"
click node_builtin_drivers "https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Database/DatabaseDriver.swift"
click node_external_plugins "https://github.com/tableproapp/tablepro/blob/main/Plugins/PostgreSQLDriverPlugin/PostgreSQLPlugin.swift"
click node_codeedit_textview "https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditTextView/Sources/CodeEditTextView/CodeEditTextView.swift"
click node_codeedit_sourceeditor "https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditSourceEditor/Sources/CodeEditSourceEditor/SourceEditor/SourceEditor.swift"
click node_codeedit_languages "https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditLanguages/Sources/CodeEditLanguages/CodeLanguage.swift"
click node_tablepro_mobile_app "https://github.com/tableproapp/tablepro/blob/main/TableProMobile/TableProMobile/TableProMobileApp.swift"
click node_tablepro_widget "https://github.com/tableproapp/tablepro/blob/main/TableProMobile/TableProWidget/QuickConnectWidget.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tablepro_app,node_tablepro_main_ui,node_tablepro_editor,node_tablepro_results,node_tablepro_settings toneBlue
class node_tablepro_mobile_app,node_tablepro_widget toneAmber
class node_tablepro_ai,node_tablepro_mcp,node_tablepro_database,node_tablepro_query,node_tablepro_storage,node_tablepro_sync,node_tablepro_export_import,node_tablepro_ssh,node_tablepro_plugins_core toneMint
class node_pluginkit,node_builtin_drivers,node_external_plugins toneRose
class node_codeedit_textview,node_codeedit_sourceeditor,node_codeedit_languages toneIndigo
```

## Components

### Desktop App

macOS client and app-level orchestration

- [TablePro](https://github.com/tableproapp/tablepro/blob/main/TablePro/TableProApp.swift): macOS app · Main desktop client with windowing, query workbench, settings, AI, MCP, plugins, sync, and database operations · `TablePro/TableProApp.swift`
- [Main UI](https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Main/MainContentView.swift): coordinator UI · Sidebar, tabs, inspector, split views, and major app navigation flows · `TablePro/Views/Main/MainContentView.swift`
- [SQL Editor](https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Editor/SQLEditorView.swift): editor shell · Query editor composition, completion adapter, and editor coordination · `TablePro/Views/Editor/SQLEditorView.swift`
- [Results Grid](https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Results/DataGridView.swift): data grid UI · Query results table, inline editing, selection, filtering, sorting, and viewers · `TablePro/Views/Results/DataGridView.swift`
- [Settings](https://github.com/tableproapp/tablepro/blob/main/TablePro/Views/Settings/SettingsView.swift): preferences UI · App settings, licenses, AI providers, plugins, MCP, sync, and appearance · `TablePro/Views/Settings/SettingsView.swift`

### Mobile Suite

iOS app and widget surfaces

- [TableProMobile](https://github.com/tableproapp/tablepro/blob/main/TableProMobile/TableProMobile/TableProMobileApp.swift): iOS app · Mobile-first client with browsing, querying, row detail, import/export, and sync · `TableProMobile/TableProMobile/TableProMobileApp.swift`
- [Widget](https://github.com/tableproapp/tablepro/blob/main/TableProMobile/TableProWidget/QuickConnectWidget.swift): extension · Quick-connect and live activity widget surface for shared connections · `TableProMobile/TableProWidget/QuickConnectWidget.swift`

### Shared Core

Reusable domain, storage, sync, and service layers

- [AI Layer](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/AI/AIProvider.swift): assistant stack · Providers, chat tools, prompts, streaming, and inline suggestion features · `TablePro/Core/AI/AIProvider.swift`
- [MCP Server](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/MCP/MCPServerManager.swift): automation stack · External protocol boundary for tools, transports, auth, sessions, and rate limiting · `TablePro/Core/MCP/MCPServerManager.swift`
- [Database Core](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Database/DatabaseManager.swift): connection pipeline · Connection parsing, manager, health, metadata, schema, queries, SSH, and tunnels · `TablePro/Core/Database/DatabaseManager.swift`
- [Query Services](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Services/Query/QueryExecutor.swift): query engine · Query execution, pagination, row parsing, schema services, and result routing · `TablePro/Core/Services/Query/QueryExecutor.swift`
- [Storage](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Storage/ConnectionStorage.swift): local persistence · Connections, groups, tags, favorites, history, settings, keychain, and session state · `TablePro/Core/Storage/ConnectionStorage.swift`
- [Sync](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Sync/CloudKitSyncEngine.swift): cloud sync · CloudKit sync, record mapping, metadata, and conflict handling · `TablePro/Core/Sync/CloudKitSyncEngine.swift`
- [Import/Export](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Services/Export/ImportService.swift): data exchange · CSV, JSON, SQL, XLSX, connection transfer, and foreign app migration · `TablePro/Core/Services/Export/ImportService.swift`
- [SSH/Tunnels](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/SSH/SSHTunnelManager.swift): transport layer · SSH auth, tunnels, host verification, config resolution, and relay I/O · `TablePro/Core/SSH/SSHTunnelManager.swift`
- [Plugin Manager](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Plugins/PluginManager.swift): plugin runtime · Discovery, installation, verification, registry integration, and driver adaptation · `TablePro/Core/Plugins/PluginManager.swift`

### Plugin Layer

Driver plugins and plugin protocol kit

- [PluginKit](https://github.com/tableproapp/tablepro/blob/main/Plugins/TableProPluginKit/TableProPlugin.swift): plugin protocol · Shared plugin contracts, capabilities, dialect metadata, and import/export abstractions · `Plugins/TableProPluginKit/TableProPlugin.swift`
- [Built-in Drivers](https://github.com/tableproapp/tablepro/blob/main/TablePro/Core/Database/DatabaseDriver.swift): native drivers · Native Swift plus C-bridged database support shipped inside the app · `TablePro/Core/Database/DatabaseDriver.swift`
- [Driver Plugins](https://github.com/tableproapp/tablepro/blob/main/Plugins/PostgreSQLDriverPlugin/PostgreSQLPlugin.swift): plugin bundles · Out-of-process or separately packaged drivers and import/export plugins · `Plugins/PostgreSQLDriverPlugin/PostgreSQLPlugin.swift`

### Editor Packages

Shared SQL editing and syntax infrastructure

- [CodeEditTextView](https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditTextView/Sources/CodeEditTextView/CodeEditTextView.swift): text editor package · Low-level text layout, selection, syntax rendering, and editor behavior · `LocalPackages/CodeEditTextView/Sources/CodeEditTextView/CodeEditTextView.swift`
- [CodeEditSourceEditor](https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditSourceEditor/Sources/CodeEditSourceEditor/SourceEditor/SourceEditor.swift): source editor package · Coordinator-backed source editor with highlighting, folding, find, and tree-sitter integration · `LocalPackages/CodeEditSourceEditor/Sources/CodeEditSourceEditor/SourceEditor/SourceEditor.swift`
- [CodeEditLanguages](https://github.com/tableproapp/tablepro/blob/main/LocalPackages/CodeEditLanguages/Sources/CodeEditLanguages/CodeLanguage.swift): language pack · Tree-sitter language definitions and highlight resources for SQL and other syntaxes · `LocalPackages/CodeEditLanguages/Sources/CodeEditLanguages/CodeLanguage.swift`

## Connections

- TablePro → Main UI: hosts · Desktop app presents the primary coordinator-heavy interface
- TablePro → SQL Editor: uses · Main app embeds the SQL editor surface
- TablePro → Results Grid: renders · Desktop app shows query results and row editing
- TablePro → Settings: configures · Settings hub exposes product and integration controls
- Main UI → Database Core: drives · UI actions flow into connection and transport orchestration
- SQL Editor → CodeEditSourceEditor: built on · Desktop SQL editor uses the shared source editor package
- SQL Editor → CodeEditTextView: built on · Editor behavior depends on the lower-level text view package
- SQL Editor → CodeEditLanguages: highlights with · Language definitions provide syntax highlighting and parsing support
- Results Grid → Query Services: reads from · Results grid is fed by query execution and paging services
- Results Grid → Database Core: writes through · Row edits and schema changes are committed through the connection layer
- Database Core → SSH/Tunnels: tunnels via · Connection setup can route through SSH and related transports
- Database Core → Built-in Drivers: executes on · Built-in engines are invoked directly by the database manager
- Database Core → Driver Plugins: adapts · Plugin-backed engines are loaded and normalized through the plugin layer
- Plugin Manager → PluginKit: implements · App-side plugin management conforms to the shared plugin protocol
- Driver Plugins → PluginKit: conforms to · Driver bundles implement the common plugin contracts
- Query Services → Built-in Drivers: queries · Query services dispatch SQL and metadata work to native drivers
- Query Services → Storage: persists · Query history, favorites, and tab state are stored locally
- Storage → Sync: syncs · Selected local records are mirrored through CloudKit sync
- AI Layer → Query Services: calls · AI tools can inspect schema and execute queries
- AI Layer → Storage: stores · Chat state, prompts, and AI credentials are persisted locally
- MCP Server → Query Services: exposes · External clients can list, inspect, and execute against connections
- MCP Server → Database Core: bridges · MCP tools operate through the active database/session layer
- Import/Export → Storage: imports into · Connection and app data imports land in local persistence
- Import/Export → Driver Plugins: extends · Import/export formats can be supplied by plugins
- TableProMobile → Storage: shares · Mobile app reuses shared persistence models and storage concepts
- TableProMobile → Sync: syncs with · Mobile client uses sync coordinator for shared data
- TableProMobile → SSH/Tunnels: connects via · iOS client includes its own SSH/tunnel implementation
- TableProMobile → Widget: extends · Widget and live activity provide quick access from the mobile suite