Skip to content

architecture.md

Latest commit

 

History

History
87 lines (68 loc) · 3.97 KB

architecture.md

File metadata and controls

87 lines (68 loc) · 3.97 KB
Raw

Architecture

A high-level map of the codebase for contributors. The app is a Flutter desktop client with a custom window frame (bitsdojo_window) and shadcn_flutter UI components.

Layered layout

lib/
├── main.dart        App entry: window setup, controller bootstrap
├── app/             App shell, theme wiring, global scopes
├── core/            Cross-cutting infrastructure (no feature UI)
├── features/        Feature modules, one folder per area / engine
└── shared/          Reusable widgets shared across features

The dependency direction is features → core/shared, never the reverse. core/ and shared/ must not import from features/ or app/ (test/guards/core_does_not_import_features_test.dart checks it).

When core/ needs something that lives in features/, it declares a hook and app/app_wiring.dart installs it at startup (installAppWiring(), also run by test/flutter_test_config.dart):

Hook Installed
QueryaCommandRegistry.coreCommands queryaCoreCommands (app/querya_core_commands.dart): palette commands that open feature dialogs
ExtensionCommandSync.connectionPicker showExtensionConnectionPickerDialog
McpServerController.delegateFactory createReadOnlyMcpDelegate (app/mcp_sql_delegates.dart): the SQL editor's read-only delegates

Core code that only reads SQL depends on SqlQueryRunner (core/database/sql_query_runner.dart), which the workspace's SqlExecutionDelegate implements. The schema catalog behind the ER diagram and MCP (ErdCatalog, ErdSchema, ErdTableNames) is in core/erd/.

core/

Path Responsibility
core/database/ Engine clients and query execution (PostgreSQL, MySQL, Redis, MongoDB).
core/storage/ Local SQLite metadata (local_db.dart), app settings, secure secrets store.
core/theme/ Theme tokens, VS Code theme import, color resolution.
core/editor/ Code editor helpers and syntax highlighting glue.
core/layout/ Window/dialog sizing and the global UI-scale system.
core/csv/, core/json/ Result export helpers (CSV / JSON).

features/

Path Responsibility
features/main_screen/ Main layout, workspace panel, query/results tabs, history.
features/connections/ Connection tree, new connection / folder flows, driver manager.
features/postgresql/ PostgreSQL workspace, object browser, SQL editor dialog.
features/mysql/ MySQL / MariaDB workspace, browser, SQL editor dialog.
features/redis/ Redis connection form and workspace.
features/mongodb/ MongoDB connection form, database dialog, stats view.
features/settings/ Preferences dialog, controls, interface scale slider.

shared/

Path Responsibility
shared/widgets/ shadcn re-exports, QueryaDropdown, app dialog, shared tokens.

Cross-cutting systems

  • Theme system — runtime dark/light/system modes plus VS Code theme import. See theme.md and theme-import.md.
  • UI scaling — a global scale factor propagated via an inherited scope and applied to text (TextScaler) and dialog dimensions. Lives in core/layout/.
  • Secrets — passwords and connection strings go to the OS secure store, not SQLite. See security.md.

Data and secrets

  • Connection metadata + preferences: local SQLite (querya.db in the app support directory).
  • Passwords / connection strings: OS secure store via flutter_secure_storage (Keychain / Credential Manager / libsecret).

Tests

Widget tests that touch SQLite or path_provider follow the patterns in test/features/connections/connections_panel_layout_test.dart and test/flutter_test_config.dart (in-memory secrets backend, no desktop keyring required). Run them with flutter test.