# SIM Card Management System - Specification

## 1. Project Overview

**Project Name:** SIM Card Management System  
**Type:** Web Application (Laravel)  
**Core Functionality:** A telecom administration system for managing SIM cards, customers, activations, balances, transactions, and user roles through a secure web dashboard.  
**Target Users:** Super Admins, Admins, Agents, and Customers

---

## 2. Tech Stack

- **Backend:** Laravel 11
- **Frontend:** Blade Templates + Bootstrap 5
- **Database:** MySQL
- **Authentication:** Laravel Breeze
- **CSS Framework:** Bootstrap 5 + Custom CSS
- **PHP Version:** 8.2+
- **Node.js:** For asset compilation

---

## 3. User Roles & Permissions

| Role | Description | Permissions |
|------|-------------|--------------|
| Super Admin | Full system control | All permissions, manage users, system settings |
| Admin | Manage SIM cards, customers, reports | Manage SIMs, customers, transactions, reports |
| Agent | Register SIM cards, activate SIMs, manage assigned customers | Register/activate SIMs, view assigned customers |
| Customer | View SIM status, balance, transactions | View own SIMs, balance, transaction history |

---

## 4. Database Schema

### 4.1 Users Table
```php
$table->id();
$table->string('name');
$table->string('email')->unique();
$table->string('password');
$table->foreignId('role_id')->constrained();
$table->foreignId('created_by')->nullable();
$table->boolean('is_active')->default(true);
$table->timestamp('email_verified_at')->nullable();
$table->rememberToken();
$table->timestamps();
```

### 4.2 Roles Table
```php
$table->id();
$table->string('name')->unique();
$table->string('display_name');
$table->timestamps();
```

### 4.3 Permissions Table
```php
$table->id();
$table->string('name')->unique();
$table->string('display_name');
$table->timestamps();
```

### 4.4 Role_Permissions Table (Pivot)
```php
$table->foreignId('role_id')->constrained();
$table->foreignId('permission_id')->constrained();
$table->primary(['role_id', 'permission_id']);
```

### 4.5 Sims Table
```php
$table->id();
$table->string('sim_number')->unique();
$table->string('iccid')->unique();
$table->string('phone_number')->nullable();
$table->foreignId('customer_id')->nullable()->constrained();
$table->enum('status', ['available', 'assigned', 'active', 'inactive', 'suspended', 'blocked'])->default('available');
$table->decimal('balance', 15, 2)->default(0);
$table->decimal('initial_balance', 15, 2)->default(0);
$table->foreignId('assigned_agent_id')->nullable()->constrained('users');
$table->timestamp('activated_at')->nullable();
$table->timestamp('deactivated_at')->nullable();
$table->timestamps();
```

### 4.6 Customers Table
```php
$table->id();
$table->string('name');
$table->string('email')->unique();
$table->string('phone')->nullable();
$table->string('address')->nullable();
$table->string('id_type')->nullable(); // passport, nid, license
$table->string('id_number')->nullable();
$table->string('id_document_path')->nullable();
$table->boolean('is_verified')->default(false);
$table->foreignId('created_by')->nullable()->constrained('users');
$table->timestamps();
```

### 4.7 Sim_Assignments Table
```php
$table->id();
$table->foreignId('sim_id')->constrained();
$table->foreignId('customer_id')->constrained();
$table->foreignId('assigned_by')->nullable()->constrained('users');
$table->timestamp('assigned_at');
$table->timestamp('unassigned_at')->nullable();
$table->timestamps();
```

### 4.8 Activations Table
```php
$table->id();
$table->foreignId('sim_id')->constrained();
$table->foreignId('activated_by')->nullable()->constrained('users');
$table->string('otp')->nullable();
$table->timestamp('otp_sent_at')->nullable();
$table->timestamp('activated_at')->nullable();
$table->string('activation_method'); // otp, manual
$table->timestamps();
```

### 4.9 Transactions Table
```php
$table->id();
$table->foreignId('sim_id')->constrained();
$table->foreignId('customer_id')->nullable()->constrained();
$table->foreignId('processed_by')->nullable()->constrained('users');
$table->enum('type', ['recharge', 'debit', 'refund', 'activation']);
$table->decimal('amount', 15, 2);
$table->decimal('balance_before', 15, 2);
$table->decimal('balance_after', 15, 2);
$table->string('description')->nullable();
$table->string('reference')->nullable();
$table->timestamps();
```

### 4.10 Payments Table
```php
$table->id();
$table->foreignId('customer_id')->nullable()->constrained();
$table->foreignId('user_id')->nullable()->constrained('users');
$table->foreignId('transaction_id')->nullable()->constrained();
$table->decimal('amount', 15, 2);
$table->string('payment_method'); // cash, card, mobile_money
$table->string('reference')->nullable();
$table->enum('status', ['pending', 'completed', 'failed', 'refunded'])->default('pending');
$table->timestamps();
```

### 4.11 Notifications Table
```php
$table->id();
$table->foreignId('user_id')->nullable()->constrained();
$table->foreignId('customer_id')->nullable()->constrained();
$table->string('type'); // sms, email, system
$table->string('channel'); // sms, email, in_app
$table->string('title');
$table->text('message');
$table->boolean('is_sent')->default(false);
$table->timestamp('sent_at')->nullable();
$table->timestamps();
```

### 4.12 Activity_Logs Table
```php
$table->id();
$table->foreignId('user_id')->nullable()->constrained();
$table->string('action');
$table->string('entity_type');
$table->foreignId('entity_id')->nullable();
$table->text('description');
$table->json('old_values')->nullable();
$table->json('new_values')->nullable();
$table->timestamps();
```

---

## 5. Core Modules Specification

### 5.1 SIM Card Management
- **Add SIM:** Form with SIM number, ICCID, initial balance
- **Activate/Deactivate:** Toggle SIM status with confirmation
- **Block/Unblock:** Block SIM for security reasons
- **Assign SIM:** Link SIM to customer
- **SIM History:** View all changes to SIM status
- **Bulk Import:** CSV import for bulk SIM registration

### 5.2 Customer Management
- **Register Customer:** Name, email, phone, address, ID verification
- **Update Customer:** Edit customer details
- **Assign SIMs:** Link multiple SIMs to one customer
- **Customer Verification:** Upload ID document
- **Customer List:** Searchable, filterable list

### 5.3 SIM Activation System
- **Activation Form:** Enter SIM number
- **OTP Generation:** 6-digit random OTP
- **OTP Verification:** Validate OTP within 10 minutes
- **Activation Log:** Record all activations with timestamp

### 5.4 Balance & Usage Tracking
- **Balance Display:** Show current balance per SIM
- **Top-up/Recharge:** Add balance via payment
- **Usage History:** View all balance changes
- **Low Balance Alert:** Trigger notification below threshold

### 5.5 Transactions Module
- **Recharge History:** List all recharges
- **Payment Processing:** Record payments
- **Receipt Generation:** PDF download
- **Transaction Filter:** By date, type, customer

### 5.6 User & Role Management
- **Create User:** Name, email, role assignment
- **Edit User:** Modify user details and role
- **Assign Permissions:** Role-based access control
- **Activity Log:** Track user actions

### 5.7 Reporting System
- **Dashboard Reports:** SIM counts, activations, revenue
- **Date Range Filter:** Daily, weekly, monthly, custom
- **Export:** Excel download
- **PDF Reports:** Printable reports

### 5.8 Notification System
- **In-App Notifications:** System alerts
- **Email Notifications:** Configurable alerts
- **SMS Notifications:** SIM activation, balance alerts (placeholder)

---

## 6. Dashboard Specification

### 6.1 Super Admin / Admin Dashboard
- **Stats Cards:**
  - Total SIM Cards
  - Active SIMs
  - Total Customers
  - Total Revenue
- **Charts:**
  - Daily Activations (Line chart)
  - Revenue by Month (Bar chart)
  - SIM Status Distribution (Pie chart)
- **Recent Activities:** Last 10 actions
- **Quick Actions:** Add SIM, Add Customer, New Recharge

### 6.2 Agent Dashboard
- **Stats Cards:**
  - SIMs Registered Today
  - SIMs Activated Today
  - Assigned Customers
- **Quick Actions:** Register SIM, Activate SIM

### 6.3 Customer Dashboard (Optional)
- **My SIMs:** List of assigned SIMs
- **Balance:** Current balance
- **Transactions:** Recent transactions

---

## 7. UI/UX Specification

### 7.1 Layout
- **Sidebar:** Fixed left sidebar (240px) with navigation
- **Header:** Fixed top header (60px) with user menu
- **Content Area:** Scrollable main content
- **Responsive:** Collapsible sidebar on mobile

### 7.2 Color Scheme
- **Primary:** #2563eb (Blue)
- **Secondary:** #64748b (Slate)
- **Success:** #22c55e (Green)
- **Danger:** #ef4444 (Red)
- **Warning:** #f59e0b (Amber)
- **Background:** #f8fafc (Light gray)
- **Card Background:** #ffffff

### 7.3 Typography
- **Font Family:** 'Inter', system-ui, sans-serif
- **Headings:** Bold, various sizes
- **Body:** Regular, 14px
- **Small:** 12px

### 7.4 Components
- **Buttons:** Primary, Secondary, Danger, Success
- **Forms:** Floating labels, validation states
- **Tables:** Striped rows, pagination
- **Cards:** Shadow, rounded corners
- **Modals:** Centered, backdrop

---

## 8. Security Features

- **Authentication:** Laravel Breeze (login/register)
- **Role-based Access:** Middleware for role verification
- **CSRF Protection:** Built-in Laravel CSRF tokens
- **Password Hashing:** bcrypt
- **Session Management:** Configurable session timeout
- **Input Validation:** Form requests with validation

---

## 9. Acceptance Criteria

1. Users can register and login with email/password
2. Super Admin can create users with different roles
3. Admins can add, edit, delete SIM cards
4. Admins can register and manage customers
5. Agents can register SIM cards assigned to them
6. SIM activation with OTP verification works
7. Balance top-up and tracking works
8. Transactions are recorded with full history
9. Dashboard shows correct statistics
10. Reports can be generated and exported
11. Activity logs capture all user actions
12. Role-based access restricts unauthorized actions
13. UI is responsive and user-friendly

---

## 10. File Structure

```
simcard/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   ├── Middleware/
│   │   └── Requests/
│   ├── Models/
│   ├── Providers/
│   └── Policies/
├── database/
│   ├── migrations/
│   └── seeders/
├── resources/
│   ├── views/
│   └── css/
├── routes/
├── tests/
├── public/
└── SPEC.md
```