# GPT Agent — Admin Panel Product & Engineering Plan

## 1. Purpose

Build a production-grade Admin Panel for GPT Agent.

GPT Agent is a self-hosted SaaS platform that lets businesses create AI sales agents and embed them into any website.

The Admin Panel is the platform operator's command center.

It must allow platform administrators to manage:
- Users
- Workspaces
- Agents
- Conversations
- Leads
- Knowledge
- AI usage
- API usage
- System health
- Queue jobs
- Logs
- Audit logs
- Plans
- Subscriptions
- Transactions
- Platform settings

This is NOT a demo admin dashboard. It must feel like a real commercial SaaS administration system built by an experienced product and engineering team.

---

# 2. Critical Visual Requirement

## KEEP THE CURRENT LIGHT THEME

The current application theme is LIGHT.

Do NOT redesign the Admin Panel as a dark dashboard.
Do NOT switch the global theme to dark.
Do NOT introduce a separate dark visual language for the Admin Panel.

The Admin Panel must use the same existing light theme and visual design system already present in the application.

Preserve:
- Existing background
- Existing typography
- Existing spacing system
- Existing border style
- Existing button style
- Existing input style
- Existing table style
- Existing sidebar style
- Existing navigation style
- Existing brand colors
- Existing component language

The Admin Panel should feel like it belongs to the same product.

It should be more operational and information-dense than the user panel, but NOT visually unrelated to it.

If the existing repository already contains a design system, reuse it instead of creating another one.

---

# 3. Design Philosophy

The Admin Panel should communicate:

"Platform Control Center"

Not:

"Generic Admin Template"

The UI should be:
- Light
- Clean
- Premium
- Professional
- Information-dense
- Calm
- Structured
- Fast
- Consistent
- Responsive

Avoid:
- Dark theme
- Neon effects
- Excessive gradients
- Giant AI graphics
- Robot illustrations
- Glassmorphism everywhere
- Excessive rounded cards
- Excessive shadows
- Fake charts
- Fake metrics
- Generic Bootstrap-style admin screens
- Unnecessary animations
- Huge empty areas
- Every element inside a card

Use whitespace intentionally.

---

# 4. Repository Inspection First

Before implementing anything:
1. Inspect the entire existing repository.
2. Identify the current Laravel version.
3. Inspect authentication.
4. Inspect existing user/workspace models.
5. Inspect migrations.
6. Inspect existing frontend architecture.
7. Inspect the existing light theme.
8. Inspect reusable components.
9. Inspect existing routes and middleware.
10. Inspect existing API structure.
11. Inspect existing policies and authorization.
12. Inspect existing analytics/data models.
13. Identify what Admin functionality already exists.

Do not overwrite working code.
Do not create duplicate components.
Do not introduce a new UI framework if the project already has a suitable frontend system.

---

# 5. Admin Architecture

Use a dedicated protected admin area.

```text
Admin
│
├── Overview
│
├── Customers
│   ├── Users
│   ├── Workspaces
│   └── Agents
│
├── Operations
│   ├── Conversations
│   ├── Leads
│   ├── Knowledge
│   ├── AI Usage
│   └── API Usage
│
├── System
│   ├── System Health
│   ├── Jobs
│   ├── Logs
│   └── Audit Logs
│
├── Business
│   ├── Plans
│   ├── Subscriptions
│   └── Transactions
│
└── Configuration
    ├── AI Providers
    ├── Integrations
    ├── Email
    ├── Storage
    ├── Security
    └── Platform Settings
```

Use clear navigation groups. Do not overload the sidebar.

---

# 6. Admin Authentication & Authorization

Admin access must be separate from normal customer authorization.

Requirements:
- Admin authentication
- Admin authorization middleware/policy
- Role-based permissions
- Secure session handling
- Password change
- Optional 2FA architecture
- Session management
- Audit logging for sensitive admin actions

Never secure Admin routes only by hiding frontend links.

Every admin operation must be authorized server-side.

---

# 7. Admin Roles

Minimum roles:

## Super Admin
Full platform control.

## Admin
Operational management.

## Support
Customer support access with restricted sensitive operations.

## Analyst
Read-only access to analytics and reporting.

Do not create unnecessary roles unless the product requires them.

Permissions should be explicit.

---

# 8. Admin Sidebar

Use the existing LIGHT sidebar design.

Suggested structure:

```text
GPT Agent

Overview

CUSTOMERS
Users
Workspaces
Agents

OPERATIONS
Conversations
Leads
Knowledge
AI Usage
API Usage

SYSTEM
System Health
Jobs
Logs
Audit Logs

BUSINESS
Plans
Subscriptions
Transactions

CONFIGURATION
AI Providers
Integrations
Settings
```

At the bottom:

```text
Admin Profile
Support
Logout
```

Keep the sidebar compact and professional.

---

# 9. Global Admin Header

Top bar:

Left:
```text
Page Title
Breadcrumb
```

Right:
```text
Global Search
Notifications
Admin Profile
```

Global search should eventually search:
- Users
- Workspaces
- Agents
- Conversations
- Leads
- API keys

Do not build a fake search box. If global search is implemented, it must return real records.

---

# 10. Admin Dashboard / Overview

The Overview page is the main platform monitoring screen.

Header:
```text
Overview

Platform performance and activity
```

Date selector:
```text
7D
30D
90D
1Y
Custom
```

---

# 11. Overview KPI Section

Use real database values.

Suggested KPIs:
```text
Users
Workspaces
Active Agents
Conversations
Leads
AI Requests
```

Each KPI can show:
```text
12,482
Users

+12.4%
vs previous period
```

Do not hard-code numbers.

If data is unavailable, show "No data" or an appropriate empty state.

Never show fake production metrics.

---

# 12. Platform Growth Chart

Create a real chart based on database events.

Possible series:
- Users
- Workspaces
- Conversations
- Leads

Allow time-range filtering.

The chart must be readable and restrained.

Do not create decorative charts that have no operational value.

---

# 13. Revenue Section

Only display revenue if billing/transaction data actually exists.

Metrics:
- MRR
- ARR
- New subscriptions
- Churn
- Revenue trend

If billing is not implemented:
Do NOT show fake revenue.

Either hide the section or show a proper "Billing not configured" state.

---

# 14. Live Activity

Create a real activity stream.

Example:
```text
12:42
New workspace created

12:41
Agent published

12:40
New lead captured

12:39
Knowledge source indexed

12:38
New user registered
```

Use real events. Provide timestamps. Keep the list compact.

---

# 15. System Status Summary

Overview should include a concise operational status area.

Example:
```text
Application     Operational
Database        Operational
Queue           Operational
Cache           Operational
Storage         Operational
AI Provider     Operational
Widget API      Operational
```

Use meaningful status states:
- Operational
- Degraded
- Down
- Unknown

Do not claim a service is healthy unless it is actually checked.

---

# 16. Users Management

Create a production-grade Users page.

Table:
```text
User
Email
Workspace
Plan
Agents
Status
Joined
Actions
```

Features:
- Search
- Status filter
- Plan filter
- Date filter
- Sort
- Pagination

Actions:
- View
- Suspend
- Restore
- Impersonate if explicitly implemented
- Delete where permitted

Do not expose destructive actions without confirmation.

---

# 17. User Detail

User detail page:
```text
User Profile

Name
Email
Status
Joined
Last Active
```

Sections:
```text
Workspaces
Agents
Conversations
Leads
Usage
Subscription
Activity
Security
```

Use real relationships.

---

# 18. Workspace Management

Workspaces are the primary tenant boundary.

Table:
```text
Workspace
Owner
Members
Agents
Conversations
Plan
Usage
Status
Created
```

Actions:
- View
- Suspend
- Restore
- Manage
- Delete where permitted

Workspace detail:
```text
Overview
Members
Agents
Knowledge
Conversations
Leads
Usage
Billing
Activity
```

Never allow admins to accidentally break tenant isolation.

---

# 19. Agent Management

Platform-wide Agent management.

Table:
```text
Agent
Workspace
Model
Status
Conversations
Leads
Created
```

Statuses:
- Draft
- Active
- Paused
- Archived

Agent detail:
```text
Overview
Configuration
Knowledge
Conversations
Usage
Errors
Widget
Activity
```

Admin should be able to inspect the agent.

Modification capabilities should depend on admin permission.

---

# 20. Conversations Management

Platform-wide conversation monitoring.

Filters:
- Workspace
- Agent
- Status
- Date
- Lead
- Search

Statuses:
- Open
- Pending
- Resolved
- Archived

Conversation detail should show:
- Visitor
- Agent
- Workspace
- Messages
- Source URL
- Lead data
- Created time
- Last activity
- Metadata

Do not expose unnecessary private data.

Access must be auditable.

---

# 21. Leads Management

Platform-wide lead management.

Metrics:
- Total leads
- New
- Qualified
- Contacted
- Won
- Lost

Table:
```text
Lead
Workspace
Agent
Source
Status
Score
Created
```

Filters:
- Workspace
- Agent
- Status
- Date

Lead detail:
- Contact information
- Conversation
- Notes
- Status history
- Source
- Metadata

---

# 22. Knowledge Management

Show platform knowledge indexing status.

Metrics:
```text
Indexed
Processing
Failed
Disabled
```

Table:
```text
Source
Workspace
Agent
Type
Status
Size
Created
```

Source types:
- Website
- Sitemap
- PDF
- Text
- Other supported document

Show processing failures with useful error information.

---

# 23. AI Usage

This should be a major Admin feature.

Top metrics:
```text
AI Requests
Tokens Used
Estimated Cost
Average Response Time
Error Rate
```

Breakdowns:
- Provider
- Model
- Workspace
- Agent
- Date

Example:
```text
Provider      Requests      Tokens      Cost

Provider A    5.2M         182M        $812
Provider B    2.2M         102M        $472
```

All values must come from real usage records.

Do not display estimated cost unless the estimation methodology is defined.

---

# 24. AI Provider Management

Admin should be able to configure supported AI providers.

Possible settings:
- Provider
- Model
- API configuration
- Default provider
- Fallback provider
- Availability
- Usage limits

Secrets must never be shown in plain text after saving.

Never expose provider API keys to frontend code.

Keep provider-specific implementation behind a service abstraction.

---

# 25. API Usage

Track platform API activity.

Metrics:
- Requests
- Successful requests
- 4xx
- 5xx
- Average latency
- Rate-limit events

Break down by:
- Endpoint
- Workspace
- API key
- Date

Do not log sensitive payloads unnecessarily.

---

# 26. System Health

Create a dedicated operational dashboard.

Services:
```text
Application
Database
Cache
Queue
Storage
AI Provider
Widget API
Mail
```

For each service:
- Status
- Last checked
- Response time where meaningful
- Error state

Do not use fake green indicators.

Health checks must actually test the service.

---

# 27. Queue / Jobs

Laravel queue monitoring.

Sections:
```text
Pending
Processing
Failed
Completed
```

Failed job table:
```text
Job
Queue
Attempts
Failed At
Error
Actions
```

Actions:
- Retry
- Delete where safe
- Inspect

Jobs should not expose secrets.

---

# 28. Logs

Create an application log viewer suitable for administrators.

Filters:
- Level
- Service
- Date
- Search

Levels:
- Debug
- Info
- Warning
- Error
- Critical

Sensitive information must be redacted.

Do not expose:
- Passwords
- API keys
- Tokens
- Secrets
- Full sensitive personal data

---

# 29. Audit Logs

Audit logs are mandatory.

Record:
- Admin login
- Admin logout where useful
- User suspension
- Workspace suspension
- Agent changes
- API key actions
- Provider configuration changes
- Billing changes
- Permission changes
- Destructive actions
- Security-sensitive operations

Fields:
```text
Actor
Action
Resource
Resource ID
IP
User Agent
Timestamp
Metadata
```

Never store secrets inside audit metadata.

---

# 30. Plans

Create a plan management system.

Example plans:
```text
Free
Starter
Growth
Pro
Enterprise
```

Each plan may define:
- Price
- Agents
- Conversations
- Knowledge sources
- Members
- AI usage
- Features

Plan limits must be enforced through backend entitlement logic.

Do not only display limits in the UI.

---

# 31. Subscriptions

Admin subscription view:

```text
Customer
Workspace
Plan
Status
Started
Renewal
MRR
```

Statuses:
- Trialing
- Active
- Past Due
- Cancelled
- Expired

Only show billing fields that are backed by real billing data.

---

# 32. Transactions

Transaction table:
```text
Transaction
Workspace
Customer
Amount
Currency
Status
Provider
Created
```

Statuses:
- Pending
- Paid
- Failed
- Refunded

Do not expose payment secrets.

---

# 33. Platform Settings

Settings should be organized, not one giant form.

## General
- Application name
- Application URL
- Default timezone
- Default locale

## AI
- Providers
- Models
- Defaults
- Limits

## Email
- SMTP
- Mail settings

## Storage
- Local
- S3-compatible storage where supported

## Queue
- Queue configuration

## Security
- Session settings
- Rate limits
- Authentication settings

## Widget
- Widget URL
- Public configuration
- Allowed origins

## Billing
- Provider
- Currency
- Plans

---

# 34. Admin Notifications

Provide useful notifications for:
- Failed AI provider
- Failed knowledge indexing
- Queue failures
- Payment issues
- Security events
- System degradation

Do not generate notification noise.

---

# 35. Search

Implement global admin search only with real backend search.

Search across:
- Users
- Workspaces
- Agents
- Leads
- Conversations

Results should show:
```text
Type
Name
Workspace
Status
```

Use authorization rules even for search results.

Do not leak resources through search.

---

# 36. Admin Impersonation

If implemented, impersonation must be highly controlled.

Requirements:
- Explicit permission
- Confirmation
- Audit event
- Visible impersonation banner
- Easy return to admin session
- No password exposure
- No ability to silently hide the action

Do not implement impersonation unless it is genuinely useful.

---

# 37. Responsive Behavior

The Admin Panel must support:
- Desktop
- Laptop
- Tablet
- Mobile

Desktop should provide the full operational experience.

On mobile:
- Sidebar becomes a drawer
- Tables become responsive layouts
- Filters become usable controls
- Detail views remain readable
- Charts remain legible

Do not simply shrink desktop tables until they become unusable.

---

# 38. UI Component System

Reuse existing application components.

Required reusable components:
- Button
- Input
- Select
- Date picker
- Modal
- Dropdown
- Badge
- Alert
- Toast
- Table
- Pagination
- Tabs
- Stat
- Chart container
- Empty state
- Skeleton
- Status indicator
- Confirmation dialog

Do not create multiple versions of the same component.

---

# 39. Tables

All major management tables should support appropriate combinations of:
- Search
- Filter
- Sort
- Pagination
- Row actions

Do not add bulk actions everywhere.

Only implement bulk actions where they provide real operational value.

---

# 40. Empty States

Every admin page needs a deliberate empty state.

Example:
```text
No workspaces yet.

There are no workspaces matching your current filters.
```

If there are no records, do not fill the page with fake records.

---

# 41. Loading States

Use skeletons or appropriate loading indicators.

Avoid:
- blank screens
- frozen controls
- buttons that appear clickable during requests

Buttons should show processing state during mutations.

---

# 42. Error States

Admin errors should provide useful information without exposing secrets.

Example:
```text
Unable to load AI usage.

Please try again.
```

For operational errors:
```text
Service unavailable
Last successful check: ...
```

Do not display stack traces to normal admins.

---

# 43. Destructive Actions

Actions such as:
- Delete user
- Delete workspace
- Suspend workspace
- Revoke API key
- Cancel subscription

must require deliberate confirmation.

For high-risk operations, consider requiring the resource name to be typed.

---

# 44. Security

Admin Panel must address:
- Authentication
- Authorization
- CSRF
- XSS
- SQL injection
- Mass assignment
- Session security
- Rate limiting
- Tenant isolation
- Audit logging
- Secret protection
- Secure file access
- API security

Never trust browser-supplied:
- workspace ownership
- user ownership
- agent ownership
- role
- permission

---

# 45. Tenant Isolation

Admin functionality must not accidentally weaken normal tenant isolation.

Normal users must only access their own authorized workspaces.

Admins may have broader access based on role.

Every admin access to sensitive tenant data should be traceable where appropriate.

---

# 46. Performance

Admin pages may contain large datasets.

Use:
- Pagination
- Database indexes
- Eager loading
- Query optimization
- Aggregation queries
- Caching where appropriate
- Lazy loading for heavy detail sections

Avoid:
- Loading thousands of records into one page
- N+1 queries
- Repeated expensive aggregate queries
- Unnecessary API calls

---

# 47. Real-Time Features

Real-time updates can be used for:
- Live activity
- Queue status
- System health
- New leads

Only implement real-time infrastructure where it provides actual value.

Do not add WebSockets simply because it looks impressive.

---

# 48. API Design

Admin APIs should be separate from public widget APIs.

Example:
```text
/api/v1/admin/...
```

Use:
- Form Requests
- API Resources
- Policies
- Rate limiting
- Consistent response structures

Do not expose raw database records.

---

# 49. Testing

Critical Admin tests:

## Authentication
- unauthorized users cannot access admin
- authorized admin can access admin

## Authorization
- role permissions work
- restricted actions are blocked

## Users
- listing
- filtering
- suspension
- restoration

## Workspaces
- access
- suspension
- tenant boundaries

## Agents
- listing
- inspection
- status changes

## Conversations
- listing
- filtering
- access control

## AI Usage
- correct aggregation
- date filtering

## Jobs
- failed job visibility
- retry authorization

## Audit Logs
- sensitive actions create logs

## Settings
- authorized changes only

---

# 50. Production Data Rule

The Admin Panel must never rely on fake production data.

Remove:
- hard-coded users
- fake workspace counts
- fake revenue
- fake AI usage
- fake conversations
- fake leads
- fake system health

Seeders are acceptable only for clearly isolated development/demo data.

---

# 51. Code Quality

Build like a senior engineering team will review the repository.

Use:
- Small controllers
- Focused services/actions
- Policies
- Form Requests
- Proper model relationships
- Reusable UI components
- Clear route naming
- Meaningful variable names
- Config-driven behavior

Avoid:
- Giant controllers
- Giant components
- Duplicate logic
- Inline business logic everywhere
- Magic numbers
- Hard-coded secrets
- Temporary hacks
- TODO comments replacing implementation

---

# 52. Implementation Order

## Phase 0 — Audit
Inspect the existing repository and current UI.

Do not change the theme.

## Phase 1 — Admin Foundation
Implement:
- Admin authentication
- Admin middleware
- Roles
- Permissions
- Admin layout
- Sidebar
- Header
- Design-system reuse

## Phase 2 — Overview
Implement:
- KPIs
- Growth analytics
- Live activity
- System status

## Phase 3 — Customers
Implement:
- Users
- Workspaces
- Agents
- Detail views

## Phase 4 — Operations
Implement:
- Conversations
- Leads
- Knowledge
- AI usage
- API usage

## Phase 5 — System
Implement:
- System health
- Queue/jobs
- Logs
- Audit logs

## Phase 6 — Business
Implement:
- Plans
- Subscriptions
- Transactions

## Phase 7 — Configuration
Implement:
- AI providers
- Integrations
- Email
- Storage
- Security
- Widget
- Platform settings

## Phase 8 — Security & Performance
Review:
- Authorization
- Tenant isolation
- Rate limiting
- Query performance
- Indexes
- Secret exposure
- Logging

## Phase 9 — QA
Test the complete Admin workflow.

---

# 53. Admin Definition of Done

Admin Panel is complete only when:

- [ ] Admin authentication works
- [ ] Admin authorization works
- [ ] Roles work
- [ ] Permissions work
- [ ] Light theme is preserved
- [ ] Existing design system is reused
- [ ] Overview uses real data
- [ ] Users management works
- [ ] Workspaces management works
- [ ] Agents management works
- [ ] Conversations management works
- [ ] Leads management works
- [ ] Knowledge monitoring works
- [ ] AI usage works
- [ ] API usage works
- [ ] System health uses real checks
- [ ] Queue monitoring works
- [ ] Logs are protected
- [ ] Audit logs work
- [ ] Plans work if billing exists
- [ ] Subscriptions work if billing exists
- [ ] Transactions work if billing exists
- [ ] Settings work
- [ ] Responsive layout works
- [ ] Loading states exist
- [ ] Empty states exist
- [ ] Error states exist
- [ ] Destructive actions are protected
- [ ] No fake production data exists
- [ ] No sensitive secrets are exposed
- [ ] No obvious console errors remain
- [ ] No obvious server errors remain

---

# 54. Final Antigravity Instruction

Treat this file as the Admin Panel master specification.

Before coding:
1. Read this entire file.
2. Inspect the existing project.
3. Inspect the CURRENT LIGHT THEME.
4. Reuse the existing visual language.
5. Identify existing components.
6. Identify existing models and APIs.
7. Identify missing Admin functionality.
8. Implement in phases.
9. Test every phase.
10. Fix issues before continuing.

MOST IMPORTANT:

The Admin Panel must remain LIGHT because that is the approved product theme.

Do not convert it to dark mode.
Do not create a new unrelated visual identity.

The final result should feel like a natural, professionally engineered extension of the existing GPT Agent product.

The target is:

**Real SaaS Admin Panel**
+
**Real Data**
+
**Real Authorization**
+
**Real Operations**
+
**Real Production Engineering**

It must not look or behave like an AI-generated prototype.
