<p align="center">
    <img src="https://melsoftzim.co.zw/assets/uploads/logo.jpg" width="200" alt="Prolex Logo">
</p>

<h1 align="center">Prolex - Legal Practice Management System</h1>

<p align="center">
    <strong>Version 1.89</strong><br>
    Built by <strong>Melsoft Private Limited</strong><br>
    Location: <strong>Harare CBD, Harare,Zimbabwe</strong>
</p>

<p align="center">
    <strong>Lead Engineer:</strong> Tadiwa Ashley Gwena.
</p>

---

## About This Project

Prolex is an enterprise-grade Legal Practice Management System built on Laravel. It provides comprehensive case management, financial tracking, and client relationship management for law firms.

### Core Capabilities
- **Case Management**: Full lifecycle legal case tracking
- **Client Management**: Client accounts, invoices, quotations, and receipts
- **Financial Management**: Cashbook, journals, age analysis, tax reports
- **Courtings**: Court filing management and tracking
- ** FilTime Tracking**: Billable hours and utilization reporting
- **Dashboard Analytics**: KPI tracking with DSO, collection rate, realization rate

---

## Permission Management System

Prolex features a robust, enterprise-grade permission management system supporting user, group, and tier-based access control with comprehensive audit logging.

### Key Features

- **Hierarchical Permissions**: Three-tier permission system (User → Tier → Group)
- **Immutable Audit Trail**: All login events logged with IP, user agent, and session data
- **Law-Firm Grade Compliance**: Account locking after failed attempts, session tracking
- **Soft-Deletes & Overrides**: Safe data deletion with override capabilities

---

## Database Overview

### Core Permission Tables (6 Tables)

| Table | Purpose | Primary Key |
|-------|---------|-------------|
| `users` | System users | `id` (BIGINT) |
| `roles` | Role definitions | `id` (BIGINT) |
| `user_roles` | User-role assignments | `user_role_id` (BIGINT) |
| `user_groups` | Group definitions | `user_group_id` (BIGINT) |
| `user_tiers` | Tier definitions | `tier_id` (BIGINT) |
| `user_sessions` | Login audit trail | `session_id` (BIGINT) |

### Database Specifications
- **BIGINT Keys**: All primary keys use BIGINT unsigned for scalability
- **Strict Foreign Key Enforcement**: Referential integrity enforced at database level
- **Timestamps**: Proper created_at/updated_at columns for audit purposes

---

## Permission Resolution Logic

Prolex implements a hierarchical permission resolution system with the following precedence:

```
User Specific → Tier Level → Group Level → Role Level
```

### 1. User-Level Permissions (Highest Priority)
- Stored in `users.permissions` as JSON array
- Directly assigned permissions take precedence
- Example: `["case.create", "case.edit", "report.view"]`

### 2. Tier-Based Access
- Users belong to one `UserTier` (e.g., Junior, Senior, Partner)
- Each tier defines baseline permissions
- Hierarchical: Junior < Senior < Partner < Managing

### 3. Group-Based Access
- Users can belong to one `Group` (e.g., Litigation, Corporate, Conveyancing)
- Groups define department-specific permissions
- Enables fine-grained access control by practice area

### 4. Role-Based Access
- Users have one `Role` assignment (e.g., Attorney, Paralegal, Admin)
- Roles define functional permissions
- Combined with tiers for comprehensive access control

### Account Security Features
- **Account Locking**: Automatically locks after 5 failed login attempts for 15 minutes
- **Session Tracking**: Every login creates a session record with IP and user agent
- **Audit Logging**: Login events captured in `user_sessions` table
- **Password Hashing**: Uses Laravel's built-in bcrypt hashing

---

## Installation

### Requirements

| Component | Minimum Version |
|-----------|------------------|
| PHP | 8.2+ |
| Laravel | 12.0 |
| MySQL | 5.7+ |
| Node.js | 18+ (for Vite) |
| Composer | 2.0+ |

### Database Setup

1. Create a new MySQL database named `prolex`
2. Import the SQL schema files in order:
   
```
bash
   # Core tables
   mysql -u root -p prolex < database/sql/settings_tables.sql
   
   # Run migrations
   php artisan migrate
   
   # Seed default data
   php artisan db:seed
   
```

### Environment Configuration

1. Copy `.env.example` to `.env`
2. Configure database connection:
   
```
env
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=prolex
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   
```

3. Generate application key:
   
```
bash
   php artisan key:generate
   
```

4. Install dependencies:
   
```
bash
   composer install
   npm install
   
```

5. Build assets:
   
```
bash
   npm run dev
   
```

### Running the Application

```
bash
# Start development server
php artisan serve

# Or use Laravel Sail for Docker
./vendor/bin/sail up
```

---

## Project Structure

```
prolex/
├── app/
│   ├── Http/           # Controllers and Middleware
│   ├── Models/         # Eloquent models
│   ├── Services/       # Business logic services
│   ├── Support/        # Helper classes
│   └── Listeners/      # Event listeners (login/logout)
├── database/
│   ├── migrations/     # Database migrations
│   ├── seeders/        # Database seeders
│   └── sql/            # SQL schema files
├── resources/
│   ├── views/          # Blade templates
│   ├── css/            # Stylesheets
│   └── js/             # JavaScript/Vue components
├── routes/             # Route definitions
└── config/             # Configuration files
```

---

## Technology Stack

- **Backend**: Laravel 12.0 (PHP 8.2+)
- **Frontend**: Blade Templates + Vite + Chart.js
- **Database**: MySQL 5.7+
- **PDF Generation**: TCPDF, DomPDF
- **Authentication**: Laravel Breeze/Jetstream
- **Session Management**: Database-driven sessions

---

## License

This project is proprietary software developed by **Melsoft Private Limited**.

Copyright © 2024 Melsoft Private Limited. All rights reserved.

---

## Support

For technical support or inquiries, contact the development team at Melsoft Private Limited, Zimbabwe.
