docs: add project README.md detailing backend architecture and setup instructions
This commit is contained in:
Ümit Tunç
+64
-38
@@ -1,58 +1,84 @@
|
||||
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
|
||||
# Mariavel Backend - Database Management API
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
|
||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
|
||||
</p>
|
||||
This is the backend API for Mariavel, built with Laravel 11. It provides a secure and robust abstraction layer for interacting with MariaDB/MySQL databases, managing schema metadata, and performing administrative operations.
|
||||
|
||||
## About Laravel
|
||||
## 🛠️ Core Responsibilities
|
||||
|
||||
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
|
||||
- **Schema Discovery**: Dynamically fetches databases, tables, and column metadata using system catalogs (`information_schema`).
|
||||
- **SQL Execution**: Executes raw SQL queries and returns structured data with row counts and execution metrics.
|
||||
- **Administrative Operations**: Handles bulk table maintenance (Truncate, Drop, Optimize) and technical specifications.
|
||||
- **Database Backups**: Integrates with system tools like `mysqldump` to generate full database exports.
|
||||
- **Import Management**: Processes SQL files and ZIP archives, handling file extraction and sequence execution.
|
||||
- **Data Transformation**: Maps database-specific types to frontend-friendly formats.
|
||||
|
||||
- [Simple, fast routing engine](https://laravel.com/docs/routing).
|
||||
- [Powerful dependency injection container](https://laravel.com/docs/container).
|
||||
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
|
||||
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
|
||||
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
|
||||
- [Robust background job processing](https://laravel.com/docs/queues).
|
||||
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
|
||||
## 🏗️ Architecture & Structure
|
||||
|
||||
Laravel is accessible, powerful, and provides tools required for large, robust applications.
|
||||
The backend follows a service-oriented architecture to ensure separation of concerns and database-agnostic potential:
|
||||
|
||||
## Learning Laravel
|
||||
### Controller Layer
|
||||
- `app/Http/Controllers/Api/SchemaController.php`: Exposes REST endpoints for the frontend, handling request validation and response formatting.
|
||||
|
||||
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework.
|
||||
### Service Layer (Abstraction)
|
||||
- `app/Services/DatabaseService.php`: The main entry point for database operations. It orchestrates high-level tasks and manages driver interactions.
|
||||
|
||||
In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
|
||||
### Driver Layer (Implementation)
|
||||
- `app/Services/Database/MySqlDriver.php`: Contains the concrete logic for MySQL/MariaDB. It encapsulates raw SQL generation and system command execution.
|
||||
|
||||
You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals.
|
||||
## 📂 Directory Structure
|
||||
|
||||
## Agentic Development
|
||||
|
||||
Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow:
|
||||
|
||||
```bash
|
||||
composer require laravel/boost --dev
|
||||
|
||||
php artisan boost:install
|
||||
```
|
||||
app/
|
||||
├── Http/
|
||||
│ └── Controllers/
|
||||
│ └── Api/ # API Endpoints (SchemaController)
|
||||
├── Services/
|
||||
│ ├── Database/ # Driver implementations (MySqlDriver)
|
||||
│ └── DatabaseService.php # Main database abstraction service
|
||||
├── Models/ # Eloquent models (if applicable)
|
||||
└── Providers/ # Service providers for dependency injection
|
||||
routes/
|
||||
└── api.php # API route definitions
|
||||
storage/
|
||||
└── app/backups/ # Temporary storage for export/import files
|
||||
```
|
||||
|
||||
Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices.
|
||||
## 🚥 Getting Started
|
||||
|
||||
## Contributing
|
||||
### Prerequisites
|
||||
- PHP 8.2+
|
||||
- Composer
|
||||
- MySQL/MariaDB server
|
||||
|
||||
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
|
||||
### Installation
|
||||
|
||||
## Code of Conduct
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
composer install
|
||||
```
|
||||
|
||||
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
|
||||
2. Configure environment:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
```
|
||||
|
||||
## Security Vulnerabilities
|
||||
3. Update `.env` with your database credentials:
|
||||
```env
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=your_database
|
||||
DB_USERNAME=your_username
|
||||
DB_PASSWORD=your_password
|
||||
```
|
||||
|
||||
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
|
||||
4. Run the development server:
|
||||
```bash
|
||||
php artisan serve
|
||||
```
|
||||
|
||||
## License
|
||||
## 🔒 Security
|
||||
|
||||
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
|
||||
- All raw SQL execution is handled with caution.
|
||||
- File operations are restricted to specific storage directories.
|
||||
- Ensure the API is protected by authentication in production environments.
|
||||
|
||||
Reference in New Issue
Block a user