mad-lawsuit/README.md

# MAD Lawsuit Court Docket Website

A public-facing website for displaying court documents and filings for the lawsuit: **Elizabeth Kragh v. Montana Association of the Deaf**.

**Live Site**: https://v2.mad-lawsuit.org  
**Admin Dashboard**: https://v2.mad-lawsuit.org/admin/login

## 📋 Project Overview

This website provides public access to court documents from an ongoing lawsuit in Montana state court. Since the Montana court system requires a licensed attorney electronic account for access, this platform ensures transparency by making all case filings, motions, exhibits, and court decisions publicly accessible.

### Purpose

- **Public Transparency**: Makes court proceedings accessible to anyone interested
- **Document Organization**: Centralized, chronological display of all case filings
- **Real-time Updates**: Email subscription system for case updates
- **Professional Presentation**: Clean interface with document summaries and metadata

### Target Audience

- General public following the case
- Legal community (attorneys, paralegals, law students)
- Disability rights advocacy groups
- Media and journalists
- Researchers studying the case

## 🛠️ Technology Stack

### Backend
- **Framework**: Laravel 12.43.1
- **Language**: PHP 8.3.28
- **Database**: PostgreSQL 16
- **ORM**: Eloquent
- **Authentication**: Laravel Sanctum + Session

### Frontend
- **Framework**: Vue 3 with TypeScript
- **Routing**: Inertia.js (SSR-like experience)
- **Styling**: Tailwind CSS 3.x
- **Build Tool**: Vite 7.x
- **Components**: Vue Single File Components (SFC)

### Infrastructure
- **Containerization**: Docker with Alpine Linux
- **Web Server**: nginx 1.28.0
- **PHP**: PHP-FPM 8.3.28
- **Reverse Proxy**: Caddy (with automatic SSL)
- **Deployment**: Production server at 10.4.0.205

## ✨ Features

### Public Website
- **Court Docket Display**: Chronological list of all court filings
- **Document Viewer**: 
  - Desktop: Modal PDF viewer with download option
  - Mobile: Opens PDFs in new tab (optimized for iOS Safari)
- **Email Subscriptions**: Users can subscribe for case updates
- **Responsive Design**: Optimized for desktop, tablet, and mobile
- **Case Information**: Status, last updated date, and case details

### Admin Dashboard
- **Authentication**: Secure session-based login
- **Docket Entry Management**: Full CRUD operations
  - Create new entries with date, title, and summary
  - Edit existing entries
  - Delete entries (cascades to associated documents)
  - View entry details
- **Document Management**:
  - Upload PDF documents (500MB max)
  - UUID-based file naming for security
  - Multiple documents per docket entry
  - Delete documents
- **Subscriber Management**:
  - View all subscribers (paginated, 50 per page)
  - Deactivate subscribers
  - Statistics dashboard (total, active, inactive)
- **Dashboard Statistics**: Quick overview of entries, documents, and subscribers

## 🚀 Getting Started

### Prerequisites
- PHP 8.3+
- Composer
- Node.js 18+ and npm
- PostgreSQL 16+
- Docker (for production deployment)

### Local Development Setup

1. **Clone the repository**
   ```bash
   git clone https://gitea.sigd.net/chaulmark/mad-lawsuit.git
   cd mad-lawsuit
   ```

2. **Install PHP dependencies**
   ```bash
   composer install
   ```

3. **Install JavaScript dependencies**
   ```bash
   npm install
   ```

4. **Configure environment**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

5. **Configure database**
   Edit `.env` with your PostgreSQL credentials:
   ```env
   DB_CONNECTION=pgsql
   DB_HOST=127.0.0.1
   DB_PORT=5432
   DB_DATABASE=mad_lawsuit
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   ```

6. **Run migrations**
   ```bash
   php artisan migrate
   ```

7. **Seed admin user**
   ```bash
   php artisan db:seed --class=AdminSeeder
   ```

8. **Create storage symlink**
   ```bash
   php artisan storage:link
   ```

9. **Start development servers**
   ```bash
   # Terminal 1: Laravel development server
   php artisan serve

   # Terminal 2: Vite development server
   npm run dev
   ```

10. **Access the application**
    - Public site: http://localhost:8000
    - Admin dashboard: http://localhost:8000/admin/login
    - Default credentials: See `database/seeders/AdminSeeder.php`

### Production Deployment

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed production deployment instructions using Docker.

## 📁 Project Structure

```
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/          # Admin dashboard controllers
│   │   │   ├── HomeController.php
│   │   │   └── SubscriptionController.php
│   │   └── Middleware/
│   │       └── AdminAuth.php   # Admin authentication middleware
│   └── Models/
│       ├── AdminUser.php
│       ├── DocketEntry.php
│       ├── Document.php
│       └── Subscription.php
├── database/
│   ├── migrations/             # Database schema
│   └── seeders/
│       ├── AdminSeeder.php
│       └── V1DataMigrationSeeder.php
├── resources/
│   ├── js/
│   │   ├── Components/
│   │   │   └── PDFViewer.vue   # PDF modal viewer
│   │   ├── Pages/
│   │   │   ├── Home.vue        # Public homepage
│   │   │   └── Admin/          # Admin dashboard pages
│   │   └── app.ts
│   └── css/
│       └── app.css
├── routes/
│   └── web.php                 # Application routes
├── docker/                     # Docker configuration
├── cline_docs/                 # Project documentation
└── storage/
    └── app/
        └── public/
            └── documents/      # Uploaded PDF files
```

## 🔐 Security

- **Admin Authentication**: Session-based authentication separate from Laravel Breeze
- **File Security**: UUID-based file naming prevents direct access guessing
- **CSRF Protection**: Laravel's built-in CSRF protection on all forms
- **SQL Injection**: Eloquent ORM prevents SQL injection
- **XSS Protection**: Vue.js automatic escaping
- **HTTPS**: Automatic SSL via Caddy in production

## 📊 Database Schema

### Tables
- **docket_entries**: Court filings with date, title, summary, notes
- **documents**: PDF files linked to docket entries
- **subscriptions**: Email subscribers with active/inactive status
- **admin_users**: Admin authentication

### Relationships
- One docket entry has many documents
- Documents cascade delete when entry is deleted
- Subscriptions are soft-deleted (is_active flag)

## 🧪 Testing

```bash
# Run PHP tests
php artisan test

# Run with coverage
php artisan test --coverage
```

## 📝 API Endpoints

### Public Routes
- `GET /` - Homepage with docket entries
- `POST /api/subscribe` - Email subscription
- `GET /api/documents/{id}/download` - Download PDF

### Admin Routes (requires authentication)
- `GET /admin/login` - Admin login page
- `POST /admin/login` - Process login
- `POST /admin/logout` - Logout
- `GET /admin/dashboard` - Admin dashboard
- Resource routes for:
  - `/admin/docket-entries` - Docket entry management
  - `/admin/documents` - Document management
  - `/admin/subscribers` - Subscriber management

## 🐛 Known Issues & Solutions

### Mobile PDF Viewing
- **Issue**: iOS Safari renders PDFs in iframes as single-page images
- **Solution**: On screens < 768px, PDFs open in a new tab instead of modal viewer

### Admin Subscribers Page
- **Fixed**: Changed pagination from `->through()` to `->items()` to properly pass array to Vue

## 🤝 Contributing

This is a private project for a specific lawsuit. For questions or issues, contact the repository owner.

## 📄 License

Proprietary - All rights reserved.

## 👥 Credits

- **Development**: Built with Laravel, Vue.js, and Inertia.js
- **Design**: DeafGain LLC (http://deafgain.org)
- **Hosting**: Self-hosted on dedicated infrastructure

## 📞 Support

For technical issues or questions:
- Repository: https://gitea.sigd.net/chaulmark/mad-lawsuit
- Production URL: https://v2.mad-lawsuit.org

---

**Version**: 2.0  
**Last Updated**: December 2025  
**Status**: Production Ready ✅