docs: update and complete README with advanced features, tree structure, and orchestration details

README.md

@@ -208,3 +208,55 @@ Or evaluate coverage scores:
 ```bash
 php artisan test --coverage
 ```
+
+---
+
+## 📂 Project Directory Structure
+
+```text
+.
+├── app/
+│   ├── Http/
+│   │   ├── Controllers/
+│   │   │   ├── Api/V1/         # Sanctum-protected REST API endpoints
+│   │   │   ├── Auth/           # Full Breeze web and 2FA authentication flow
+│   │   │   ├── Settings/       # Dynamic system configurations and branding controllers
+│   │   │   ├── Dashboard/      # Dynamic home widgets layout engine
+│   │   │   └── Profile/        # Account preferences and session settings
+│   │   └── Middleware/         # Custom CORS, IP blockers, 2FA enforcement
+│   ├── Models/                 # User, Role, Permission, SystemSetting, ActivityLog, DashboardWidget
+│   └── Services/               # Dynamic configuration caches, Excel batching, and remote sync services
+├── bootstrap/                  # Compiled route/config caches
+├── config/                     # Core configs (Spatie matrix, Breeze auth, Inertia, Mail)
+├── database/
+│   ├── migrations/             # Standardized DB schemas (users, roles, permissions, settings, logs)
+│   └── seeders/                # Initial dynamic settings & full RBAC Matrix seeds
+├── docker/                     # Optimized Alpine + PHP-FPM / pgsql / Redis service images
+├── public/                     # Compiled browser-ready front-end assets
+├── resources/
+│   ├── js/
+│   │   ├── Components/         # Reusable dynamic components (Command Palette, Modals, Forms)
+│   │   ├── Layouts/            # Premium dashboard frames, notification panel, global search
+│   │   └── Pages/              # Sleek React + TailwindCSS views (RBAC, Audit Logs, Settings)
+│   └── views/                  # Primary Inertia wrapper template
+├── routes/                     # Structured API, Web, Auth, and System configuration endpoints
+├── storage/                    # Dynamic file assets, private exports, and system logs
+└── tests/                      # Full-featured integration and regression test coverage
+```
+
+---
+
+## 🐳 Architecture & Self-Healing Orchestration (`run.sh`)
+
+The starter kit features an advanced orchestration script (`run.sh`) that automates container configuration and implements robust **Self-Healing Mechanics**:
+
+1. **Port & Instance Conflict Protection**: Scans and gracefully stops local/containerized processes conflicting on ports `8000` (Web), `5432` (Postgres), and `6379` (Redis).
+2. **Zero-Dependency Host Bootstrapping**: Automatically spins up temporary PHP containers to run `composer install` if dependencies are absent, ensuring you can initialize the stack on a completely clean host.
+3. **Database Health Synchronization**: Implements asynchronous health loops checking container states. Database migrations and seeder processes wait precisely until services report a `healthy` state.
+4. **Automatic Workspace Permissions**: Secures and corrects directory owner attributes (`chown` / `chmod`) across compiled Vite bundles and Laravel cache paths.
+
+---
+
+## 📄 License & Terms
+
+Proprietary © 2026 Andika Debi Putra (Debesocial). Designed and packaged to expedite development while aligning with modern security and architectural guidelines. All rights reserved.