Add comprehensive documentation and project setup guide

- Expand README.md with detailed architecture overview, configuration guide, and usage instructions - Add CLAUDE.md with development commands and implementation details for Claude Code assistance - Document authentication flow, API integration, and security considerations - Include setup instructions for Firebase, Filevine API, and local development environment - Add project structure documentation and future enhancement roadmap 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-27 15:21:38 -07:00
parent 2383d1ad9a
commit 2b5bef1a28
2 changed files with 316 additions and 15 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,94 @@
+# 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
--- a/README.md
+++ b/README.md
@@ -1,19 +1,226 @@
-Rothbard Client Portal
+# Rothbard Client Portal

-This is a server-side rendered client portal for rothbard law group. Users can log in, and once they've been configured, can see a list of cases from the filevine API.
+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.

-Todo list
-* Lock down firebase
-* Set firebase up with terraform
-* Allow users to store their preferences on which columns they see
-* Styling
-* New user sign up
-* Set up users
+## 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

-Project Structure:
-* static/ - static assets, html, javascript etc
-* templates/ jinja templates
-* app.py - core login
-* examples/ sample filevine api requests/responses for digging into
-* generate_sample.py - generates the examples
+## 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
+├── 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
+├── examples/            # Sample Filevine API responses
+│   ├── project_list.json
+│   ├── project_contacts.json
+│   └── client.json
+└── .env                 # Environment variables (not tracked)
+```
+
+## 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)
+
+### 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
+
+### 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
+
+## Configuration
+
+### Required Environment Variables
+
+Create a `.env` file with the following variables:
+
+```bash
+# Flask Configuration
+FLASK_SECRET_KEY=your-secret-key-here
+
+# Firebase Configuration
+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
+FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'  # or set GOOGLE_APPLICATION_CREDENTIALS
+
+# 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-service-account.json`
+5. Configure Authentication settings for your web app
+
+### 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-service-account.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
+
+## 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 lists
+- Project contacts
+- Client information
+
+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
+
+## 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
+
+## 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)
+
+### Filevine API Integration
+- Projects: `/fv-app/v2/Projects`
+- Project Details: `/fv-app/v2/Projects/{id}`
+- Contacts: `/fv-app/v2/projects/{id}/contacts`
+- Client Info: `/fv-app/v2/contacts/{id}`
+
+## License
+
+This project is proprietary software for Rothbard Law Group.