rothbard/README.md

# Rothbard Client Portal

A secure, server-side rendered client portal for Rothbard Law Group that enables authenticated users to view and manage their legal cases from the Filevine case management platform.

## Overview

This web application provides a customized interface for law firm clients to:
- Authenticate securely using Firebase Authentication
- View their assigned legal cases and matters
- Access case details including client information, matter descriptions, and contacts
- Interact with Filevine API data in a user-friendly dashboard format

## Architecture

The application is built with:
- **Backend**: Flask (Python) web server
- **Frontend**: Server-side rendered HTML with Tailwind CSS
- **Authentication**: Firebase Authentication with session management
- **Database**: Firestore for user profiles and preferences
- **External API**: Filevine API for case management data

## Project Structure

```
rothbard/
├── app.py                 # Main Flask application with routes and API integrations
├── generate_sample.py     # Utility to generate sample Filevine API responses
├── requirements.txt       # Python dependencies
├── rothbard-service-account.json  # Firebase service account credentials
├── rothbard-staging2-12345-firebase-adminsdk-fbsvc-7f95268383.json  # Firebase service account for staging
├── static/
│   └── auth.js           # Client-side authentication handling
├── templates/            # Jinja2 HTML templates
│   ├── base.html        # Base template with navigation
│   ├── login.html       # Firebase login page
│   ├── welcome.html     # User welcome/onboarding page
│   ├── dashboard.html   # Main case dashboard
│   ├── admin_users.html # Admin user management interface
│   ├── admin_user_edit.html # Admin user edit interface
│   ├── admin_user_create.html # Admin user creation interface
│   └── _pagination.html # Pagination component
├── examples/            # Sample Filevine API responses
│   ├── forms__complaintInfo.json
│   ├── forms__newFileReview.json
│   ├── project_tasks.json
│   ├── project_type_pahe_list.json
│   ├── project_team.json
│   └── ...
├── .env                 # Environment variables (not tracked)
├── .gcloudignore        # Files ignored by Google Cloud Build
├── .gitignore           # Files ignored by Git
├── cloudbuild.yaml      # Google Cloud Build configuration
├── Dockerfile           # Containerization configuration
├── deploy.sh            # Deployment script
├── main.tf              # Terraform infrastructure as code
├── firestore.rules      # Firestore security rules
├── column_mapping.json  # Column mapping configuration (unused)
├── DEPLOY.md            # Deployment instructions
├── CLAUDE.md            # Development guidance
└── utils.py             # Utility functions for user profile management
```

## Core Features

### Authentication System
- Firebase Authentication integration for secure user login
- Server-side session management with 8-hour expiration
- User profile management in Firestore
- Role-based access control (admin-enabled users only)
- Admin interface for user management

### Case Management Dashboard
- Real-time fetching of projects from Filevine API
- Project filtering based on user's assigned email
- Detailed case information display including:
  - Client names and matter descriptions
  - Project numbers and incident dates
  - Contact information and project URLs
- Responsive design using Tailwind CSS
- Configurable column visibility with local storage
- Pagination for large datasets
- Admin simulation mode to view other users' cases

### API Integration
- OAuth 2.0 authentication with Filevine API
- Bearer token management and refresh
- Comprehensive data fetching:
  - Project lists with pagination support
  - Individual project details
  - Client information
  - Project contacts
  - Project tasks and forms

### Admin Interface
- Comprehensive user management dashboard
- Enable/disable user access
- Grant/revoke admin privileges
- Reset user passwords
- Create new users
- View all user profiles
- Simulate case email access for testing

## Configuration

### Required Environment Variables

Create a `.env` file with the following variables:

```bash
# Flask Configuration
FLASK_SECRET_KEY=your-secret-key-here

# Firebase Configuration
# Choose ONE of these approaches:
# 1) Path to JSON creds file
GOOGLE_APPLICATION_CREDENTIALS=./rothbard-staging2-12345-firebase-adminsdk-fbsvc-7f95268383.json
# 2) Or inline JSON (escaped as single line)
# FIREBASE_SERVICE_ACCOUNT_JSON="{\"type\":\"service_account\",...}"

# Front-end Firebase (public — safe to expose)
FIREBASE_API_KEY=your-firebase-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-firebase-project-id
FIREBASE_APP_ID=your-firebase-app-id

# Filevine API Configuration
FILEVINE_CLIENT_ID=your-filevine-client-id
FILEVINE_CLIENT_SECRET=your-filevine-client-secret
FILEVINE_PERSONAL_ACCESS_TOKEN=your-filevine-pat
FILEVINE_ORG_ID=your-filevine-org-id
FILEVINE_USER_ID=your-filevine-user-id
```

### Firebase Setup

1. Create a Firebase project at https://console.firebase.google.com
2. Enable Authentication with Email/Password provider
3. Create a Firestore database
4. Generate a service account key and save as `rothbard-staging2-12345-firebase-adminsdk-fbsvc-7f95268383.json`
5. Configure Authentication settings for your web app
6. Set up Firestore security rules (provided in `firestore.rules`)

### Filevine API Setup

1. Obtain API credentials from your Filevine account
2. Create a Personal Access Token (PAT)
3. Note your Organization ID and User ID
4. Configure OAuth 2.0 client credentials

## Installation and Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd rothbard
   ```

2. **Create virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure environment variables**
   ```bash
   cp .env.example .env  # if available
   # Edit .env with your configuration
   ```

5. **Initialize Firebase**
   - Place your service account JSON file at `rothbard-staging2-12345-firebase-adminsdk-fbsvc-7f95268383.json`
   - Or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable

6. **Run the application**
   ```bash
   python app.py
   ```

   The application will be available at `http://localhost:5000`

## Usage

### For Users
1. Navigate to the application URL
2. Sign in using Firebase Authentication (email/password)
3. If not yet enabled, users will see a welcome page until an administrator enables their account
4. Once enabled, users can access their case dashboard showing:
   - All assigned projects/matters
   - Client information and contact details
   - Project metadata and links to Filevine

### For Administrators
1. User profiles are stored in Firestore at `users/{uid}`
2. Enable users by setting `enabled: true` and providing a `caseEmail`
3. The `caseEmail` field determines which projects the user can access
4. Admins can access the admin interface at `/admin/users` to manage all users
5. Admins can simulate other users' case access by entering their email in the simulation field on the dashboard

## Development Tools

### Generate Sample API Data
Use the provided utility to generate sample Filevine API responses:

```bash
python generate_sample.py
```

This will create JSON files in the `examples/` directory containing:
- Sample project forms (complaintInfo, newFileReview)
- Project tasks
- Project type phases
- Project team members

These samples are useful for development and testing without hitting the live API.

## Security Considerations

- All API communications use HTTPS
- Firebase ID tokens are verified server-side
- Sessions have limited duration (8 hours)
- User access is controlled through Firestore profiles
- Sensitive credentials are stored in environment variables
- Filevine API tokens are properly scoped and managed
- Firestore security rules restrict access to user's own profile
- Google Cloud Build and deployment use secure practices

## Future Enhancements

Planned improvements include:
- [ ] Firebase security rules hardening
- [ ] Terraform infrastructure as code for Firebase setup
- [ ] User-customizable dashboard columns
- [ ] Enhanced styling and responsive design
- [ ] Self-service user registration
- [ ] Administrative user management interface
- [ ] Real-time case updates
- [ ] Document upload/download capabilities
- [ ] Case status tracking and notifications

## Dependencies

- **Flask 3.0.3** - Web framework
- **firebase-admin 6.6.0** - Firebase server SDK
- **python-dotenv 1.0.1** - Environment variable management
- **requests 2.32.3** - HTTP client for API calls
- **itsdangerous 2.2.0** - Security utilities for Flask
- **gunicorn 23.0.0** - WSGI HTTP Server
- **pytz 2024.1** - Timezone library

## API Endpoints

### Internal Application Routes
- `GET /` - Home route (redirects based on auth status)
- `GET /login` - Firebase login page
- `POST /session_login` - Firebase ID token exchange
- `GET /logout` - Session termination
- `GET /welcome` - User onboarding page
- `GET /dashboard` - Main case dashboard (authenticated users only)
- `GET /admin/users` - Admin user management interface
- `GET /admin/users/<uid>` - Admin user detail view
- `POST /admin/users/update` - Update user information
- `POST /admin/users/create` - Create new user
- `POST /admin/users/<uid>/reset-password` - Reset user password

### Filevine API Integration
- Projects: `/fv-app/v2/Projects`
- Project Details: `/fv-app/v2/Projects/{id}`
- Project Team: `/fv-app/v2/Projects/{id}/team`
- Project Tasks: `/fv-app/v2/Projects/{id}/tasks`
- Project Forms: `/fv-app/v2/Projects/{id}/Forms/{form}`
- Project Contacts: `/fv-app/v2/projects/{id}/contacts`
- Client Info: `/fv-app/v2/contacts/{id}`

## License

This project is proprietary software for Rothbard Law Group.