# Admin Interface - Quick Start Guide

## Getting Started

### 1. Start the Development Server

```bash
# Option 1: Run server with Tailwind watch (recommended)
bin/dev

# Option 2: Run server only
bin/rails server
```

### 2. Access the Admin Interface

Open your browser and navigate to:
```
http://localhost:3000/admin/login
```

### 3. Login with Default Credentials

```
Email: admin@example.com
Password: password123
```

⚠️ **Important**: Change this password immediately in production!

## Interface Overview

### Dashboard (/)
- **Real-time Statistics**: View gateway counts, API keys, and message metrics
- **Recent Messages**: Monitor the latest 10 SMS messages
- **Gateway Status**: Check active gateways and their heartbeat status

### API Keys (/admin/api_keys)
- **List Keys**: View all API keys with status and permissions
- **Create New**: Generate API keys with custom permissions (Send SMS, Receive SMS, Manage Gateways)
- **Revoke Keys**: Deactivate keys that are no longer needed
- **One-time Display**: API keys are shown only once after creation for security

### SMS Logs (/admin/logs)
- **View All Messages**: Paginated list (50 per page) of all SMS traffic
- **Advanced Filters**:
  - Direction (Inbound/Outbound)
  - Status (Pending/Sent/Delivered/Failed)
  - Phone number search
  - Gateway selection
  - Date range
- **Error Details**: Click on failed messages to view error information

### Gateways (/admin/gateways)
- **List Devices**: View all registered gateway devices
- **Device Details**: Click on gateway name for detailed stats
- **Toggle Status**: Activate or deactivate gateways
- **Monitor Health**: Check connection status, heartbeat, and message counts

## Key Features

### Status Indicators
- 🟢 **Green Pulse**: Gateway is online and active
- 🔴 **Red Dot**: Gateway is offline
- 🟡 **Yellow**: Pending or warning status
- 🔵 **Blue**: Information or in-progress status

### Color-Coded Badges
- **Green**: Success, Active, Delivered, Online
- **Blue**: Information, Sent, Outbound
- **Red**: Error, Failed, Revoked, Offline
- **Yellow**: Warning, Pending
- **Purple**: Queued, Priority
- **Gray**: Inactive, Neutral

### Quick Actions
- **Copy API Key**: One-click copy to clipboard
- **Filter & Search**: Quick filtering on all list views
- **Toggle States**: One-click activate/deactivate
- **View Details**: Click on links for detailed information

## Common Tasks

### Creating an API Key
1. Navigate to **API Keys** → **Create New API Key**
2. Enter a descriptive name
3. Select permissions (checkboxes)
4. Optionally set an expiration date
5. Click **Create API Key**
6. **Copy the key immediately** (shown only once!)
7. Store securely

### Monitoring Messages
1. Navigate to **SMS Logs**
2. Use filters to narrow down results:
   - Select direction and status
   - Enter phone number to search
   - Choose specific gateway
   - Set date range
3. Click **Apply Filters**
4. Click on any row with errors to view details

### Managing Gateways
1. Navigate to **Gateways**
2. View online/offline status
3. Click gateway name for detailed stats
4. Use **Activate/Deactivate** buttons to control gateway

### Checking Statistics
1. Dashboard shows current metrics:
   - Total vs. online gateways
   - Active API keys
   - Messages today (sent/received)
   - Failed messages count
2. All stats update on page refresh

## Navigation

### Sidebar Menu
- **Dashboard**: Home page with overview
- **API Keys**: Manage client API keys
- **SMS Logs**: View and filter messages
- **Gateways**: Manage gateway devices

### User Menu (Bottom of Sidebar)
- Shows your name and email
- **Logout** button

## Tips & Tricks

### Keyboard Navigation
- All interactive elements are keyboard accessible
- Use Tab to navigate between fields
- Enter to submit forms

### Search & Filter
- Phone number search accepts partial numbers
- Date filters are inclusive (includes start and end dates)
- Clear filters to reset to default view

### Visual Cues
- Hover over rows to highlight
- Online gateways show animated pulse
- Active states have distinct colors
- Error messages expand on click

### Mobile Support
- Sidebar collapses on mobile
- Tables scroll horizontally
- Touch-friendly button sizes
- Responsive grid layouts

## Development

### Running Tests
```bash
bin/rails test
```

### Code Quality
```bash
bin/rubocop
bin/brakeman
```

### Database Management
```bash
# Reset and seed
bin/rails db:reset

# Just seed
bin/rails db:seed
```

### Building Tailwind CSS
```bash
# One-time build
bin/rails tailwindcss:build

# Watch mode (auto-rebuild)
bin/rails tailwindcss:watch

# Or use foreman to run both
bin/dev
```

## Troubleshooting

### Can't Login
- Verify you ran `bin/rails db:seed`
- Check that Admin user exists: `bin/rails console` → `Admin.count`
- Verify email/password are correct

### Styling Looks Broken
- Run `bin/rails tailwindcss:build`
- Clear browser cache
- Check `app/assets/builds/tailwind.css` exists

### API Key Not Working
- Verify key is active (not revoked)
- Check key hasn't expired
- Ensure permissions are set correctly

### No Data Showing
- Run `bin/rails db:seed` to create sample data
- Check that gateway devices are registered
- Verify messages exist in database

## Security Checklist

- [ ] Change default admin password
- [ ] Use HTTPS in production
- [ ] Set secure session cookies
- [ ] Enable rate limiting
- [ ] Monitor admin access logs
- [ ] Regularly audit API keys
- [ ] Revoke unused API keys
- [ ] Set expiration dates on keys

## Getting Help

- Read full documentation: `ADMIN_INTERFACE.md`
- Check project docs: `CLAUDE.md`
- View Rails logs: `log/development.log`
- Rails console: `bin/rails console`

---

**Happy administering! 🎉**