Ümit Tunç
98 lines
5.7 KiB
Markdown
98 lines
5.7 KiB
Markdown
# 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.
|