MySMSAPio/ADMIN_QUICKSTART.md

Admin Interface - Quick Start Guide

Getting Started

1. Start the Development Server

# 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

bin/rails test

Code Quality

bin/rubocop
bin/brakeman

Database Management

# Reset and seed
bin/rails db:reset

# Just seed
bin/rails db:seed

Building Tailwind CSS

# 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! 🎉