danwel - Platform Administration

Platform-level administration features for managing users, organizations, and system operations.

---

1. [Overview](#overview)
2. [Admin Access](#admin-access)
3. [User Management](#user-management)
4. [Organization Management](#organization-management)
5. [Impersonation System](#impersonation-system)
6. [Demo Mode Management](#demo-mode-management)
7. [Audit Logging](#audit-logging)
8. [System Monitoring](#system-monitoring)
9. [API Endpoints](#api-endpoints)

---

Overview

The admin system provides platform-level management capabilities for danwel administrators. This includes user management, organization oversight, system monitoring, and the ability to impersonate users for support purposes.

Admin Features

• **User Management** - View, manage, and impersonate users

• **Organization Management** - Monitor organization usage and status

• **Demo Mode** - Controlled demo access with restrictions

• **Audit Logging** - Comprehensive system activity tracking

• **System Monitoring** - Log viewing and system health checks

• **Support Tools** - User impersonation for troubleshooting

---

Admin Access

Admin User Flag

Users are marked as platform administrators using the is_admin boolean field:

// Check if user is admin

$user = auth()->user();

if ($user->isAdmin()) {

    // User has platform admin access

}

Admin Route Protection

Admin routes are protected by middleware that checks the admin flag:

Route::prefix('admin')->middleware(['auth', 'admin'])->group(function () {

    // Admin routes

});

Setting Admin Users

Admins can be set via Artisan command:

bash

php artisan admin:set user@example.com



Or programmatically:



$user = User::where('email', 'user@example.com')->first();

$user->update(['is_admin' => true]);
---
User Management




User Dashboard




**Route:** /admin/users

**Controller:** App\Http\Controllers\Admin\UsersController



Features:

• **User Listing** - Paginated list of all platform users


• **Search & Filtering** - Find users by email, name, or organization


• **User Details** - View user profile, organizations, and activity


• **Quick Actions** - Impersonate, suspend, or manage users




User Information Display




// User dashboard shows:

$userData = [

    'id' => $user->id,

    'name' => $user->name,

    'email' => $user->email,

    'email_verified_at' => $user->email_verified_at,

    'is_admin' => $user->is_admin,

    'created_at' => $user->created_at,

    'last_login_at' => $user->last_login_at,

    'organizations_count' => $user->organizations()->count(),

    'authentication_methods' => $user->getAuthenticationMethods(),

    'is_demo' => $user->isDemo(),

];
---
Organization Management




Organization Dashboard




**Route:** /admin/organizations

**Controller:** App\Http\Controllers\Admin\OrganizationsController



Features:

• **Organization Listing** - All organizations with metrics


• **Usage Statistics** - Time blocks, users, integrations per org


• **Subscription Status** - Trial/active/canceled status tracking


• **Quick Actions** - View details, manage settings




Organization Metrics




$orgMetrics = [

    'users_count' => $org->users()->count(),

    'time_blocks_count' => $org->timeBlocks()->count(),

    'integrations_count' => $org->integrations()->count(),

    'projects_count' => $org->projects()->count(),

    'clients_count' => $org->clients()->count(),

    'subscription_status' => $org->subscription_status,

    'trial_ends_at' => $org->trial_ends_at,

    'created_at' => $org->created_at,

];
---
Impersonation System




How Impersonation Works
Administrators can impersonate users to troubleshoot issues or provide support. The system maintains the admin's original session while switching to the target user's context.
Starting Impersonation




// Impersonate specific user

POST /admin/users/{user}/impersonate



// Impersonate demo user

POST /admin/impersonate/demo




Impersonation State
The system tracks impersonation using:
// Session keys

session()->put('impersonating_user_id', $targetUser->id);

session()->put('original_user_id', $admin->id);



// Context service

app(TenantContext::class)->isImpersonating(); // returns true




Stopping Impersonation




// Stop impersonation and return to admin

GET|POST /admin/impersonate/stop




Impersonation MiddlewareThe RestoreImpersonationContext middleware:
1. Checks for impersonation session data

2. Authenticates as the impersonated user

3. Maintains admin privileges for bypassing restrictions

4. Shows impersonation indicator in UI---
Demo Mode Management




Demo User System
Danwel includes a special demo mode for showcasing the platform:
// Demo user identification

$isDemoUser = $user->isDemo(); // checks against DEMO_USER_EMAIL



// Demo mode checks

if (env('DEMO_MODE_ALLOWED', false)) {

    // Demo functionality enabled

}




Demo RestrictionsDemo mode applies restrictions via the RestrictDemoUser middleware:
• **No destructive actions** - Prevent deletions, permanent changes


• **Limited integrations** - Restricted OAuth connections


• **Data isolation** - Demo data is separate from real user data


• **Auto-logout** - Sessions may be automatically terminated




Demo Data




Demo mode includes:

• **Pre-populated projects and clients**


• **Sample time blocks and entries**


• **Realistic calendar events**


• **Example integrations** (read-only)




Demo Bypass
Admins can bypass demo restrictions:
$user->canBypassDemoRestrictions(); // true for admins or when impersonating
---
Audit Logging




Audit Log Model




// AuditLog model

$auditLog = [

    'id' => 1,

    'organization_id' => 1, // null for system events

    'user_id' => 1,

    'action' => 'user.impersonated',

    'auditable_type' => 'App\Models\User',

    'auditable_id' => 2,

    'old_values' => ['status' => 'active'],

    'new_values' => ['status' => 'suspended'],

    'ip_address' => '192.168.1.1',

    'user_agent' => 'Mozilla/5.0...',

    'created_at' => '2024-01-01T00:00:00Z'

];




Logged Actions




The system automatically logs:

• **User actions** - Login, logout, profile changes


• **Admin actions** - Impersonation, user management


• **System events** - Integration connections, errors


• **Security events** - Failed logins, permission changes




Audit Dashboard




**Route:** /admin/audit-log

**Controller:** App\Http\Controllers\Admin\AuditLogController



Features:

• **Event Filtering** - By user, action, date range


• **Search** - Full-text search across audit events


• **Export** - Download audit logs for compliance


• **Real-time** - Live updates of system activity
---
System Monitoring




Log Viewer




**Route:** /admin/logs

**Controller:** App\Http\Controllers\Admin\LogViewerController



Features:

• **Laravel Logs** - View application logs in real-time


• **Log Filtering** - Filter by level (error, warning, info)


• **Log Search** - Search through log contents


• **Download** - Download log files for analysis




System Health Checks




Admins can monitor:

• **Database Connectivity** - Connection status and performance


• **Queue Status** - Job processing and failures


• **Integration Health** - OAuth token status and API connectivity


• **Storage Usage** - Disk space and file storage metrics




Analytics Dashboard
The admin panel includes access to request analytics:
// Analytics access check

$user->canAccessAnalyticsDashboard(); // true for admins




This provides insights into:

• **Request Patterns** - API usage and popular endpoints


• **User Activity** - Login patterns and feature usage


• **Performance Metrics** - Response times and error rates


• **Growth Metrics** - User and organization growth
---
API Endpoints




Admin User Management


http

GET    /admin/users                    # List all users

GET    /admin/users/{user}             # Get user details

POST   /admin/users/{user}/impersonate # Start impersonating user

POST   /admin/users/{user}/suspend     # Suspend user account

POST   /admin/users/{user}/unsuspend   # Restore user account



Admin Organization Management


http

GET    /admin/organizations            # List all organizations

GET    /admin/organizations/{org}      # Get organization details

PATCH  /admin/organizations/{org}      # Update organization settings



Impersonation Control


http

POST   /admin/impersonate/demo         # Impersonate demo user

POST   /admin/impersonate/{user}       # Impersonate specific user

GET    /admin/impersonate/stop         # Stop impersonation

POST   /admin/impersonate/stop         # Stop impersonation (POST)



Audit and Monitoring


http

GET    /admin/audit-log                # View audit events

GET    /admin/logs                     # View system logs

GET    /admin/system-health            # System health check

---
Security Considerations




Admin Privilege Escalation

• **Admin flag verification** - Always verify is_admin` flag

• **Session validation** - Validate admin sessions on sensitive operations

• **Audit trail** - All admin actions are logged

Impersonation Security

• **Original user tracking** - Always maintain original admin identity

• **Session isolation** - Impersonation doesn't affect admin privileges

• **Automatic cleanup** - Impersonation sessions expire automatically

• **Audit logging** - All impersonation events are logged

Demo Mode Security

• **Data isolation** - Demo data cannot affect real users

• **Action restrictions** - Destructive actions are blocked

• **Session limits** - Demo sessions may have time limits

• **IP restrictions** - Demo access may be IP-restricted

---

Usage Examples

Checking Admin Status

// In a controller

public function adminOnly()

{

    if (!auth()->user()->isAdmin()) {

        abort(403, 'Admin access required');

    }



    // Admin functionality

}



// In a view

@if(auth()->user()->isAdmin())

    Admin Panel

@endif

Impersonation Context

// Check if currently impersonating

$tenantContext = app(TenantContext::class);

if ($tenantContext->isImpersonating()) {

    // Show impersonation banner

    $originalUser = User::find(session('original_user_id'));

    $impersonatedUser = auth()->user();

}

Demo Mode Restrictions

// In middleware or controller

if (auth()->user()->isDemo() && !auth()->user()->canBypassDemoRestrictions()) {

    return response()->json(['error' => 'Demo mode restriction'], 403);

}

Audit Log Creation

// Manually log an event

AuditLog::create([

    'organization_id' => $currentOrg->id,

    'user_id' => auth()->id(),

    'action' => 'integration.connected',

    'auditable_type' => Integration::class,

    'auditable_id' => $integration->id,

    'new_values' => ['provider' => $integration->provider],

    'ip_address' => request()->ip(),

    'user_agent' => request()->userAgent(),

]);

---

This admin system provides comprehensive platform management while maintaining security and auditability for all administrative actions.

Table of Contents

danwel - Platform Administration

Table of Contents

Overview

Admin Features

Admin Access

Admin User Flag

Admin Route Protection

Setting Admin Users

User Management

User Dashboard

User Information Display

Organization Management

Organization Dashboard

Organization Metrics

Impersonation System

How Impersonation Works

Starting Impersonation

Impersonation State

Stopping Impersonation

Impersonation Middleware

Demo Mode Management

Demo User System

Demo Restrictions

Demo Data

Demo Bypass

Audit Logging

Audit Log Model

Logged Actions

Audit Dashboard

System Monitoring

Log Viewer

System Health Checks

Analytics Dashboard

API Endpoints

Admin User Management

Admin Organization Management

Impersonation Control

Audit and Monitoring

Security Considerations

Admin Privilege Escalation

Impersonation Security

Demo Mode Security

Usage Examples

Checking Admin Status

Impersonation Context

Demo Mode Restrictions

Audit Log Creation

Table of Contents