Admin Panel

File: 18-admin-panel.md

Loading documentation...

# Admin Panel

## Overview

The admin panel provides administrative control over the platform, including user management, subscription plans, token packages, section system configuration, and platform analytics.

## Access Requirements

- User must be authenticated (`token.auth` middleware)
- User must have `is_admin = true` in the users table
- User must not be suspended (`is_suspended = false`)

All admin endpoints return 403 Unauthorized if these conditions are not met.

## Admin Routes

### Web Routes (`/admin/*`)

Accessible at `/admin/{route}` with authentication:

- **Dashboard**: `/admin/dashboard` - Main admin dashboard view
- **Users**: `/admin/users` - User management interface
- **Plans**: `/admin/plans` - Subscription plan management
- **Token Packages**: `/admin/token-packages` - Token package management
- **Analytics**: `/admin/analytics` - Platform analytics view
- **Settings**: `/admin/settings` - System settings
- **Categories**: `/admin/categories` - Category management
- **Sections**: `/admin/sections` - Section system management
  - Types: `/admin/sections/types`
  - Templates: `/admin/sections/types/{type}/templates`
  - Template Edit: `/admin/sections/types/{type}/templates/{template}/edit`
  - Variables: `/admin/sections/types/{type}/variables`
- **Base Templates**: `/admin/base-templates` - Base template management (resource routes)
- **Notes**: `/admin/notes` - Developer notes dashboard

## API Endpoints

### Dashboard & Statistics

#### Get Dashboard Stats
**GET** `/api/admin/dashboard`

Returns platform statistics:
```json
{
    "success": true,
    "data": {
        "stats": {
            "total_users": 100,
            "active_users": 95,
            "suspended_users": 5,
            "admin_users": 3
        }
    }
}
```

#### Get Recent Activity
**GET** `/api/admin/recent-activity`

Returns last 20 user activities with user information:
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "event_type": "login",
            "description": "User logged in",
            "user": { "id": 1, "name": "John", "email": "john@example.com" },
            "created_at": "2024-06-27 10:00:00",
            "time_ago": "2 hours ago"
        }
    ]
}
```

#### Get Service Balances
**GET** `/api/admin/service-balances`

Returns status and balances for integrated services:
```json
{
    "success": true,
    "data": {
        "twilio": {
            "balance": "$10.50",
            "connection": true
        },
        "openai": {
            "status": { "usage": {...} }
        },
        "stripe": {
            "balance": "$0.00",
            "connection": true
        }
    }
}
```

### User Management

#### List All Users
**GET** `/api/admin/users`

Returns all users with relevant information:
```json
{
    "success": true,
    "users": [
        {
            "id": 1,
            "username": "testuser",
            "name": "Test User",
            "email": "test@example.com",
            "phone": "+1234567890",
            "role": "creator",
            "is_admin": false,
            "is_suspended": false,
            "email_verified_at": "2024-06-27T22:00:00.000000Z",
            "created_at": "2024-06-27T22:00:00.000000Z"
        }
    ]
}
```

#### Suspend User
**POST** `/api/admin/users/{userId}/suspend`

**Body:**
```json
{
    "reason": "Violation of terms of service"
}
```

Suspends a user account. Admins cannot suspend themselves.

#### Unsuspend User
**POST** `/api/admin/users/{userId}/unsuspend`

Removes suspension from a user account.

#### Delete User
**DELETE** `/api/admin/users/{userId}`

**Body:**
```json
{
    "reason": "Account deletion requested"
}
```

Permanently deletes a user account. All related data is handled according to Laravel's model relationships. Admins cannot delete themselves.

#### Toggle Admin Status
**POST** `/api/admin/users/{userId}/toggle-admin`

Toggles admin privileges for a user. Admins cannot modify their own admin status.

### Plan Management

See full documentation in API reference. Key endpoints:

- **List Plans**: `GET /api/admin/plans`
- **Create Plan**: `POST /api/admin/plans`
- **Update Plan**: `PUT /api/admin/plans/{id}`
- **Delete Plan**: `DELETE /api/admin/plans/{id}`
- **Get Statistics**: `GET /api/admin/plans/statistics`
- **Validate All Stripe Plans**: `POST /api/admin/plans/validate-all-stripe`
- **Create Stripe Plan**: `POST /api/admin/plans/{id}/create-stripe`
- **Validate Stripe Plan**: `POST /api/admin/plans/{id}/validate-stripe`

### Token Package Management

- **List Packages**: `GET /api/admin/token-packages`
- **Create Package**: `POST /api/admin/token-packages`
- **Update Package**: `PUT /api/admin/token-packages/{id}`
- **Delete Package**: `DELETE /api/admin/token-packages/{id}`
- **Get Statistics**: `GET /api/admin/token-packages/statistics`
- **Validate All Stripe Prices**: `POST /api/admin/token-packages/validate-all-stripe`
- **Create Stripe Price**: `POST /api/admin/token-packages/{id}/create-stripe`
- **Validate Stripe Price**: `POST /api/admin/token-packages/{id}/validate-stripe`

### Section System Management

#### Section Types
- **List Types**: `GET /api/admin/sections/types`
- **Create Type**: `POST /api/admin/sections/types`
- **Update Type**: `PUT /api/admin/sections/types/{sectionType}`
- **Delete Type**: `DELETE /api/admin/sections/types/{sectionType}`

#### Section Templates
- **List Templates**: `GET /api/admin/sections/types/{sectionType}/templates`
- **Create Template**: `POST /api/admin/sections/types/{sectionType}/templates`
- **Update Template**: `PUT /api/admin/sections/templates/{template}`
- **Update Template Content**: `PUT /api/admin/sections/types/{sectionType}/templates/{sectionTemplate}`
- **Delete Template**: `DELETE /api/admin/sections/templates/{template}`
- **Clone Template**: `POST /api/admin/sections/types/{sectionType}/templates/{sectionTemplate}/clone`
- **Get Template File Content**: `GET /api/admin/sections/types/{sectionType}/templates/{sectionTemplate}/file-content`
- **Generate Template AI Prompt**: `POST /api/admin/sections/ai-prompt`
- **Generate Template with AI**: `POST /api/admin/sections/generate-template`
- **Convert Template to File**: `POST /api/admin/sections/types/{sectionType}/templates/{sectionTemplate}/convert-to-file`

#### Section Variables
- **List Variables**: `GET /api/admin/sections/types/{sectionType}/variables`
- **Create Variable**: `POST /api/admin/sections/types/{sectionType}/variables`
- **Update Variable**: `PUT /api/admin/sections/variables/{sectionVariable}`
- **Delete Variable**: `DELETE /api/admin/sections/variables/{sectionVariable}`

#### Entity Options
- **Get Entity Options**: `GET /api/admin/sections/entity-options`

### Base Template Management

- **Toggle Active**: `POST /api/admin/base-templates/{baseTemplate}/toggle-active`
- **Set Default**: `POST /api/admin/base-templates/{baseTemplate}/set-default`
- **Clone Template**: `POST /api/admin/base-templates/{baseTemplate}/clone`
- **Get File Content**: `GET /api/admin/base-templates/{baseTemplate}/file-content/{type}`
- **Generate AI Prompt**: `POST /api/admin/base-templates/ai-prompt`
- **Delete Template**: `DELETE /api/admin/base-templates/{baseTemplate}`

### Notes Management

- **Get Pages**: `GET /api/admin/notes/pages`
- **Get Page Notes**: `GET /api/admin/notes/page-notes?view_path={path}`

## Admin Functions

### User Activity Logging

All admin actions are automatically logged to the `user_activity_logs` table via the `LogsUserActivity` trait. Logs include:

- Admin user who performed the action
- Target user (if applicable)
- Action type and description
- Metadata (reason, IP address, etc.)
- Timestamp

### Security Features

1. **Self-Protection**: Admins cannot:
   - Suspend themselves
   - Delete themselves
   - Remove their own admin status

2. **Authorization Check**: Every admin endpoint checks:
   ```php
   if (!$user || !$user->canPerformAdminActions()) {
       return response()->json(['success' => false, 'message' => 'Unauthorized access'], 403);
   }
   ```

3. **Activity Logging**: All destructive actions are logged with IP addresses and reasons.

## Usage Examples

### Fetching Dashboard Stats

```javascript
const stats = await apiGet('/api/admin/dashboard');
if (stats.success) {
    console.log('Total users:', stats.data.stats.total_users);
}
```

### Managing Users

```javascript
// Suspend a user
await apiPost(`/api/admin/users/${userId}/suspend`, {
    reason: 'Violation of terms'
});

// Grant admin access
await apiPost(`/api/admin/users/${userId}/toggle-admin`);

// Delete a user
await apiDelete(`/api/admin/users/${userId}`, {
    body: JSON.stringify({ reason: 'Account closure' })
});
```

### Managing Plans

```javascript
// Create a new plan
await apiPost('/api/admin/plans', {
    name: 'Pro Plan',
    slug: 'pro',
    amount: 29.99,
    interval: 'month',
    features: { podcasts: 10, blogs: 5 }
});

// Validate Stripe integration
await apiPost(`/api/admin/plans/${planId}/validate-stripe`);
```

### Checking Service Status

```javascript
const services = await apiGet('/api/admin/service-balances');
if (services.success) {
    console.log('Twilio balance:', services.data.twilio.balance);
    console.log('Stripe connection:', services.data.stripe.connection);
}
```

## Best Practices

1. **Always log reasons** for user actions (suspend, delete)
2. **Verify service status** regularly via `/api/admin/service-balances`
3. **Monitor activity logs** for suspicious admin actions
4. **Test Stripe integration** after creating or updating plans
5. **Use bulk validation** endpoints to check all Stripe plans/prices at once
6. **Review section templates** before making them active
7. **Backup before deleting** critical resources like base templates

## Related Documentation

- **API Reference**: See `docs/03-api-reference.md` for complete endpoint documentation
- **Subscription System**: See `docs/subscription-system.markdown` for plan management details
- **Token System**: See `docs/subscription_token_system.md` for token package details
- **Section System**: See `docs/template` for section system architecture

Admin Panel

Admin Panel

📝 Page Notes

Add New Note