MySMSAPio/STARTUP_GUIDE.md

# MySMSAPio - Startup Guide

## ⚠️ Important: Configuration Changes Made

The application configuration has been updated to support both API endpoints and the admin web interface. **You MUST restart your Rails server** for these changes to take effect.

## Quick Start

### 1. Stop Any Running Servers
If you have a Rails server running, stop it first (Ctrl+C).

### 2. Start the Server

**Option A: With Tailwind CSS watch (Recommended)**
```bash
bin/dev
```
This starts both Rails server and Tailwind CSS watcher.

**Option B: Rails server only**
```bash
bin/rails server
```

### 3. Access the Admin Interface

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

### 4. Login

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

⚠️ **Remember to change this password in production!**

## What Changed

### Configuration Updates

1. **Disabled API-Only Mode**
   - File: `config/application.rb`
   - Changed: Commented out `config.api_only = true`
   - Reason: Allows admin interface to use sessions and flash messages

2. **Added Session Store**
   - File: `config/initializers/session_store.rb`
   - Added: Cookie-based session configuration
   - Reason: Required for admin authentication

3. **CSRF Protection**
   - All admin controllers have CSRF protection enabled
   - Forms automatically include CSRF tokens
   - API endpoints (ActionController::API) are unaffected

### Why These Changes Were Needed

**The Problem:**
- The app was configured as `api_only = true`
- This disables sessions, flash messages, and cookies
- Admin interface needs these features for authentication

**The Solution:**
- Keep API controllers using `ActionController::API` (fast, stateless)
- Admin controllers use `ActionController::Base` (full Rails features)
- Both work together in the same app

## Architecture

```
MySMSAPio Application
│
├── API Endpoints (Fast & Stateless)
│   ├── /api/v1/sms/*
│   ├── /api/v1/otp/*
│   └── /api/v1/gateway/*
│   └── Controllers inherit from ActionController::API
│   └── Use: Token authentication, no sessions
│
└── Admin Interface (Full Rails Features)
    ├── /admin/login
    ├── /admin/dashboard
    ├── /admin/api_keys
    ├── /admin/logs
    └── /admin/gateways
    └── Controllers inherit from ActionController::Base
    └── Use: Session authentication, flash messages, cookies
```

## Troubleshooting

### Error: "undefined method 'flash'"
**Solution:** Restart the Rails server. Configuration changes require a server restart.

```bash
# Stop the server (Ctrl+C), then:
bin/dev
# or
bin/rails server
```

### Error: "Admin is not a module"
**Solution:** This was already fixed by renaming the model to `AdminUser`. If you see this:
```bash
bin/rails db:migrate
bin/rails db:seed
```

### Login Page Shows 404
**Check routes:**
```bash
bin/rails routes | grep admin
```

Should show routes like `/admin/login`, `/admin/dashboard`, etc.

### Session Not Persisting
**Check middleware:**
```bash
bin/rails middleware | grep Session
```

Should show: `use ActionDispatch::Session::CookieStore`

### API Endpoints Not Working
The API endpoints should work exactly as before. Test with:
```bash
curl -H "Authorization: Bearer your_api_key" \
  http://localhost:3000/api/v1/sms/received
```

## Development Workflow

### Daily Development
```bash
# Start everything
bin/dev

# This runs:
# - Rails server (port 3000)
# - Tailwind CSS watcher (auto-rebuild on changes)
```

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

### Database Operations
```bash
# Reset database
bin/rails db:reset

# Run migrations
bin/rails db:migrate

# Seed data
bin/rails db:seed
```

### Code Quality
```bash
# Run RuboCop
bin/rubocop

# Run Brakeman security scanner
bin/brakeman
```

## Production Deployment

### Environment Variables
Make sure these are set:
```bash
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
SECRET_KEY_BASE=your_secret_key
RAILS_ENV=production
```

### Precompile Assets
```bash
bin/rails assets:precompile
bin/rails tailwindcss:build
```

### Change Default Password
```bash
bin/rails console

# In console:
admin = AdminUser.find_by(email: 'admin@example.com')
admin.update!(password: 'your_secure_password')
```

### Enable HTTPS
Update `config/environments/production.rb`:
```ruby
config.force_ssl = true
```

## Features Working

✅ **Admin Dashboard**
- Real-time statistics
- Recent messages
- Gateway status

✅ **API Keys Management**
- Create with permissions
- View all keys
- Revoke keys

✅ **SMS Logs**
- Filter by direction, status, date
- View error messages
- Pagination

✅ **Gateway Management**
- View all gateways
- Activate/deactivate
- Monitor health

✅ **Authentication**
- Session-based login
- Flash messages
- CSRF protection

✅ **Professional UI**
- Tailwind CSS theme
- Responsive design
- Animated indicators

## Need Help?

### Documentation
- `README.md` - Project overview
- `ADMIN_INTERFACE.md` - Complete admin documentation
- `ADMIN_QUICKSTART.md` - Quick reference
- `NAMESPACE_FIX.md` - Model naming fix
- `SESSION_MIDDLEWARE_FIX.md` - Middleware configuration

### Logs
```bash
# Development log
tail -f log/development.log

# Test log
tail -f log/test.log
```

### Rails Console
```bash
bin/rails console

# Check AdminUser
AdminUser.count
AdminUser.first.email

# Check API Keys
ApiKey.count

# Check Gateways
Gateway.count
```

## Summary

1. ✅ Configuration updated to support admin interface
2. ✅ Sessions and flash messages enabled
3. ✅ API endpoints remain fast and stateless
4. ✅ Both admin and API work together
5. ⚠️ **Must restart server after configuration changes**

Start the server with `bin/dev` and access the admin at `http://localhost:3000/admin/login`!

Happy coding! 🚀