tableproapp/tablepro

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.