base-api-scramble-mcp 1.0.0

package/docs/STRUCTURE.md

@@ -0,0 +1,540 @@
+# Project Structure - Base API Scramble
+
+## 📁 Root Directory
+
+```
+base-api-scramble/
+├── 📄 .editorconfig
+├── 📄 .env.example
+├── 📄 .gitattributes
+├── 📄 .gitignore
+├── 📄 README.md
+├── 📄 DESCRIPTION.md
+├── 📄 STRUCTURE.md                     # This file
+├── 📄 artisan
+├── 📄 composer.json
+├── 📄 composer.lock
+├── 📄 package.json
+├── 📄 phpunit.xml
+├── 📄 vite.config.js
+└── 📁 [directories...]
+```
+
+---
+
+## 🎯 Application Directory (`app/`)
+
+### Console
+```
+app/Console/
+├── Commands/
+│   ├── GC.php                          # Generator Command utama
+│   ├── GCFromMigration.php             # Generate dari migration
+│   ├── GCHelp.php                      # Helper command
+│   ├── GCWizard.php                    # Wizard mode
+│   └── gc/                             # Template stubs
+│       ├── controller.stub
+│       ├── controller_with_file.stub
+│       ├── migration.stub
+│       ├── model.stub
+│       ├── query.stub                  # ⭐ NEW: Query class stub
+│       ├── route_api_v1_segment.stub
+│       ├── storerequest.stub
+│       └── updaterequest.stub
+└── Kernel.php
+```
+
+### Exceptions
+```
+app/Exceptions/
+└── Handler.php                         # Global exception handler
+```
+
+### Helpers
+```
+app/Helpers/
+├── ApiResponse.php                     # Standardized API responses
+└── QueryHelper.php                     # Query building helper
+```
+
+### HTTP Layer
+```
+app/Http/
+├── Controllers/
+│   ├── Controller.php                  # Base controller
+│   └── Api/V1/                         # API Version 1
+│       ├── AuthController.php          # Authentication
+│       ├── LabelController.php         # Labels CRUD
+│       ├── LogActivityController.php   # Activity logs
+│       ├── PermissionController.php    # Permissions management
+│       ├── PostController.php          # Posts CRUD
+│       ├── ProfileController.php       # User profile
+│       ├── RoleController.php          # Roles management
+│       ├── RolePermissionController.php # Role-Permission pivot
+│       ├── UserController.php          # Users management
+│       └── UserRoleController.php      # User-Role pivot
+│
+├── Middleware/
+│   ├── Authenticate.php
+│   ├── EncryptCookies.php
+│   ├── PreventRequestsDuringMaintenance.php
+│   ├── RedirectIfAuthenticated.php
+│   ├── TrimStrings.php
+│   ├── TrustHosts.php
+│   ├── TrustProxies.php
+│   ├── ValidateSignature.php
+│   └── VerifyCsrfToken.php
+│
+├── Requests/Api/V1/
+│   ├── ChangePasswordRequest.php
+│   ├── IndexRequest.php                # ⭐ NEW: Generic index request
+│   ├── LoginRequest.php                # ⭐ NEW: Login validation
+│   ├── LabelStoreRequest.php
+│   ├── LabelUpdateRequest.php
+│   ├── PermissionStoreRequest.php      # ⭐ NEW
+│   ├── PermissionUpdateRequest.php     # ⭐ NEW
+│   ├── PostStoreRequest.php
+│   ├── PostUpdateRequest.php
+│   ├── ProfileRequest.php
+│   ├── RolePermissionAttachRequest.php # ⭐ NEW
+│   ├── RolePermissionDetachRequest.php # ⭐ NEW
+│   ├── RolePermissionSyncPermissionsRequest.php # ⭐ NEW
+│   ├── RolePermissionSyncRolesRequest.php # ⭐ NEW
+│   ├── RoleStoreRequest.php            # ⭐ NEW
+│   ├── RoleUpdateRequest.php           # ⭐ NEW
+│   ├── UserRoleAttachRequest.php       # ⭐ NEW
+│   ├── UserRoleDetachRequest.php       # ⭐ NEW
+│   ├── UserRoleSyncRolesRequest.php    # ⭐ NEW
+│   ├── UserRoleSyncUsersRequest.php    # ⭐ NEW
+│   ├── UserStoreRequest.php            # ⭐ NEW
+│   └── UserUpdateRequest.php           # ⭐ NEW
+│
+├── Resources/V1/
+│   └── ActivityLogResource.php         # API resource transformer
+│
+└── Kernel.php
+```
+
+### Models
+```
+app/Models/
+├── ActivityLog.php                     # Activity logging
+├── Label.php                           # Labels
+├── Permission.php                      # Permissions (Spatie)
+├── Post.php                            # Posts
+├── Role.php                            # Roles (Spatie)
+└── User.php                            # Users
+```
+
+### Observers
+```
+app/Observers/
+├── LogPermissionObserver.php           # Log permission changes
+├── LogRoleObserver.php                 # Log role changes
+└── LogUserObserver.php                 # Log user changes
+```
+
+### Providers
+```
+app/Providers/
+├── AppServiceProvider.php
+├── AuthServiceProvider.php
+├── BroadcastServiceProvider.php
+├── EventServiceProvider.php
+├── RouteServiceProvider.php
+└── ScrambleServiceProvider.php         # ⭐ NEW: Scramble configuration
+```
+
+### Queries (⭐ NEW Directory)
+```
+app/Queries/
+├── ActivityLogQuery.php                # Activity log query builder
+├── LabelQuery.php                      # Label query builder
+├── PermissionQuery.php                 # Permission query builder
+├── PostQuery.php                       # Post query builder
+├── RoleQuery.php                       # Role query builder
+└── UserQuery.php                       # User query builder
+```
+
+### Services
+```
+app/Services/
+└── FileService.php                     # File handling service
+```
+
+### Traits
+```
+app/Traits/
+└── Queryable.php                       # Query filtering trait
+```
+
+---
+
+## 🗄️ Database (`database/`)
+
+```
+database/
+├── factories/
+│   └── UserFactory.php
+│
+├── migrations/
+│   ├── 2014_10_12_000000_create_users_table.php
+│   ├── 2014_10_12_100000_create_password_reset_tokens_table.php
+│   ├── 2019_08_19_000000_create_failed_jobs_table.php
+│   ├── 2019_12_14_000001_create_personal_access_tokens_table.php
+│   ├── 2025_02_07_062711_create_sessions_table.php
+│   ├── 2025_02_07_062718_create_jobs_table.php
+│   ├── 2025_02_07_062727_create_cache_table.php
+│   ├── 2025_02_07_063308_create_permission_tables.php
+│   ├── 2025_02_07_064118_create_activity_log_table.php
+│   ├── 2025_06_20_105040_create_labels_table.php
+│   └── 2025_06_20_113036_create_posts_table.php
+│
+└── seeders/
+    ├── DatabaseSeeder.php
+    └── PermissionSeeder.php
+```
+
+---
+
+## ⚙️ Configuration (`config/`)
+
+```
+config/
+├── app.php                             # Application config
+├── auth.php                            # Authentication
+├── broadcasting.php                    # Broadcasting
+├── cache.php                           # Cache
+├── cors.php                            # CORS
+├── database.php                        # Database
+├── filesystems.php                     # File storage
+├── hashing.php                         # Hashing
+├── logging.php                         # Logging
+├── mail.php                            # Mail
+├── permission.php                      # Spatie Permission
+├── query-builder.php                   # Query builder
+├── queue.php                           # Queue
+├── sanctum.php                         # Laravel Sanctum
+├── scramble.php                        # ⭐ NEW: Scramble API docs config
+├── services.php                        # External services
+├── session.php                         # Session
+└── view.php                            # Views
+```
+
+---
+
+## 🌐 Routes (`routes/`)
+
+```
+routes/
+├── api.php                             # Main API routes
+├── api_v1.php                          # API Version 1 routes
+├── channels.php                        # Broadcasting channels
+├── console.php                         # Console commands
+└── web.php                             # Web routes
+```
+
+---
+
+## 📦 Public Assets (`public/`)
+
+```
+public/
+├── .htaccess
+├── favicon.ico
+├── index.php                           # Application entry point
+└── robots.txt
+```
+
+---
+
+## 🎨 Resources (`resources/`)
+
+```
+resources/
+├── css/
+│   └── app.css
+├── js/
+│   ├── app.js
+│   └── bootstrap.js
+└── views/
+    └── welcome.blade.php
+```
+
+---
+
+## 💾 Storage (`storage/`)
+
+```
+storage/
+├── app/
+│   └── public/                         # Public storage (symlinked)
+│
+├── framework/
+│   ├── cache/
+│   │   └── data/
+│   ├── sessions/
+│   ├── testing/
+│   └── views/
+│
+└── logs/                               # Application logs
+```
+
+---
+
+## 🧪 Tests (`tests/`)
+
+```
+tests/
+├── CreatesApplication.php
+├── TestCase.php
+├── Feature/
+│   └── ExampleTest.php
+└── Unit/
+    └── ExampleTest.php
+```
+
+---
+
+## 📚 Documentation (`docs/`)
+
+```
+docs/
+└── AI-GUIDE-COMPLETE.md                # Complete AI implementation guide
+```
+
+---
+
+## 🛠️ Bootstrap (`bootstrap/`)
+
+```
+bootstrap/
+├── app.php                             # Application bootstrap
+└── cache/                              # Framework cache
+```
+
+---
+
+## 🎯 Architecture Highlights
+
+### 📋 Query Builder Pattern (NEW!)
+Project ini menggunakan **dedicated Query classes** untuk memisahkan logic filtering/searching dari Controller:
+
+```php
+app/Queries/
+├── ActivityLogQuery.php
+├── LabelQuery.php
+├── PermissionQuery.php
+├── PostQuery.php
+├── RoleQuery.php
+└── UserQuery.php
+```
+
+**Benefits:**
+- ✅ Separation of Concerns
+- ✅ Reusable query logic
+- ✅ Easier testing
+- ✅ Cleaner controllers
+- ✅ Better maintainability
+
+### 🔐 Authentication & Authorization
+- **Laravel Sanctum** for API authentication
+- **Spatie Permission** for role-based access control (RBAC)
+- **Activity logging** for audit trails with observers
+
+### 📝 Enhanced Request Validation
+Validasi yang lebih lengkap dan granular:
+- **IndexRequest** - Generic pagination & filtering
+- **LoginRequest** - Authentication validation
+- **Attach/Detach/Sync Requests** - Many-to-many relationship operations
+- **Store/Update Requests** - Per-resource validation
+
+### 🎯 API Documentation
+- **Scramble** for automatic OpenAPI/Swagger documentation
+- **ScrambleServiceProvider** untuk custom configuration
+- **Versioned API** (V1) dengan struktur yang scalable
+
+### 🔨 Custom Commands
+- `php artisan gc` - Generator Command
+- `php artisan gc:wizard` - Interactive wizard
+- `php artisan gc:migration` - Generate from migration
+- `php artisan gc:help` - Help documentation
+
+Generator sekarang include:
+- Controller (dengan/tanpa file upload)
+- Model dengan relationships
+- **Query class** untuk filtering
+- Request validation (Store/Update)
+- Migration
+- Auto-register routes
+
+---
+
+## 📝 Key Features
+
+### ✨ Complete CRUD Architecture
+```
+Request → Controller → Query → Model → Response
+```
+
+**Flow:**
+1. **Request Validation** (FormRequest)
+2. **Controller** delegates to Query class
+3. **Query Class** handles filtering, searching, sorting
+4. **Model** interacts with database
+5. **Resource** transforms response (optional)
+6. **ApiResponse** standardizes output
+
+### 🎨 API Response Format
+Menggunakan `ApiResponse` helper untuk response konsisten:
+```php
+ApiResponse::success($data, 'Message', 200);
+ApiResponse::error('Error message', 400);
+```
+
+### 📊 Development Tools
+- Query builder pattern
+- File upload service
+- Activity log observers
+- API resource transformers
+
+### ✅ Code Quality
+- Form request validation (22 request classes)
+- Query classes for business logic separation
+- Model observers for event handling
+- Service layer for reusable logic
+- Traits for shared functionality
+
+---
+
+## 🚀 Tech Stack
+
+- **Framework:** Laravel 10.x (^10.10)
+- **PHP:** 8.1+
+- **Authentication:** Laravel Sanctum (^3.3)
+- **Permissions:** Spatie Laravel Permission (^6.13)
+- **API Docs:** Dedoc Scramble (^0.12.35) + Scramble Pro (^0.7.18)
+- **Query Builder:** Spatie Laravel Query Builder (^6.3)
+- **Activity Log:** Spatie Laravel Activity Log (^4.9)
+- **Frontend Build:** Vite
+- **Architecture:** MVC + Query Pattern
+
+---
+
+## 📊 Comparison: Old vs New Structure
+
+### Added Features:
+| Feature | Old Branch | Current Branch |
+|---------|-----------|----------------|
+| Query Classes | ❌ | ✅ (6 classes) |
+| Scramble Config | ❌ | ✅ |
+| Request Classes | 6 | 22 (+267%) |
+| ScrambleServiceProvider | ❌ | ✅ |
+| Telescope | ✅ | ❌ (removed) |
+| Query Stub | ❌ | ✅ |
+
+### Benefits of Current Architecture:
+✅ Better separation of concerns dengan Query classes  
+✅ More granular validation dengan 22+ request classes  
+✅ Cleaner controllers (logic di Query classes)  
+✅ Easier to test (isolated query logic)  
+✅ Scalable untuk fitur complex filtering  
+✅ Professional API documentation dengan Scramble  
+
+---
+
+## 📌 Notes
+
+### Architecture Pattern
+Project ini menggunakan **Query Builder Pattern** sebagai enhancement dari standard MVC:
+
+```
+┌─────────────┐
+│   Request   │ (Validation)
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│ Controller  │ (Routing logic)
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│    Query    │ (Business logic, filtering, sorting)
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│    Model    │ (Data access)
+└──────┬──────┘
+       │
+┌──────▼──────┐
+│  Response   │ (Transform & format)
+└─────────────┘
+```
+
+### Generator Command
+Custom artisan commands untuk generate complete CRUD:
+- Model + Migration
+- Controller (dengan Query integration)
+- **Query class** untuk filtering logic
+- Request validation (Store/Update)
+- Auto-register API routes
+- Support file upload
+
+### API Documentation
+Scramble automatically generates OpenAPI documentation dari:
+- Controller methods
+- FormRequest validation rules
+- Route definitions
+- Model properties
+
+Access di: `/docs/api` (when configured)
+
+---
+
+## 🎓 Best Practices Implemented
+
+1. **Request Validation**: All inputs validated via FormRequest
+2. **Query Separation**: Business logic di Query classes
+3. **Resource Transformation**: Consistent API responses
+4. **Activity Logging**: Automatic via Observers
+5. **Type Hinting**: Strong typing throughout
+6. **API Versioning**: Prepared for V2, V3, etc.
+7. **Documentation**: Auto-generated with Scramble
+
+---
+
+## 📦 Dependencies
+
+### Production
+```json
+{
+  "php": "^8.1",
+  "laravel/framework": "^10.10",
+  "laravel/sanctum": "^3.3",
+  "dedoc/scramble": "^0.12.35",
+  "dedoc/scramble-pro": "^0.7.18",
+  "spatie/laravel-permission": "^6.13",
+  "spatie/laravel-query-builder": "^6.3",
+  "spatie/laravel-activitylog": "^4.9",
+  "guzzlehttp/guzzle": "^7.2",
+  "laravel/tinker": "^2.8"
+}
+```
+
+### Development
+```json
+{
+  "laravel/pint": "^1.0",
+  "laravel/sail": "^1.18",
+  "phpunit/phpunit": "^10.1",
+  "spatie/laravel-ignition": "^2.0",
+  "fakerphp/faker": "^1.9.1",
+  "mockery/mockery": "^1.4.4",
+  "nunomaduro/collision": "^7.0"
+}
+```
+
+---
+
+**Last Updated:** October 2025
+**Laravel Version:** 10.x (^10.10)
+**PHP Version:** 8.1+