# Admin Instance Management System - Implementation Plan

## Overview
Implement a comprehensive admin panel for managing Wakel AI instances with lifecycle management, auto-deletion, and restore capabilities.

---

## Current System Analysis

### Existing Components
- **Admin Dashboard**: `/src/app/admin/page.tsx` - Shows basic stats
- **Managed Instances Page**: `/src/app/admin/managed-instances/page.tsx` - Lists all instances
- **Authentication**: NextAuth.js with email/password
- **Database**: PostgreSQL with Prisma ORM
- **Instance Model**: `Instance` table with basic fields (status, dates, port, etc.)

### Current Limitations
1. No admin-specific role/permission system
2. No soft delete mechanism
3. No instance lifecycle tracking (deleted_at, scheduled_deletion_date)
4. No admin login as user functionality
5. No configurable retention period
6. No auto-deletion cron job

---

## Implementation Plan

### Phase 1: Database Schema Changes

**Additions to `prisma/schema.prisma`:**

```prisma
// Add to existing User model
model User {
  // ... existing fields
  role            UserRole       @default(USER)
  adminSettings   AdminSettings?
}

enum UserRole {
  USER
  ADMIN
}

// New model for admin settings
model AdminSettings {
  id                    String   @id @default(cuid())
  userId                String   @unique
  user                  User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  instanceRetentionDays Int      @default(7)
  createdAt            DateTime @default(now())
  updatedAt            DateTime @updatedAt
}

// Add to existing Instance model
model Instance {
  // ... existing fields
  deletedAt             DateTime?
  scheduledDeletionDate DateTime?
  restoredAt            DateTime?
  deletedBy             String?
  restoredBy            String?
}
```

---

### Phase 2: Admin Authorization & Middleware

**Files to create:**
- `/src/lib/admin-auth.ts` - Admin role checking
- `/src/middleware.ts` - Route protection

**Functionality:**
- Check if user has ADMIN role
- Protect admin routes
- Add admin role checks to API routes

---

### Phase 3: Enhanced Admin Instance Management Page

**Update `/src/app/admin/managed-instances/page.tsx`:**

**Features to implement:**
1. **Instance List with Enhanced Info**
   - Instance name
   - Owner email/name
   - Status (RUNNING, STOPPED, DELETED, ERROR)
   - Created date
   - Deleted date (if deleted)
   - Scheduled deletion date (if pending)
   - Port
   - Actions

2. **Admin Actions**
   - Login as user (impersonate)
   - View instance details
   - Stop instance
   - Delete instance (soft delete)
   - Restore instance
   - Force delete (immediate)

3. **Filtering & Search**
   - Filter by status
   - Filter by owner
   - Search by name/slug
   - Show deleted instances toggle

---

### Phase 4: Instance Lifecycle Management

**API Endpoints to create:**

1. **`POST /api/admin/instances/[id]/stop`**
   - Stop Docker container
   - Update status to STOPPED
   - Set scheduledDeletionDate to now + retentionDays

2. **`POST /api/admin/instances/[id]/delete`**
   - Soft delete (mark deletedAt)
   - Keep Docker container running for restore capability
   - Set scheduledDeletionDate to now + retentionDays

3. **`POST /api/admin/instances/[id]/restore`**
   - Clear deletedAt and scheduledDeletionDate
   - Set restoredAt and restoredBy
   - Start Docker container if stopped
   - Update status to RUNNING

4. **`DELETE /api/admin/instances/[id]/force`**
   - Hard delete (permanent)
   - Remove Docker container
   - Release port
   - Remove nginx config
   - Delete from database

5. **`POST /api/admin/instances/[id]/login-as-user`**
   - Generate admin impersonation token
   - Create session for target user
   - Redirect to user dashboard

---

### Phase 5: Admin Settings Page

**Update `/src/app/admin/settings/page.tsx`:**

**Settings to implement:**
1. **Instance Retention Period**
   - Number input field (default: 7)
   - Range: 1-90 days
   - Save to AdminSettings

2. **Auto-Deletion Schedule**
   - Display cron job status
   - Show next run time
   - Manual trigger button

3. **Statistics**
   - Total instances
   - Active instances
   - Stopped instances
   - Soft deleted instances
   - Pending deletion instances

---

### Phase 6: Auto-Deletion Cron Job

**Create `/src/lib/cron/auto-delete-instances.ts`:**

**Functionality:**
```typescript
// Run daily to permanently delete instances past retention period
async function autoDeleteExpiredInstances() {
  const expiredInstances = await prisma.instance.findMany({
    where: {
      status: 'STOPPED',
      scheduledDeletionDate: { lte: new Date() }
    },
    include: { user: true }
  });

  for (const instance of expiredInstances) {
    // 1. Stop and remove Docker container
    // 2. Release allocated port
    // 3. Remove nginx config
    // 4. Hard delete from database
    // 5. Log deletion
  }
}
```

**Create API endpoint: `/api/admin/cron/auto-delete`**
- Secured with admin check
- Can be triggered by external cron service
- Returns summary of deletions

---

### Phase 7: UI Components

**Components to create:**

1. **`/src/components/admin/instance-actions.tsx`**
   - Stop button
   - Delete button (with confirmation)
   - Restore button
   - Login as user button

2. **`/src/components/admin/instance-status-badge.tsx`**
   - Color-coded status badges
   - Show deletion countdown if scheduled

3. **`/src/components/admin/delete-confirmation-modal.tsx`**
   - Show retention period
   - Explain soft delete behavior
   - Confirm or cancel

4. **`/src/components/admin/retention-setting.tsx`**
   - Number input for days
   - Save button
   - Display current value

---

### Phase 8: Docker & nginx Integration

**Update `/src/lib/dokploy.ts`:**
- Add `stopContainer()` function
- Add `removeContainer()` function
- Add `isContainerRunning()` function

**Update `/src/lib/nginx-manager.ts`:**
- Add `removeInstanceConfig()` function
- Ensure proper reload after removal

**Create `/src/lib/port-allocator.ts`:**
- Ensure `releasePort()` is called on deletion

---

## File Structure

```
src/
├── app/
│   ├── admin/
│   │   ├── managed-instances/
│   │   │   ├── page.tsx (UPDATE)
│   │   │   └── [id]/
│   │   │       └── page.tsx (NEW - instance details)
│   │   ├── settings/
│   │   │   └── page.tsx (UPDATE)
│   │   └── layout.tsx (UPDATE - add admin check)
│   └── api/
│       ├── admin/
│       │   ├── instances/
│       │   │   ├── [id]/
│       │   │   │   ├── stop/route.ts (NEW)
│       │   │   │   ├── delete/route.ts (NEW)
│       │   │   │   ├── restore/route.ts (NEW)
│       │   │   │   ├── force-delete/route.ts (NEW)
│       │   │   │   └── login-as-user/route.ts (NEW)
│       │   │   └── route.ts (UPDATE - admin list)
│       │   ├── settings/
│       │   │   └── retention/route.ts (NEW)
│       │   └── cron/
│       │       └── auto-delete/route.ts (NEW)
│       └── instances/
│           ├── [id]/
│           │   └── route.ts (UPDATE - add soft delete)
├── components/
│   └── admin/
│       ├── admin-shell.tsx (UPDATE - add admin check)
│       ├── instance-actions.tsx (NEW)
│       ├── instance-status-badge.tsx (NEW)
│       ├── delete-confirmation-modal.tsx (NEW)
│       └── retention-setting.tsx (NEW)
├── lib/
│   ├── admin-auth.ts (NEW)
│   ├── cron/
│   │   └── auto-delete-instances.ts (NEW)
│   ├── dokploy.ts (UPDATE)
│   ├── nginx-manager.ts (UPDATE)
│   └── port-allocator.ts (UPDATE)
├── middleware.ts (NEW)
└── prisma/
    └── schema.prisma (UPDATE)
```

---

## Implementation Order

1. **Database Schema** (1-2 hours)
   - Update Prisma schema
   - Run migrations
   - Seed default admin settings

2. **Admin Auth** (2-3 hours)
   - Create admin auth lib
   - Add middleware
   - Update admin layout

3. **Instance Lifecycle API** (3-4 hours)
   - Stop endpoint
   - Delete endpoint
   - Restore endpoint
   - Force delete endpoint

4. **Admin Instance Management UI** (4-5 hours)
   - Update instances list page
   - Add status badges
   - Add action buttons
   - Add filtering/search

5. **Login as User** (2-3 hours)
   - Impersonation API
   - UI integration
   - Security considerations

6. **Settings Page** (2-3 hours)
   - Retention period setting
   - Stats display
   - Save functionality

7. **Auto-Deletion Cron** (2-3 hours)
   - Cron job function
   - API endpoint
   - Docker cleanup integration

8. **Testing & Polish** (2-3 hours)
   - End-to-end testing
   - UI polish
   - Error handling

**Total Estimated Time: 18-26 hours**

---

## Security Considerations

1. **Admin Role Enforcement**
   - All admin API endpoints must verify admin role
   - Middleware protection for admin routes
   - Audit logging for admin actions

2. **Impersonation Security**
   - Log all impersonation attempts
   - Show "Acting as admin" banner when impersonating
   - Time-limited impersonation tokens (optional)

3. **Deletion Safety**
   - Soft delete by default
   - Confirmation dialogs
   - Show retention period
   - Force delete requires additional confirmation

4. **Port Release**
   - Ensure ports are released on deletion
   - Handle edge cases where Docker cleanup fails

---

## Cron Job Setup

**Option 1: External Cron Service**
```bash
# Add to cron.daily or external service
curl -X POST https://wakelai.com/api/admin/cron/auto-delete \
  -H "Authorization: Bearer ADMIN_CRON_SECRET"
```

**Option 2: Node-Cron (if running continuously)**
```typescript
import cron from 'node-cron';

// Run daily at 2 AM
cron.schedule('0 2 * * *', autoDeleteExpiredInstances);
```

---

## Environment Variables

```env
# Add to .env
ADMIN_EMAILS=admin@example.com,ops@example.com
ADMIN_CRON_SECRET=your-secret-key
AUTO_DELETE_ENABLED=true
DEFAULT_RETENTION_DAYS=7
```

---

## Testing Checklist

- [ ] Admin can view all instances
- [ ] Admin can stop instances
- [ ] Admin can soft delete instances
- [ ] Admin can restore deleted instances
- [ ] Admin can force delete instances
- [ ] Admin can login as any user
- [ ] Admin can change retention period
- [ ] Auto-deletion cron works correctly
- [ ] Ports are properly released
- [ ] nginx configs are removed
- [ ] Docker containers are removed
- [ ] Non-admin users cannot access admin functions
- [ ] Impersonation is logged

---

## Migration Plan

### Step 1: Backup
```bash
pg_dump -U wakelai -h localhost -p 55433 wakelai > backup.sql
```

### Step 2: Schema Update
```bash
npx prisma migrate dev --name add-admin-instance-management
```

### Step 3: Seed Admin Settings
```typescript
// Run once to create admin settings for existing users
await prisma.adminSettings.createMany({
  data: [
    { userId: 'admin-user-id', instanceRetentionDays: 7 }
  ],
  skipDuplicates: true
});
```

### Step 4: Update Environment
Add new env variables to `.env`

---

## Future Enhancements

1. **Bulk Actions** - Select multiple instances for operations
2. **Export Data** - Export instance list to CSV
3. **Activity Log** - View admin action history
4. **Instance Metrics** - CPU, memory usage per instance
5. **Cost Tracking** - Track resource usage costs
6. **Notification System** - Alert admins about issues