mchus/turborfq
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Add project Bible and consolidate documentation

Browse Source 
- Create bible/ as single source of truth (architecture, API, frontend, installation, usage, security, roadmap)
- Verify and fix Bible against actual source code (API methods, endpoints, data flow)
- Trim README.md and CLAUDE.md to minimal stubs pointing to the Bible
- Remove duplicate claude.md (lowercase)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mikhail Chusavitin
2026-02-20 14:11:57 +03:00
parent 4d608c016d
commit c97d49e762
10 changed files with 812 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
claude.md
View File

@@ -1,147 +1 @@
# TurboRFQ - MariaDB Web UI
TurboRFQ is a lightweight PHP web application that provides an Excel-like interface for browsing and editing MariaDB tables. Users authenticate with their own MariaDB credentials, and the app works with any schema by reading metadata from `information_schema`.
## Key Features
- **Authentication**: Native MariaDB user/password authentication (no separate app users)
- **Schema Agnostic**: Works with any schema by reading metadata from `information_schema`
- **Excel-like Grid**: Interactive data grid built with Tabulator
- **Column Header Filters**: Per-column search capabilities
- **Server-side Pagination**: Efficient handling of large datasets
- **Full CRUD Operations**: Insert, update, delete functionality
- **CSV Import/Export**: Bulk data operations
- **Backup Functionality**: Database backup using mysqldump
- **Foreign Key Support**: Proper handling of foreign key relationships
## Architecture
### Backend Components
1. **Database Layer (`Db.php`)**:
- PDO factory based on session credentials
- Connection testing functionality
- Session-based authentication
2. **Metadata Service (`MetaService.php`)**:
- Queries `information_schema` to build schema → tables tree
- Loads column definitions and detects primary keys
- Handles foreign key relationships
- Provides editor type mapping for different data types
3. **Data Service (`DataService.php`)**:
- Generic SELECT operations with server-side pagination and filtering
- INSERT operations (skipping auto_increment columns)
- UPDATE/DELETE operations by primary key
- CSV import with error handling and data validation
- CSV export functionality
- Mass delete operations
- Backup functionality using mysqldump
- Foreign key value suggestions
4. **Backup Service (`BackupService.php`)**:
- Database backup using mysqldump
- Supports backup of individual databases or all databases
- Temporary file management
### Frontend Components
- `index.html` - Basic layout with sidebar, toolbar, and grid container
- `app.js` - Frontend logic using Tabulator for interactive data grid
### API Endpoints
The application exposes a comprehensive RESTful API:
- Authentication (`/api/login`)
- Schema tree (`/api/tree`)
- Table metadata (`/api/table/meta`)
- Data operations (`/api/table/data`, `/api/table/insert`, `/api/table/update`, `/api/table/delete`)
- CSV import/export (`/api/table/import-csv`, `/api/table/export-csv`)
- Foreign key values (`/api/fk-values`)
- Batch operations (`/api/table/delete-batch`)
- Backup functionality (`/api/backup/*`)
## Technology Stack
**Backend**:
- PHP 8.1+
- Slim 4 microframework
- PHP-DI (dependency injection)
- PDO (MariaDB/MySQL driver)
**Frontend**:
- Vanilla JS
- Tabulator (interactive data grid)
## Installation
### Docker (Recommended)
```bash
docker pull git.mchus.pro/mchus/turborfq:latest
docker run -d \
--name turborfq \
-p 8080:8080 \
-e DB_HOST=your-mariadb-host \
-e DB_PORT=3306 \
git.mchus.pro/mchus/turborfq:latest
```
Open http://localhost:8080 in your browser.
### Manual Installation
1. Clone the project:
```bash
cd /path/to
git clone https://git.mchus.pro/mchus/turborfq.git mariadb-grid
cd mariadb-grid
```
2. Install PHP dependencies:
```bash
composer install
```
3. Run the development server:
```bash
cd /path/to/mariadb-grid
php -S localhost:8080 -t public
```
## Usage
1. Open the app in a browser
2. In the top login panel:
- Enter MariaDB username
- Enter MariaDB password
- Click "Login"
3. If the connection succeeds:
- The left sidebar will show databases and tables as a tree
4. Click any table:
- The central Tabulator grid will load the table's data
- Column header filters allow you to filter per column
- Pagination is handled server-side
### CRUD operations
- **Insert**: Click "Insert" to add a new row
- **Update**: Select a row and edit cells directly in the grid, then click "Save row"
- **Delete**: Select one or more rows and click "Delete", then confirm
> Updates and deletes are performed using the table's primary key. If there is no primary key, it is safer to treat the table as read-only.
## Security Considerations
The application uses session-based authentication with credentials stored in PHP sessions. It leverages MariaDB's own permission system for access control, ensuring that users can only see and edit what their credentials allow.
The application includes robust error handling and logging capabilities, particularly for data operations and CSV import/export functions.
## Customization Ideas
- Map column `DATA_TYPE` to more specific editors (date picker, number editor, dropdowns)
- Add sorting synchronization (Tabulator sorters → backend `ORDER BY`)
- Add bulk insert/update operations using transactions
- Add read-only mode for tables without primary keys
- Add simple configuration file for allowed schemas, default page size, etc.
Read [bible/README.md](bible/README.md) and all files it references before making any architectural or implementation decisions. The Bible is the single source of truth for this project — respect it and keep it up to date.