# OIA Alert System - Features & Functionality

## Core Modules

### 1. Authentication Module

#### Features
- User registration with validation
- Secure login with session management
- Remember me functionality
- Password reset via email
- Email verification (optional)
- Automatic session timeout

#### Files
- Routes: `routes/auth.php`
- Models: `app/Models/User.php`
- Controllers: Built-in by Laravel Breeze

#### Configuration
- Edit auth settings in `config/auth.php`
- Password hashing in `config/hashing.php`

---

### 2. Dashboard Module

#### Features
- **Statistics Cards**:
  - Total alerts submitted by user
  - Pending alerts count
  - Resolved alerts count
  - Critical alerts count

- **Recent Alerts List**:
  - Shows 5 most recent alerts
  - Quick links to view details
  - Status and severity indicators

- **Notifications Feed**:
  - Displays latest unread notifications
  - Quick notification counter in header
  - Clickable notification bell icon

- **User Greeting**:
  - Personalized greeting with user name
  - Current day of week display
  - User avatar

#### File
- Controller: `app/Http/Controllers/DashboardController.php`
- View: `resources/views/dashboard.blade.php`
- Route: `GET /dashboard`

#### Data Displayed
```
Dashboard Controller:
- $totalAlerts: Count of all user alerts
- $pendingAlerts: Count of pending status alerts
- $resolvedAlerts: Count of resolved status alerts
- $criticalAlerts: Count of critical severity alerts
- $recentAlerts: Latest 5 alerts
- $unreadNotifications: All unread notifications
```

---

### 3. Alert Management Module

#### 3.1 Submit Alert

**Purpose**: Create and submit new alerts

**Fields**:
- Title (required, max 255 chars)
- Description (required, longtext)
- Alert Type (required, dropdown)
- Severity Level (required: low, medium, high, critical)
- Location (optional, max 255 chars)
- Image Upload (optional, max 5MB)
- Evidence Upload (optional, max 10MB)

**Processing**:
1. Validate all inputs
2. Upload files to storage
3. Create alert record
4. Send notification to admins
5. Redirect to alerts list

**File**:
- Controller: `app/Http/Controllers/AlertController@create` & `@store`
- View: `resources/views/alerts/create.blade.php`
- Routes: `GET/POST /alerts`

---

#### 3.2 My Alerts List

**Purpose**: View and manage user's own alerts

**Features**:
- Paginated list (10 per page)
- Severity color coding
- Status badges
- Alert type display
- Submission date
- Quick action links

**Actions**:
- View Details
- Edit Alert
- Delete Alert

**Filtering**:
- By user ID only
- Sortable by date (latest first)

**File**:
- Controller: `app/Http/Controllers/AlertController@index`
- View: `resources/views/alerts/index.blade.php`
- Route: `GET /alerts`

---

#### 3.3 Browse OIA Alerts

**Purpose**: View all alerts from community

**Features**:
- Grid layout (responsive cards)
- Paginated list (10 per page)
- Alert title and preview
- Submitter name
- Severity badge
- Type and date
- Time elapsed display (e.g., "2 days ago")

**Actions**:
- View Full Details

**Display**:
- All alerts (no filtering by user)
- All fields visible except edit/delete

**File**:
- Controller: `app/Http/Controllers/AlertController@oiaAlerts`
- View: `resources/views/alerts/oia-alerts.blade.php`
- Route: `GET /alerts/oia/alerts`

---

#### 3.4 Alert Details

**Purpose**: View complete alert information

**Displays**:
- Full title and description
- All metadata (type, severity, status)
- Location information
- Submitter name and date
- Attachments (if any)
- Related notifications (if any)

**Features**:
- Severity-based left border color
- Status and severity badges
- Downloadable evidence files
- Viewable images
- Navigation breadcrumb

**Actions** (Own Alerts Only):
- Edit Alert
- Delete Alert

**Files**:
- Controller: `app/Http/Controllers/AlertController@show`
- View: `resources/views/alerts/show.blade.php`
- Route: `GET /alerts/{id}`
- Policy: `app/Policies/AlertPolicy@view`

---

#### 3.5 Edit Alert

**Purpose**: Modify existing alert

**Editable Fields**:
- Title
- Description
- Alert Type
- Severity
- Location

**Non-Editable**:
- Attachments (can't be changed)
- Submitter
- Status (admin only)

**Access Control**:
- Only alert owner can edit
- Policy: `AlertPolicy@update`

**Files**:
- Controller: `app/Http/Controllers/AlertController@edit` & `@update`
- View: `resources/views/alerts/edit.blade.php`
- Route: `GET/PUT /alerts/{id}/edit`

---

#### 3.6 Delete Alert

**Purpose**: Remove alert from system

**Features**:
- Soft confirmation dialog
- Only owner can delete
- Related notifications deleted (cascade)
- Attachments removed from storage

**Files**:
- Controller: `app/Http/Controllers/AlertController@destroy`
- Route: `DELETE /alerts/{id}`

---

### 4. Notification Module

#### Features
- Create notifications for alerts
- Mark as read/unread
- Delete notifications
- Unread counter display
- Notification type system

#### Notification Types
- `info` - Information (blue)
- `warning` - Warning (orange)
- `error` - Error (red)
- `success` - Success (green)

#### API Endpoints
```
GET    /notifications/unread          - Get unread (JSON)
PUT    /notifications/{id}/read       - Mark as read
POST   /notifications/mark-all-read   - Mark all read
DELETE /notifications/{id}            - Delete
```

#### Files
- Controller: `app/Http/Controllers/NotificationController.php`
- Model: `app/Models/Notification.php`
- Migration: `create_notifications_table.php`

---

### 5. User Profile Module

#### 5.1 View Profile

**Displays**:
- User avatar (generated from name)
- Name and email
- Member since date
- Activity statistics:
  - Total alerts submitted
  - Pending alerts
  - Resolved alerts

**Files**:
- Controller: `app/Http/Controllers/ProfileController@show`
- View: `resources/views/profile/show.blade.php`
- Route: `GET /profile`

---

#### 5.2 Edit Profile

**Editable Fields**:
- Name (required)
- Email (required, unique)
- Phone (optional)

**Validation**:
- Email uniqueness (except current user)
- Name required
- Email format

**Files**:
- Controller: `app/Http/Controllers/ProfileController@edit` & `@update`
- View: `resources/views/profile/edit.blade.php`
- Route: `GET/PUT /profile/edit`

---

#### 5.3 Password Security

**Purpose**: Change password securely

**Fields**:
- Current Password (for verification)
- New Password (8+ chars minimum)
- Confirm Password (must match)

**Validation**:
- Current password verification
- Password minimum length
- Password confirmation match
- Different from current password

**Security**:
- Current password required
- Passwords hashed with bcrypt
- Uses `current_password` validation rule

**Files**:
- Controller: `app/Http/Controllers/ProfileController@passwordForm` & `@updatePassword`
- View: `resources/views/profile/password.blade.php`
- Route: `GET/PUT /profile/password`

---

### 6. Navigation & Layout

#### Main Layout Template
**File**: `resources/views/layouts/app.blade.php`

#### Components
- **Sidebar Navigation**:
  - Logo/Branding
  - Navigation menu items
  - Bottom menu items
  - Collapsible on mobile

- **Top Bar**:
  - User greeting with avatar
  - Day of week display
  - Notification bell
  - Unread count badge

- **Main Content Area**:
  - Scrollable content section
  - Background color
  - Padding and spacing

#### Responsive Design
- Mobile: Hamburger menu toggle
- Tablet: Sidebar collapse/expand
- Desktop: Full sidebar always visible

#### Navigation Items
1. **Dashboard** (home icon)
2. **OIA Alerts** (broadcast icon)
3. **My Alerts** (chart icon)
4. **Submit Alert** (document icon)
5. **Settings** (gear icon)
6. **Help & Support** (headphones icon)
7. **Sign Out** (logout icon)

---

## Database Models

### User Model
**Relationships**:
- `hasMany('Alert')` - User's submitted alerts
- `hasMany('Notification')` - User's notifications

**Methods**:
- Inherits from `Authenticatable`
- Includes timestamp functionality

---

### Alert Model
**Fields**:
- id, user_id, alert_type_id, title, description
- severity, status, location, image_path, evidence_path
- created_at, updated_at

**Relationships**:
- `belongsTo('User')` - Alert creator
- `belongsTo('AlertType')` - Alert category
- `hasMany('Notification')` - Related notifications

**Mass Assignment**:
- All fillable fields

---

### AlertType Model
**Fields**:
- id, name, description, icon, created_at, updated_at

**Relationships**:
- `hasMany('Alert')` - Alerts of this type

**Default Types**:
1. Suspicious Activity
2. Safety Concern
3. Fraud
4. Environmental Issue
5. Infrastructure Problem
6. Health & Hygiene
7. Traffic Violation
8. Other

---

### Notification Model
**Fields**:
- id, user_id, alert_id, title, message, type, read_at
- created_at, updated_at

**Relationships**:
- `belongsTo('User')` - Notification recipient
- `belongsTo('Alert')` - Related alert

**Methods**:
- `markAsRead()` - Set read_at timestamp

---

## Design System

### Color Palette
```css
--primary: #ff5106 (Orange)
--secondary: #f7f7f7 (Light Gray)
--text-primary: #111 (Dark)
--text-secondary: #666 (Gray)
--border: #efefef (Light Border)
--border-highlight: #ff510636 (Orange Tint)
```

### Severity Colors
- **Low**: #4CAF50 (Green)
- **Medium**: #2196F3 (Blue)
- **High**: #FF9800 (Orange)
- **Critical**: #F44336 (Red)

### Responsive Breakpoints
```css
Mobile: < 768px
Tablet: 768px - 1024px
Desktop: > 1024px
```

### Typography
- Font: Arial, Helvetica Neue, Helvetica, sans-serif
- Base Size: 14px
- Line Height: 20px
- Headings: Bold, varied sizes (38px, 28px, 18px, 16px)

---

## Validation Rules

### Alert Submission
```php
'title' => 'required|string|max:255'
'description' => 'required|string'
'alert_type_id' => 'required|exists:alert_types,id'
'severity' => 'required|in:low,medium,high,critical'
'location' => 'nullable|string|max:255'
'image' => 'nullable|image|max:5120'
'evidence' => 'nullable|file|max:10240'
```

### Profile Update
```php
'name' => 'required|string|max:255'
'email' => 'required|email|max:255|unique:users,email,'
'phone' => 'nullable|string|max:20'
```

### Password Change
```php
'current_password' => 'required|current_password'
'password' => 'required|string|min:8|confirmed'
```

---

## File Upload

### Locations
- Images: `storage/app/public/alerts/images/`
- Evidence: `storage/app/public/alerts/evidence/`

### Access
- Through symbolic link: `/storage/alerts/images/{filename}`
- Direct: `http://localhost:8000/storage/alerts/images/{filename}`

### Cleanup
- Files deleted when alert is deleted
- Old files remain if alert is updated (consider adding cleanup)

---

## Authorization & Security

### Policies
- **AlertPolicy**:
  - `view(User, Alert)` - Can view alert
  - `update(User, Alert)` - Can edit alert
  - `delete(User, Alert)` - Can delete alert

- **NotificationPolicy**:
  - `update(User, Notification)` - Can mark read
  - `delete(User, Notification)` - Can delete

### Access Control
- All protected routes require authentication
- Alert operations limited to owners
- Admin features can be added using roles

---

## Future Enhancement Ideas

1. **Real-time Features**:
   - WebSocket notifications
   - Live alert updates
   - Chat system

2. **Admin Panel**:
   - Alert moderation
   - User management
   - Statistics dashboard
   - Alert type management

3. **Advanced Features**:
   - Map integration
   - Alert categories
   - Search and filtering
   - Export to CSV/PDF
   - Email notifications
   - SMS alerts

4. **Social Features**:
   - Comments on alerts
   - Upvoting system
   - User rankings
   - Community scoring

5. **Mobile App**:
   - Native iOS app
   - Native Android app
   - Push notifications

---

## Testing

### Key Test Scenarios

1. **Authentication**:
   - Register new user
   - Login/logout
   - Password reset

2. **Alerts**:
   - Submit alert with/without files
   - Edit own alert
   - View others' alerts
   - Cannot edit others' alerts
   - Delete alert

3. **Notifications**:
   - Mark as read
   - Delete notification
   - Counter accuracy

4. **Profile**:
   - Update information
   - Change password
   - View statistics

---

## Performance Considerations

### Optimizations
- Pagination (10 items per page)
- Eager loading of relationships
- Database indexes on foreign keys
- SQL query optimization
- Caching where appropriate

### Monitoring
- Check `storage/logs/laravel.log` for errors
- Use Laravel Debugbar for debugging
- Monitor database queries
- Profile slow endpoints

---

This comprehensive documentation covers all features, modules, and functionality of the OIA Alert System.