mad-lawsuit/README.md

# Eliza Kragh v. Montana Association of the Deaf - Court Docket Website

A public-facing website to display court documents and filings for the ongoing lawsuit: **Eliza Kragh v. Montana Association of the Deaf**. The system provides public transparency for court proceedings while allowing administrative management of documents and user notifications.

## 🏗️ Architecture

- **Frontend**: Next.js 15.4.0 with React 19, TypeScript 6.0, Tailwind CSS
- **Backend**: Node.js 22 LTS, Express.js 6.0, TypeScript 6.0, Prisma 5.0
- **Database**: PostgreSQL 17.5 with Redis caching
- **Infrastructure**: Docker Engine 28.1.1, Nginx reverse proxy

## 🚀 Quick Start

### Prerequisites

- Node.js 22 LTS
- Docker Engine 28.1.1 & Docker Compose
- pnpm (recommended package manager)

### Development Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd eliza-mad-docket-website
   ```

2. **Start the development environment**
   ```bash
   docker-compose up -d
   ```

3. **Install dependencies**
   ```bash
   # Backend
   cd backend
   pnpm install
   
   # Frontend
   cd ../frontend
   pnpm install
   ```

4. **Set up the database**
   ```bash
   cd backend
   pnpm prisma migrate dev
   pnpm prisma generate
   ```

5. **Start development servers**
   ```bash
   # Backend (in backend directory)
   pnpm dev
   
   # Frontend (in frontend directory)
   pnpm dev
   ```

6. **Access the application**
   - Frontend: http://localhost:3000
   - Backend API: http://localhost:3001
   - Database: localhost:5432
   - Redis: localhost:6379

## 📁 Project Structure

```
eliza-mad-docket/
├── backend/                 # Express.js API
│   ├── src/
│   │   ├── routes/         # API routes
│   │   ├── middleware/     # Express middleware
│   │   ├── utils/          # Utility functions
│   │   └── index.ts        # Main server file
│   ├── prisma/             # Database schema & migrations
│   ├── Dockerfile          # Backend container
│   └── package.json
├── frontend/                # Next.js application
│   ├── src/
│   │   ├── app/            # Next.js 13+ app directory
│   │   ├── components/     # React components
│   │   └── lib/            # Utility libraries
│   ├── Dockerfile          # Frontend container
│   └── package.json
├── cline_docs/             # Memory Bank documentation
├── docker-compose.yml      # Container orchestration
└── DESIGN_SPECIFICATION.md # Complete technical spec
```

## 🔧 Environment Variables

### Backend (.env)
```env
DATABASE_URL=postgresql://docket_user:docket_pass@localhost:5432/docket_db
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=24h
UPLOAD_DIR=/app/uploads
MAX_FILE_SIZE=10485760
NODE_ENV=development
```

### Frontend (.env.local)
```env
NEXT_PUBLIC_API_URL=http://localhost:3001/api
```

## 🗄️ Database Schema

The application uses PostgreSQL with the following main tables:

- **docket_entries**: Main court filings
- **documents**: PDF files associated with entries
- **subscriptions**: Email subscriptions for notifications
- **admin_users**: Administrative users

## 🔐 Security Features

- JWT authentication for admin access
- File access control through API endpoints
- UUID-based file naming for security
- Input validation and sanitization
- Rate limiting on API endpoints
- CORS protection

## 📄 File Management

- **Storage**: Local filesystem with Docker volumes
- **Naming**: UUID-based scheme: `{entry-id}_{document-type}_{uuid}.pdf`
- **Structure**: Organized by year/month directories
- **Security**: Files served only through API endpoints
- **Limits**: 10MB maximum file size, PDF only

## 🚀 Deployment

### Production Deployment

For production deployment with Portainer and Caddy, see the complete [DEPLOYMENT.md](./DEPLOYMENT.md) guide.

**Quick Production Setup:**

1. **Prepare environment**
   ```bash
   cp .env.prod .env
   # Edit .env with secure values
   ```

2. **Deploy with production compose**
   ```bash
   docker-compose -f docker-compose.prod.yml up -d
   ```

3. **Set up admin user for Eliza**
   ```bash
   docker exec -it backend_container node setup-admin.js
   ```

### Development Setup

1. **Build containers**
   ```bash
   docker-compose build
   ```

2. **Run development stack**
   ```bash
   docker-compose up -d
   ```

3. **Run database migrations**
   ```bash
   docker-compose exec backend pnpm prisma migrate deploy
   ```

### Environment-specific configurations

- **Development**: Hot reloading, detailed logging, demo credentials
- **Production**: Optimized builds, security headers, SSL/TLS, secure credentials

## 🧪 Testing

```bash
# Backend tests
cd backend
pnpm test

# Frontend tests
cd frontend
pnpm test

# Type checking
pnpm type-check
```

## 📊 API Endpoints

### Public Endpoints
- `GET /api/docket-entries` - Get all docket entries with documents
- `GET /api/documents/:id/download` - Download PDF file
- `POST /api/subscribe` - Subscribe to email notifications
- `GET /api/unsubscribe/:token` - Unsubscribe from notifications

### Admin Endpoints (Protected)
- `POST /api/auth/login` - Admin authentication
- `POST /api/docket-entries` - Create new docket entry
- `PUT /api/docket-entries/:id` - Update docket entry
- `DELETE /api/docket-entries/:id` - Delete docket entry
- `POST /api/documents` - Upload document
- `PUT /api/documents/:id` - Update document metadata
- `DELETE /api/documents/:id` - Delete document

## 🎨 UI Features

### Public Interface
- Clean, responsive design
- Document viewing with PDF.js
- Email subscription system
- Mobile-friendly layout
- Accessibility compliant

### Admin Interface
- Secure login system
- Multi-file upload support
- Document management (CRUD operations)
- File replacement capability
- Metadata editing

## 📧 Email Notifications

- Automatic notifications for new filings
- Unsubscribe functionality
- HTML email templates
- Background job processing

## 🔍 Monitoring & Logging

- Structured logging with Winston
- Request/response logging
- Error tracking and reporting
- Health check endpoints
- Performance monitoring

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 📞 Support

For questions or issues, please contact the development team or create an issue in the repository.

---

**Note**: This is a public transparency tool for court proceedings. All uploaded documents become publicly accessible through this website.