mariavel/docs/implementation-plan.md

Mariavel Implementation Plan

Mariavel is a modern, high-performance database management tool designed to bridge the gap between the power of Laravel and the elegance of React. It aims to replace traditional, clunky database management interfaces with a sleek, developer-centric experience.

1. Technical Architecture

Layer	Technology	Responsibility
Backend	Laravel 11 + Sanctum	API Management (SOLID), Dynamic Schema Discovery, CLI Bridge, Authentication.
Frontend	React (TSX) + Vite	High-performance SPA adhering to SOLID component principles.
UI Library	Material UI (MUI)	Dashboard Layout, Navigation, Modals, and consistent Design System.
Data Engine	DevExtreme DataGrid	Virtual Scrolling for millions of rows, Excel-like cell editing.
CLI Engine	Laravel Process	Asynchronous mysqldump and mysql command execution.
Real-time	Laravel Reverb	WebSocket notifications for long-running CLI tasks (Import/Export).

---

2. Design Principles (SOLID)

To ensure long-term maintainability and scalability, Mariavel follows SOLID principles across both stacks:

Backend (Laravel)

• Single Responsibility (SRP): Controllers handle requests, Services handle business logic, and Repositories handle data access.
• Open/Closed (OCP): Database connection and schema discovery logic are abstracted behind interfaces, allowing support for new DB engines (PostgreSQL, SQLite) without changing core code.
• Liskov Substitution (LSP): All database driver implementations adhere to a strict DatabaseDriverInterface.
• Interface Segregation (ISP): Clients don't depend on methods they don't use; interfaces are split into SchemaDiscoveryInterface, DataManipulationInterface, etc.
• Dependency Inversion (DIP): High-level modules (Controllers) depend on abstractions (Interfaces), not low-level implementations.

Frontend (React)

• Single Responsibility: Logic is extracted into Custom Hooks (useSchema, useDataGrid), while components focus purely on rendering.
• Component Composition: Building complex UIs from small, specialized components rather than monolithic ones.
• Prop Typing & Interfaces: Strict TypeScript interfaces for all component props and API responses to ensure type safety and predictability.

---

3. Implementation Phases

Phase 1: Backend Core & Dynamic Connectivity

The backend must handle database connections dynamically rather than relying on a static config/database.php.

• Dynamic Connection Middleware: Develop a middleware that injects database credentials (host, user, password) into the application container at runtime based on the authenticated request.
• Schema Discovery Engine:
  • GET /api/databases: List all available databases.
  • GET /api/tables/{db}: List tables within a database.
  • GET /api/schema/{table}: Retrieve column definitions, data types, and Foreign Key relationships.
• Sanctum Integration: Secure API endpoints with token-based authentication.

Phase 2: Frontend Foundation & MUI Shell

Establishing the "Shell" of the application with a focus on modern UX.

• MUI Dashboard Layout:
  • Collapsible Drawer for database/table tree navigation.
  • Tabs system for managing multiple open tables or SQL editors.
• State Management (Zustand): Efficiently manage global states like activeDatabase, activeTable, and connectionStatus.
• Theming & Aesthetics:
  • Custom Material UI theme with Dark/Light mode support.
  • Injection of dx.material.custom-scheme.css to align DevExtreme components with MUI styles.

Phase 3: High-Performance DataGrid Integration

The heart of Mariavel is the data management interface.

• DevExtreme CustomStore:
  • Implement remoteOperations (paging, filtering, sorting) to ensure the backend does the heavy lifting.
  • Server-side filtering mapping DevExtreme filters to Eloquent/Query Builder.
• Advanced Editing Features:
  • editing.mode = 'cell' for rapid, Excel-style data entry.
  • Bulk actions (Multi-select delete, batch updates).
• Virtual Scrolling: Enable high-performance rendering for tables with 100k+ records.

Phase 4: CLI-Powered Import/Export (The Power Engine)

Bypassing PHP's memory and execution limits for large data operations.

• Async Export Tool:
  • Trigger mysqldump --opt --user={user} --password={pass} {db} > {path}.sql via Laravel Process.
  • Run in the background to avoid timeout issues.
• Async Import Tool:
  • Multipart file upload support for large .sql files.
  • Execute mysql --user={user} --password={pass} {db} < {path}.sql.
• Real-time Feedback: Use Laravel Reverb (WebSockets) to stream progress and completion status back to the React UI.

---

4. Key Differentiators (Killer Features)

1. Zero-Lag Performance: Leverage DevExtreme's virtual scrolling to navigate massive datasets without browser lag.
2. Smart SQL Editor: Integrate Monaco Editor (the engine behind VS Code) for an intelligent SQL authoring experience with syntax highlighting and autocomplete.
3. Security First: Database credentials are never stored in plain text; connection strings are ephemeral or encrypted.
4. Desktop Ready: The decoupled architecture allows for easy packaging into Electron or NativePHP for a native desktop experience.

---

5. Next Steps & Priorities

1. Repository Setup: Initialize Laravel 11 and React/Vite projects.
2. Database Connection Factory: Implement the logic to create PDO connections on the fly.
3. Initial UI Prototype: Build the MUI sidebar with a mock database tree.