@fleetbase/solid-engine 0.0.4 → 0.0.5

package/REFACTORING_SUMMARY.md

@@ -0,0 +1,330 @@
+# Solid Extension Refactoring Summary
+
+## Overview
+Refactored the Fleetbase Solid Protocol extension from a multi-pod architecture to a single-pod architecture with user-friendly terminology.
+
+## Key Changes
+
+### Terminology Updates
+- **"Pods" → "Data"**: More intuitive for users to understand they're managing their data
+- **"Container" → "Folder"**: Familiar file system metaphor instead of technical Solid terminology
+
+### Architecture Shift
+**Before (Multi-Pod):**
+- Users could create multiple pods
+- Complex pod listing and management UI
+- Cross-pod authentication issues
+- Routes: `pods`, `pods.index`, `pods.explorer`, `pods.index.pod`
+
+**After (Single-Pod):**
+- Users have ONE primary pod from OIDC authentication
+- Data organized in folders within the pod (vehicles/, drivers/, contacts/, orders/)
+- Simplified permissions model
+- Routes: `data`, `data.content`
+
+---
+
+## Frontend Changes
+
+### Routes Refactored
+**File:** `addon/routes.js`
+
+**Old Structure:**
+```javascript
+this.route('pods', function () {
+    this.route('explorer', { path: '/explorer/:id' }, function () {
+        this.route('content', { path: '/~/:slug' });
+    });
+    this.route('index', { path: '/' }, function () {
+        this.route('pod', { path: '/pod/:slug' });
+    });
+});
+```
+
+**New Structure:**
+```javascript
+this.route('data', { path: '/data' }, function () {
+    this.route('content', { path: '/:slug' });
+});
+```
+
+### Files Created
+1. **`addon/routes/data/index.js`** - Main data browser route
+2. **`addon/routes/data/content.js`** - Folder navigation route
+3. **`addon/controllers/data/index.js`** - Data browser controller with folder operations
+4. **`addon/controllers/data/content.js`** - Folder content controller
+5. **`addon/templates/data/index.hbs`** - Data browser template
+6. **`addon/templates/data/content.hbs`** - Folder content viewer template
+
+### Files Removed
+- `addon/routes/pods/` (entire directory)
+- `addon/controllers/pods/` (entire directory)
+- `addon/templates/pods/` (entire directory)
+
+### Files Updated
+1. **`addon/templates/application.hbs`**
+   - Updated sidebar navigation: `console.solid-protocol.pods` → `console.solid-protocol.data`
+
+2. **`addon/templates/home.hbs`**
+   - "Browse Pods" → "Browse Data"
+   - "Explore and manage your Solid pods" → "Explore and manage your Fleetops data in Solid"
+   - Updated all pod references to use "storage" terminology
+
+3. **`addon/controllers/home.js`**
+   - `navigateToPods()` now routes to `console.solid-protocol.data`
+
+---
+
+## Backend Changes
+
+### New Controller
+**File:** `server/src/Http/Controllers/DataController.php`
+
+**Methods:**
+- `index()` - Get root level contents of user's pod
+- `showFolder($slug)` - Get contents of a specific folder
+- `createFolder()` - Create a new folder in the pod
+- `deleteItem($type, $slug)` - Delete a file or folder
+- `importResources()` - Import Fleetops resources into folders
+
+### Routes Updated
+**File:** `server/src/routes.php`
+
+**Old Routes:**
+```php
+$router->get('pods', 'PodController@index');
+$router->post('pods', 'PodController@create');
+$router->get('pods/{podId}', 'PodController@show');
+$router->delete('pods/{podId}', 'PodController@destroy');
+$router->post('import-resources', 'PodController@importResources');
+
+$router->get('containers', 'ContainerController@index');
+$router->post('containers', 'ContainerController@create');
+$router->delete('containers/{containerName}', 'ContainerController@destroy');
+```
+
+**New Routes:**
+```php
+$router->get('data', 'DataController@index');
+$router->get('data/folder/{slug}', 'DataController@showFolder');
+$router->post('data/folder', 'DataController@createFolder');
+$router->delete('data/{type}/{slug}', 'DataController@deleteItem');
+$router->post('data/import', 'DataController@importResources');
+```
+
+### Service Methods Added
+**File:** `server/src/Services/PodService.php`
+
+**New Methods:**
+- `createFolder(SolidIdentity $identity, string $folderUrl): bool`
+  - Creates a folder (LDP BasicContainer) in the pod
+  - Uses PUT request with proper Content-Type and Link headers
+
+- `deleteResource(SolidIdentity $identity, string $resourceUrl): bool`
+  - Deletes a file or folder from the pod
+  - Uses DELETE request
+
+**Existing Method Used:**
+- `getPodUrlFromWebId(string $webId): string`
+  - Extracts the pod URL from the user's WebID
+  - Example: `http://solid:3000/test/profile/card#me` → `http://solid:3000/test/`
+
+---
+
+## API Endpoint Mapping
+
+### Frontend → Backend
+| Frontend Route | API Endpoint | Controller Method |
+|----------------|--------------|-------------------|
+| `data.index` | `GET /data` | `DataController@index` |
+| `data.content/:slug` | `GET /data/folder/:slug` | `DataController@showFolder` |
+| Create folder action | `POST /data/folder` | `DataController@createFolder` |
+| Delete item action | `DELETE /data/:type/:slug` | `DataController@deleteItem` |
+| Import resources | `POST /data/import` | `DataController@importResources` |
+
+---
+
+## User Experience Improvements
+
+### Navigation
+- **Sidebar:** "Data" instead of "Pods"
+- **Home Page:** "Browse Data" quick action
+- **Breadcrumbs:** Will show folder hierarchy instead of pod names
+
+### Data Browser Features
+1. **Folder Management**
+   - Create new folders with "New Folder" button
+   - Browse folders like a file explorer
+   - Delete folders and files
+
+2. **Resource Import**
+   - "Import Resources" button in data browser
+   - Select resource types: Vehicles, Drivers, Contacts, Orders
+   - Resources imported into respective folders in the pod
+
+3. **File Operations**
+   - View file information in overlay
+   - Open files in new tab
+   - Delete files with confirmation
+
+---
+
+## Technical Benefits
+
+### Simplified Architecture
+1. **No Multi-Pod Management**
+   - Removed pod listing complexity
+   - Removed pod creation/deletion UI
+   - Removed pod selection logic
+
+2. **Single Authentication Flow**
+   - One DPoP-bound access token for the user's pod
+   - No cross-pod permission issues
+   - Cleaner token management
+
+3. **Standard Solid Patterns**
+   - Follows Solid specification for single-pod-per-user
+   - Uses LDP containers (folders) for organization
+   - Proper RDF/Turtle format for resources
+
+### Code Cleanliness
+1. **Removed Unused Code**
+   - Deleted 12 files related to multi-pod management
+   - Removed unused routes and controllers
+   - Cleaner route structure (2 routes vs 4)
+
+2. **Clear Naming**
+   - `DataController` vs `PodController` - clearer intent
+   - `data/folder` routes - self-documenting
+   - User-facing terms match technical implementation
+
+---
+
+## Data Organization
+
+### Pod Structure
+```
+http://solid:3000/user/
+├── vehicles/
+│   ├── vehicle-uuid-1.ttl
+│   ├── vehicle-uuid-2.ttl
+│   └── ...
+├── drivers/
+│   ├── driver-uuid-1.ttl
+│   └── ...
+├── contacts/
+│   ├── contact-uuid-1.ttl
+│   └── ...
+└── orders/
+    ├── order-uuid-1.ttl
+    └── ...
+```
+
+### Resource Format
+Each resource is stored as an RDF/Turtle file with semantic metadata following Solid conventions.
+
+---
+
+## Next Steps
+
+### Testing Required
+1. **Authentication Flow**
+   - Verify OIDC authentication still works
+   - Check DPoP token binding
+   - Confirm pod URL extraction from WebID
+
+2. **Data Browser**
+   - Test folder creation
+   - Test folder navigation
+   - Test file deletion
+   - Test search functionality
+
+3. **Resource Import**
+   - Test importing vehicles
+   - Test importing drivers
+   - Test importing contacts
+   - Test importing orders
+   - Verify RDF/Turtle format
+   - Check folder creation for each resource type
+
+4. **Error Handling**
+   - Test 401 unauthorized scenarios
+   - Test invalid folder names
+   - Test deleting non-existent resources
+
+### Future Enhancements
+1. **Incremental Sync**
+   - Only sync changed resources
+   - Track last sync timestamp
+   - Show sync status per resource type
+
+2. **Resource Filtering**
+   - Filter by date range
+   - Filter by status
+   - Search within resources
+
+3. **Sync History**
+   - Track sync operations
+   - Show sync logs
+   - Rollback capability
+
+4. **Real-time Sync**
+   - Webhook integration with Fleetops
+   - Automatic sync on data changes
+   - Conflict resolution
+
+---
+
+## Migration Notes
+
+### For Developers
+- Update any references to `pods` routes to use `data` routes
+- Replace `PodController` usage with `DataController`
+- Update API calls from `import-resources` to `data/import`
+- Remove any pod selection logic from components
+
+### For Users
+- Existing data: Users will need to re-import resources into their primary pod
+- No action required for authentication - existing OIDC flow remains the same
+- UI will automatically reflect new "Data" terminology
+
+---
+
+## Files Modified Summary
+
+### Created (7 files)
+- `addon/routes/data/index.js`
+- `addon/routes/data/content.js`
+- `addon/controllers/data/index.js`
+- `addon/controllers/data/content.js`
+- `addon/templates/data/index.hbs`
+- `addon/templates/data/content.hbs`
+- `server/src/Http/Controllers/DataController.php`
+
+### Modified (6 files)
+- `addon/routes.js`
+- `addon/templates/application.hbs`
+- `addon/templates/home.hbs`
+- `addon/controllers/home.js`
+- `server/src/routes.php`
+- `server/src/Services/PodService.php`
+
+### Deleted (12 files)
+- `addon/routes/pods/explorer.js`
+- `addon/routes/pods/explorer/content.js`
+- `addon/routes/pods/index.js`
+- `addon/routes/pods/index/pod.js`
+- `addon/controllers/pods/explorer.js`
+- `addon/controllers/pods/explorer/content.js`
+- `addon/controllers/pods/index.js`
+- `addon/controllers/pods/index/pod.js`
+- `addon/templates/pods/explorer.hbs`
+- `addon/templates/pods/explorer/content.hbs`
+- `addon/templates/pods/index.hbs`
+- `addon/templates/pods/index/pod.hbs`
+
+---
+
+## Conclusion
+
+This refactoring significantly simplifies the Solid extension architecture while improving user experience through familiar terminology. The single-pod approach aligns with Solid best practices and eliminates cross-pod authentication complexity. The codebase is now cleaner, more maintainable, and easier for developers to understand.

package/VERIFICATION_CHECKLIST.md

@@ -0,0 +1,82 @@
+# Refactoring Verification Checklist
+
+## Code Cleanup ✓
+- [x] Removed old `addon/routes/pods/` directory
+- [x] Removed old `addon/controllers/pods/` directory  
+- [x] Removed old `addon/templates/pods/` directory
+- [x] Removed `server/src/Http/Controllers/PodController.php`
+- [x] Removed `server/src/Http/Controllers/ContainerController.php`
+- [x] Removed commented code from `addon/templates/application.hbs`
+- [x] Removed commented routes from `server/src/routes.php`
+
+## New Files Created ✓
+- [x] `addon/routes/data/index.js`
+- [x] `addon/routes/data/content.js`
+- [x] `addon/controllers/data/index.js`
+- [x] `addon/controllers/data/content.js`
+- [x] `addon/templates/data/index.hbs`
+- [x] `addon/templates/data/content.hbs`
+- [x] `server/src/Http/Controllers/DataController.php`
+
+## Routes Updated ✓
+- [x] `addon/routes.js` - Simplified to data routes
+- [x] `server/src/routes.php` - Updated API endpoints
+
+## Templates Updated ✓
+- [x] `addon/templates/application.hbs` - Sidebar navigation
+- [x] `addon/templates/home.hbs` - Quick actions and terminology
+
+## Controllers Updated ✓
+- [x] `addon/controllers/home.js` - Navigation method
+
+## Services Updated ✓
+- [x] `server/src/Services/PodService.php` - Added createFolder() and deleteResource()
+
+## Terminology Changes ✓
+- [x] "Pods" → "Data" throughout UI
+- [x] "Container" → "Folder" in code comments and user-facing text
+- [x] Updated all user-facing messages
+
+## Testing Required
+- [ ] OIDC authentication flow
+- [ ] Pod URL extraction from WebID
+- [ ] Data browser loads correctly
+- [ ] Folder creation works
+- [ ] Folder navigation works
+- [ ] File/folder deletion works
+- [ ] Resource import (vehicles, drivers, contacts, orders)
+- [ ] Search functionality
+- [ ] Error handling (401, invalid inputs)
+
+## API Endpoints to Test
+
+### GET /solid/int/v1/data
+Expected: Returns root contents of user's pod
+
+### GET /solid/int/v1/data/folder/{slug}
+Expected: Returns contents of specified folder
+
+### POST /solid/int/v1/data/folder
+Payload: `{ "name": "test-folder", "path": "" }`
+Expected: Creates new folder
+
+### DELETE /solid/int/v1/data/{type}/{slug}
+Example: `DELETE /solid/int/v1/data/folder/vehicles`
+Expected: Deletes specified folder or file
+
+### POST /solid/int/v1/data/import
+Payload: `{ "resource_types": ["vehicles", "drivers"] }`
+Expected: Imports selected resources into folders
+
+## Files Count Summary
+- **Created:** 7 files
+- **Modified:** 6 files
+- **Deleted:** 14 files (12 frontend + 2 backend)
+- **Net change:** -1 files (cleaner codebase!)
+
+## Code Quality Checks
+- [x] No references to old `pods.explorer` or `pods.index` routes
+- [x] No references to `PodController` or `ContainerController`
+- [x] All imports and dependencies updated
+- [x] Consistent naming conventions (data/folder)
+- [x] Clean, readable code structure

package/addon/components/modals/create-solid-folder.hbs

@@ -0,0 +1,29 @@
+<Modal::Default 
+    @modalIsOpened={{@modalIsOpened}} 
+    @options={{@options}} 
+    @confirm={{@options.confirm}} 
+    @decline={{@options.decline}}
+>
+    <div class="modal-body-container">
+        <div class="space-y-4">
+            <InputGroup @name="Folder Name" @wrapperClass="mb-0">
+                <Input 
+                    @type="text" 
+                    @value={{@options.folderName}}
+                    placeholder="Enter folder name (e.g., vehicles, drivers)" 
+                    class="w-full form-input"
+                />
+            </InputGroup>
+
+            <div class="text-sm text-gray-600 dark:text-gray-400">
+                <p>This will create a new folder in your Solid pod for organizing your data.</p>
+            </div>
+
+            {{#if @options.error}}
+                <div class="bg-red-50 dark:bg-red-900 border border-red-200 dark:border-red-700 rounded p-3">
+                    <p class="text-sm text-red-800 dark:text-red-200">{{@options.error}}</p>
+                </div>
+            {{/if}}
+        </div>
+    </div>
+</Modal::Default>

package/addon/components/modals/import-solid-resources.hbs

@@ -0,0 +1,85 @@
+<Modal::Default 
+    @modalIsOpened={{@modalIsOpened}} 
+    @options={{@options}} 
+    @confirm={{@options.confirm}} 
+    @decline={{@options.decline}}
+>
+    <div class="modal-body-container">
+        <div class="space-y-4">
+            <div>
+                <p class="text-gray-700 dark:text-gray-300 mb-4">
+                    Select the Fleetops resources you want to import into your Solid pod:
+                </p>
+
+                <div class="space-y-3">
+                    <label class="flex items-center p-3 bg-gray-50 dark:bg-gray-800 rounded cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700">
+                        <input 
+                            type="checkbox" 
+                            checked={{@options.resourceTypes.vehicles}}
+                            {{on "change" (fn @options.toggleResourceType "vehicles")}}
+                            class="form-checkbox h-5 w-5 text-blue-600"
+                        />
+                        <div class="ml-3">
+                            <div class="font-medium text-gray-900 dark:text-white">Vehicles</div>
+                            <div class="text-sm text-gray-600 dark:text-gray-400">Import all vehicles from Fleetops</div>
+                        </div>
+                    </label>
+
+                    <label class="flex items-center p-3 bg-gray-50 dark:bg-gray-800 rounded cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700">
+                        <input 
+                            type="checkbox" 
+                            checked={{@options.resourceTypes.drivers}}
+                            {{on "change" (fn @options.toggleResourceType "drivers")}}
+                            class="form-checkbox h-5 w-5 text-blue-600"
+                        />
+                        <div class="ml-3">
+                            <div class="font-medium text-gray-900 dark:text-white">Drivers</div>
+                            <div class="text-sm text-gray-600 dark:text-gray-400">Import all drivers from Fleetops</div>
+                        </div>
+                    </label>
+
+                    <label class="flex items-center p-3 bg-gray-50 dark:bg-gray-800 rounded cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700">
+                        <input 
+                            type="checkbox" 
+                            checked={{@options.resourceTypes.contacts}}
+                            {{on "change" (fn @options.toggleResourceType "contacts")}}
+                            class="form-checkbox h-5 w-5 text-blue-600"
+                        />
+                        <div class="ml-3">
+                            <div class="font-medium text-gray-900 dark:text-white">Contacts</div>
+                            <div class="text-sm text-gray-600 dark:text-gray-400">Import all contacts/customers from Fleetops</div>
+                        </div>
+                    </label>
+
+                    <label class="flex items-center p-3 bg-gray-50 dark:bg-gray-800 rounded cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700">
+                        <input 
+                            type="checkbox" 
+                            checked={{@options.resourceTypes.orders}}
+                            {{on "change" (fn @options.toggleResourceType "orders")}}
+                            class="form-checkbox h-5 w-5 text-blue-600"
+                        />
+                        <div class="ml-3">
+                            <div class="font-medium text-gray-900 dark:text-white">Orders</div>
+                            <div class="text-sm text-gray-600 dark:text-gray-400">Import all orders from Fleetops</div>
+                        </div>
+                    </label>
+                </div>
+            </div>
+
+            {{#if @options.importProgress}}
+                <div class="bg-blue-50 dark:bg-blue-900 border border-blue-200 dark:border-blue-700 rounded p-3">
+                    <div class="flex items-center">
+                        <Spinner class="mr-3" />
+                        <p class="text-sm text-blue-800 dark:text-blue-200">{{@options.importProgress}}</p>
+                    </div>
+                </div>
+            {{/if}}
+
+            {{#if @options.error}}
+                <div class="bg-red-50 dark:bg-red-900 border border-red-200 dark:border-red-700 rounded p-3">
+                    <p class="text-sm text-red-800 dark:text-red-200">{{@options.error}}</p>
+                </div>
+            {{/if}}
+        </div>
+    </div>
+</Modal::Default>

package/addon/controllers/data/content.js

@@ -0,0 +1,17 @@
+import Controller from '@ember/controller';
+import { action } from '@ember/object';
+import { inject as service } from '@ember/service';
+
+export default class DataContentController extends Controller {
+    @service hostRouter;
+
+    @action back() {
+        this.hostRouter.transitionTo('console.solid-protocol.data.index');
+    }
+
+    @action viewFile() {
+        if (this.model.url) {
+            window.open(this.model.url, '_blank');
+        }
+    }
+}