System Architecture & Design

Explore the design philosophy behind Data Explorer — from Clean Architecture to high-level Design Patterns for scalability and security.

Hexagonal Architecture

Separates Domain logic from Database and UI via Ports & Adapters.

Strategy Pattern

Supports multiple DB Engines without bloating the core codebase.

Dependency Rule

Dependencies only point inward (Domain Core), ensuring sustainability.

Deep Clean Architecture

Data Explorer strictly adheres to the 4-layer model of Clean Architecture. We apply the "Dependency Rule": Dependencies only point inward, ensuring that the Domain Core is never affected by infrastructure changes.

Domain Layer (Core)

Pure Business Rules

Contains Entities (Connection, User, Table) and POJOs. This layer has zero dependencies on external libraries like NestJS or TypeORM. It is the 'Heart' of the system, preserving the core logic of how queries are structured.

Application Layer (Use Cases)

Flow Orchestration

Contains Use Cases (e.g., ExecuteQueryUseCase, GetSchemaUseCase). This layer defines 'Interfaces' (Ports) that infrastructure must follow. It acts as a conductor, orchestrating data through Ports without knowing the specific Adapter behind them.

Infrastructure Layer (Adapters)

Implementation Details

Where specific technologies 'plug' into the system. This includes PostgreSQL/MySQL/MSSQL/MongoDB drivers, AI provider runners, Prisma, and NestJS interceptors. Adding a new AI lane or a new engine mostly happens here without breaking the Domain Core.

Dependency Inversion In Action

To achieve flexibility, we don't let the Application Layer depend on Infrastructure. Instead, both depend on shared abstractions.

The Power of Ports & Adapters

# // Application layer defines the "Port"

interface DatabasePort {

execute(query: string): Promise<Result>;

}

# // Infrastructure layer implements the "Adapter"

@Injectable()

class PostgresAdapter implements DatabasePort {

async execute(query: string) { /* pg driver logic */ }

}

# // Dependency Injection handles the "plugging"

providers: [{ provide: DatabasePort, useClass: PostgresAdapter }]

Strategy Pattern: Multi-Engine Support

The biggest challenge for Data Explorer is supporting multiple SQL Dialects (Postgres vs MySQL vs MSSQL) while maintaining clean code. We solve this using the Strategy Pattern combined with Dependency Injection.

Database Strategy Interface

# // Defines the contract for all Database Engines

abstract class DatabaseStrategy {

abstract connect(id: string): Promise<Client>;

abstract getMetadata(schema: string): Promise<TableMetadata[]>;

abstract generateExplain(sql: string): Promise<string>;

}

# // Concrete Implementations

class PostgresStrategy extends DatabaseStrategy { ... }

class MySqlStrategy extends DatabaseStrategy { ... }

"The Strategy Pattern lets us extend the product with MongoDB, another SQL dialect, or a new AI execution lane without rewriting the whole UI."

Zustand State Topology

On the client, we manage state using Zustand with a Slice-based architecture. Each module has its own "Slice" but remains interoperable through the Root Store.

Connection Slice

Manages DB list and active connection state.

Tab Slice

Orchestrates independent SQL working windows.

UI/UX Slice

Whole purely UI-related state (Sidebar, Panels, Modals).

The major functional domains in the current repo

The important thing for new contributors is that Data Explorer is no longer just a standalone SQL editor. The current repo has grown into a broader data workspace with AI, NoSQL, team collaboration, layered authentication, billing, backup, and marketing/docs surfaces.

Backend domains

The most important folder groups now include `query`, `metadata`, `nosql`, `ai`, `auth`, `otp`, `billing`, `collaboration`, `organizations`, `permissions`, `teamspaces`, `notifications`, `presence`, `redis`, `mail`, and `database-strategies`. Together they show that the server acts as a query engine, an AI orchestration layer, and a business platform.

Client surfaces

On the client, the major modules currently include `Query`, `NoSqlExplorer`, `Visualization`, `Explorer`, `Dashboard`, `Connection`, `Layout`, and `LandingPage`. At the page level, the repo also ships `DocumentationPage`, `TeamPage`, `LoginPage`, `OnboardingPage`, `BillingReturnPage`, `ERDPage`, and `VisualizePage`.

This is why the docs and architecture should be read by functional domain, not just by folder tree. A small change in AI routing or team permissions can touch the editor, assistant, billing entitlements, and user-state UI at the same time.

Project structure by current product surface

Directory Tree

server/

├── src/

│ ├── auth/ # Auth, JWT, OAuth, session flows

│ ├── otp/ # OTP verification and email confirmation

│ ├── connections/ # Connection records + safety policies

│ ├── query/ # SQL execution and guardrails

│ ├── nosql/ # NoSQL execution, parsing, and Mongo-oriented flows

│ ├── ai/ # AI routing, prompts, provider runners

│ ├── billing/ # Plans, checkout providers, and entitlements

│ ├── collaboration/ # Comments, team activity, shared review context

│ ├── organizations/ # Organization ownership and membership flows

│ ├── permissions/ # Per-resource access control and labels

│ ├── teamspaces/ # Workspace grouping for team resources

│ ├── notifications/ # In-app notices and delivery orchestration

│ ├── presence/ # Team presence and real-time collaboration hints

│ ├── saved-queries/ # Shared saved queries

│ ├── dashboards/ # Dashboards and widgets

│ ├── database-strategies/ # Engine-specific DB strategies

│ ├── metadata/ # Schema/context builders

│ ├── redis/ # Caching and presence backing services

│ └── mail/ # Transactional email integration

client/

├── src/

│ ├── core/ # Adapters, domain entities, app services

│ ├── infrastructure/ # Client-side infrastructure glue

│ ├── presentation/ # Pages, modules, docs, UI shell

│ │ ├── modules/ # SQL, NoSQL, visualization, landing, layout

│ │ ├── pages/ # Docs, auth, team, billing return, ERD, visualize

│ │ └── components/# Shared UI and documentation sections

│ └── test/ # Frontend test setup

PreviousBilling & Subscription Next Technology Stack

Ready to explore data?

Join the community on GitHub to contribute to the smartest local database IDE.

Launch App