# 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.