# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

```bash
# Environment setup
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Development server (runs on http://localhost:5000)
python app.py

# Generate sample Filevine API responses for development/testing
python generate_sample.py
```

## Architecture Overview

This is a Flask-based client portal for Rothbard Law Group that provides secure access to Filevine case management data. The application uses a server-side rendered architecture with Firebase Authentication and integrates with the Filevine API.

### Core Authentication Flow
1. **Client-side**: Firebase Authentication (email/password) in login.html
2. **Server-side**: ID token verification and session creation in `/session_login`
3. **Session Management**: Flask sessions with 8-hour expiration
4. **Access Control**: User profiles in Firestore (`users/{uid}`) control access via `enabled` and `caseEmail` fields

### Key Architecture Components

**Flask Application (`app.py`)**
- Main application server with authentication, session management, and Filevine API integration
- Implements role-based access control through Firestore user profiles
- Contains all Filevine API integration functions with OAuth 2.0 authentication

**Template System**
- Jinja2 templates with Tailwind CSS for styling
- `base.html`: Navigation and layout foundation
- `login.html`: Firebase authentication interface
- `dashboard.html`: Main case data display table
- `welcome.html`: Onboarding for non-enabled users

**Filevine API Integration**
- OAuth 2.0 using Personal Access Token for authentication
- Key functions: `get_filevine_bearer()`, `list_all_projects()`, `fetch_project_detail()`, `fetch_client()`, `fetch_contacts()`
- Projects filtered by user's assigned `caseEmail` from Firestore profile

**User Management**
- User profiles stored in Firestore at `users/{uid}` with fields:
  - `enabled`: Boolean for access control
  - `caseEmail`: Determines which Filevine projects user can access
- Users see welcome page until enabled by administrator

## Configuration Requirements

**Environment Variables (.env)**
- Flask: `FLASK_SECRET_KEY`
- Firebase: `FIREBASE_API_KEY`, `FIREBASE_AUTH_DOMAIN`, `FIREBASE_PROJECT_ID`, `FIREBASE_APP_ID`
- Firebase Admin: `FIREBASE_SERVICE_ACCOUNT_JSON` or `GOOGLE_APPLICATION_CREDENTIALS`
- Filevine API: `FILEVINE_CLIENT_ID`, `FILEVINE_CLIENT_SECRET`, `FILEVINE_PERSONAL_ACCESS_TOKEN`, `FILEVINE_ORG_ID`, `FILEVINE_USER_ID`

**Firebase Setup**
- Service account credentials file: `rothbard-service-account.json`
- Firestore database for user profiles
- Firebase Authentication with email/password provider

## Development Tools

**Sample Data Generation**
- `generate_sample.py` creates sample Filevine API responses in `examples/` directory
- Useful for development without hitting live API
- Generates project lists, contacts, and client information samples

## Key Implementation Details

**Session Management**
- Sessions include `uid` and `expires_at`
- Automatic redirects based on user enablement status
- `login_required` decorator protects authenticated routes

**API Data Flow**
1. Dashboard fetches Filevine bearer token using OAuth 2.0
2. Lists all projects with pagination support
3. Filters projects by user's `caseEmail`
4. Fetches detailed data for each project (client info, contacts)
5. Renders data in responsive table format

**Security Implementation**
- Firebase ID tokens verified server-side
- All API communications use HTTPS
- Sensitive credentials stored in environment variables
- User access controlled through Firestore profiles
- Filevine API tokens properly scoped and managed