MySMSAPio/ADMIN_INTERFACE.md

Admin Interface Documentation

Overview

A web-based admin interface has been added to MySMSAPio for managing API keys and monitoring SMS logs through a user-friendly dashboard.

Features

1. Dashboard

• Real-time statistics overview
  • Total and online gateways
  • Active API keys count
  • Messages sent/received today
  • Failed messages tracking
• Recent messages display
• Gateway status overview

2. API Keys Management

• List API Keys: View all API keys with their status, permissions, and usage
• Create API Keys: Generate new API keys with customizable permissions
  • Send SMS permission
  • Receive SMS permission
  • Manage Gateways permission
  • Optional expiration date
• Revoke API Keys: Deactivate API keys when no longer needed
• View Details: See API key prefix, last used date, and creation date

3. SMS Logs Monitoring

• View All Messages: Paginated list of all SMS messages (50 per page)
• Advanced Filtering:
  • Direction (Inbound/Outbound)
  • Status (Pending/Queued/Sent/Delivered/Failed)
  • Phone number search
  • Gateway filter
  • Date range (Start/End date)
• Message Details: View message ID, content, timestamps, retry count, and error messages
• Real-time Updates: See the latest message activity

4. Gateways Management

• List Gateways: View all registered gateway devices
• Gateway Details:
  • Connection status (Online/Offline)
  • Message statistics (today and total)
  • Last heartbeat timestamp
  • Device metadata
• Activate/Deactivate: Toggle gateway active status
• Recent Messages: View messages processed by each gateway

Access

Default Login Credentials

After running bin/rails db:seed, you can access the admin interface with:

• URL: http://localhost:3000/admin/login
• Email: admin@example.com
• Password: password123

⚠️ IMPORTANT: Change the default password immediately in production!

Creating Additional Admin Users

# In Rails console (bin/rails console)
Admin.create!(
  email: "your-email@example.com",
  password: "your-secure-password",
  name: "Your Name"
)

Routes

All admin routes are namespaced under /admin:

• GET /admin/login - Login page
• POST /admin/login - Login action
• DELETE /admin/logout - Logout action
• GET /admin/dashboard - Dashboard home
• GET /admin/api_keys - List API keys
• GET /admin/api_keys/new - Create new API key
• POST /admin/api_keys - Save new API key
• DELETE /admin/api_keys/:id - Revoke API key
• POST /admin/api_keys/:id/toggle - Toggle API key active status
• GET /admin/logs - View SMS logs with filtering
• GET /admin/gateways - List all gateways
• GET /admin/gateways/:id - View gateway details
• POST /admin/gateways/:id/toggle - Toggle gateway active status

Technical Details

Authentication

• Uses Rails' has_secure_password with bcrypt for secure password hashing
• Session-based authentication
• Password must be at least 8 characters
• Email validation with format checking

Authorization

• All admin controllers inherit from Admin::BaseController
• require_admin before_action ensures user is logged in
• Redirects to login page if not authenticated

Models

• Admin (app/models/admin.rb): Admin user accounts
  • Fields: email, password_digest, name, last_login_at
  • Validations: email uniqueness and format, password minimum length
  • Methods: update_last_login! for tracking login activity

Controllers

• Admin::SessionsController: Handles login/logout
• Admin::DashboardController: Dashboard with statistics
• Admin::ApiKeysController: API key CRUD operations
• Admin::LogsController: SMS message logs with filtering
• Admin::GatewaysController: Gateway management

Views

• Custom admin layout with built-in CSS (no external dependencies)
• Responsive design with clean, modern UI
• Turbo-powered for fast navigation
• Integrated flash messages for user feedback

Styling

• Custom CSS included in admin layout
• No external CSS frameworks required
• Clean, modern design with:
  • Card-based layouts
  • Color-coded badges for status indicators
  • Responsive grid system
  • Form styling with validation states
  • Alert notifications

Pagination

• Uses Pagy gem for efficient pagination
• Configured in Admin::BaseController with include Pagy::Backend
• Frontend helpers in ApplicationHelper with include Pagy::Frontend
• 50 items per page for logs

Security Best Practices

1. Change Default Password: Immediately change admin@example.com password in production
2. Use Strong Passwords: Enforce minimum 8 characters (configured in model)
3. HTTPS Only: Always use HTTPS in production
4. Session Security: Configure secure session cookies in production
5. Rate Limiting: Consider adding rate limiting to login endpoint
6. Regular Audits: Monitor admin access through last_login_at field

Database Schema

Admins Table

create_table "admins" do |t|
  t.string :email, null: false
  t.string :password_digest, null: false
  t.string :name, null: false
  t.datetime :last_login_at
  t.timestamps

  t.index :email, unique: true
end

Customization

Adding New Admin Features

1. Create controller in app/controllers/admin/
2. Inherit from Admin::BaseController
3. Add routes in config/routes.rb under namespace :admin
4. Create views in app/views/admin/

Styling Customization

• Edit inline styles in app/views/layouts/admin.html.erb
• Modify CSS variables for colors, spacing, fonts
• Add custom JavaScript if needed

Adding Permissions

• Extend Admin model with role/permission system
• Add authorization checks in controllers
• Update views to show/hide features based on permissions

Troubleshooting

"Please log in to continue" message

• Session may have expired
• Navigate to /admin/login to log in again

API key not showing after creation

• API keys are only shown once for security
• If lost, revoke and create a new one

Pagination not working

• Ensure Pagy gem is installed: bundle exec gem list pagy
• Check that Pagy::Backend is included in Admin::BaseController
• Verify Pagy::Frontend is in ApplicationHelper

Filters not applying

• Check that form is submitting with GET method
• Verify filter parameters are being passed in URL
• Check apply_filters method in Admin::LogsController

Development

Running Tests

bin/rails test

Checking Routes

bin/rails routes | grep admin

Console Access

bin/rails console

# Check admin users
Admin.all

# Create new admin
Admin.create!(email: "test@example.com", password: "password", name: "Test")

Future Enhancements

Potential features to add:

• Role-based permissions (Admin, Viewer, Operator)
• Activity logs (audit trail)
• Two-factor authentication (2FA)
• Email notifications for critical events
• Export functionality (CSV, JSON)
• Advanced analytics and charts
• Webhook management interface
• OTP code management
• Bulk operations for messages
• API usage analytics per key

---

Tailwind CSS Theme

The admin interface has been completely redesigned with Tailwind CSS v4 for a modern, professional appearance.

Design Features

Color Scheme

• Primary: Blue (#3b82f6 - blue-600)
• Success: Green (#10b981 - green-500)
• Warning: Yellow (#f59e0b - yellow-500)
• Danger: Red (#ef4444 - red-500)
• Neutral: Gray scale for text and backgrounds

Components

Sidebar Navigation:

• Dark gradient background (gray-900 to gray-800)
• Fixed 288px width (w-72)
• Active state highlighting
• User profile section at bottom
• Smooth transitions on hover

Cards:

• Rounded corners (rounded-xl)
• Subtle shadows (ring-1 ring-gray-900/5)
• White background
• Proper spacing and padding

Stats Cards:

• Colored icon backgrounds
• Large numbers for metrics
• Secondary information in smaller text
• Animated pulse indicators for online status

Tables:

• Alternating row backgrounds on hover
• Sticky headers
• Responsive overflow scrolling
• Color-coded status badges

Badges:

• Rounded-full design
• Color-coded by status
• Ring borders for depth
• Icons integrated

Forms:

• Rounded inputs (rounded-lg)
• Icon prefixes for visual clarity
• Focus states with blue ring
• Proper validation styling
• Checkbox descriptions

Buttons:

• Primary: Blue gradient with hover effect
• Secondary: Gray with hover effect
• Danger: Red for destructive actions
• Success: Green for positive actions
• All include smooth transitions

Typography

• Headlines: Bold, large sizes (text-3xl)
• Body: Gray-900 for primary text, gray-600 for secondary
• Font weights: Semibold for emphasis, medium for labels
• Proper line heights and spacing

Icons

• Font Awesome 6.4.0 icons throughout
• Contextual icon usage
• Consistent sizing
• Proper spacing with text

Responsive Design

• Mobile-first approach
• Grid layouts that adapt (1/2/3/4 columns)
• Overflow scrolling on mobile
• Touch-friendly tap targets

Animations

• Pulse animation for online indicators
• Smooth transitions (duration-200)
• Hover state changes
• Loading states

Development

Build Tailwind CSS:

bin/rails tailwindcss:build

Watch for changes (development):

bin/rails tailwindcss:watch

Using foreman (recommended for development):

bin/dev

This automatically runs both Rails server and Tailwind watcher.

Customization

Custom Colors

Edit app/assets/tailwind/application.css:

@theme {
  --color-primary-500: #your-color;
  --color-primary-600: #your-darker-color;
}

Extending Tailwind

The project uses Tailwind CSS v4 with the new @import "tailwindcss" syntax. Custom utilities can be added directly to the CSS file.

Custom Scrollbar

Custom scrollbar styling is included for webkit browsers with gray colors matching the theme.

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• CSS Grid and Flexbox required
• Custom scrollbar styles for webkit browsers
• Responsive design works on all screen sizes

Performance

• Tailwind CSS is compiled and cached
• Production builds are automatically optimized
• Uses Rails asset pipeline for caching
• Minimal JavaScript (only for interactive features like copy-to-clipboard)

Accessibility

• Semantic HTML elements
• Proper ARIA labels
• Keyboard navigation support
• Focus states visible
• Color contrast meets WCAG guidelines
• Screen reader friendly