netflix/DEVELOPMENT.md

Netflix GraphRAG Development Guide

Authentication Bypass for Local Development

The application has been configured to bypass Microsoft authentication (MSAL) when running in development mode. This makes local development easier by:

1. Skipping the Microsoft login screen entirely
2. Automatically using a development user (dev_user@local)
3. Allowing backend API requests without MSAL tokens
4. Providing mock responses when the backend is unavailable

How to Run in Development Mode

Frontend

To run the frontend in development mode with auth bypass:

cd chat-interface
./dev.sh

Or manually:

cd chat-interface
npm run dev

Make sure the .env.development file exists with:

VITE_NODE_ENV=development
VITE_MODE=development

Backend

The backend automatically detects development mode and accepts requests with the username dev_user@local when the PRODUCTION flag is set to False.

For example:

# In routes.py
if not PRODUCTION and (not username or username == ""):
    username = "dev_user@local"

How Authentication Bypass Works

Frontend

1. In main.jsx:

   • The application checks for development mode using import.meta.env
   • In development mode, MSAL initialization is skipped
   • The application renders immediately without showing the login screen

2. In auth.js:

   • The getCurrentUser() function returns dev_user@local in development mode
   • The isAuthenticated() function always returns true in development mode
   • The initializeMSAL() function skips MSAL initialization in development mode

3. In App.jsx:

   • All API requests include the X-MS-USERNAME header with dev_user@local
   • In development mode, the application can work without a backend connection
   • It provides mock responses for chat messages and mock conversations
   • JSON parsing errors are caught and handled gracefully

Development-Only Features

The frontend includes several development-specific features:

1. Mock Chat Interface:

   • In development mode, the chat interface works without needing a backend
   • User messages get mock responses based on their content
   • Sources and reasoning information are simulated

2. Mock Conversations:

   • Development mode creates sample conversations automatically
   • No need to set up a database or backend service

3. Error Resilience:

   • All backend API calls are wrapped with development fallbacks
   • Even if API requests fail or return invalid JSON, the UI continues working
   • Clear console logging shows when development mode is active

Backend Development

The backend automatically detects development mode and accepts requests with the username dev_user@local.

1. In routes.py:

   • API endpoints check for the PRODUCTION flag
   • In development mode, if no username is provided, dev_user@local is used
   • Authentication validation is bypassed for this development user

2. In environment configuration:

   • The .env file contains API keys and other sensitive information
   • These are loaded using dotenv in config.py

Troubleshooting

If you're still seeing the login screen in development mode:

1. Check that the .env.development file exists in the chat-interface directory
2. Verify that you're running with npm run dev or the provided dev.sh script
3. Look at the browser console for any errors or authentication messages
4. If needed, clear browser cache and localStorage

If the chat interface shows errors connecting to the backend:

1. The application should still work in development mode without a backend
2. Check console logs for "Development mode" messages to confirm it's running in dev mode
3. If needed, restart the development server

API Testing

When testing backend APIs directly, include the development username in requests:

curl -X POST http://localhost:5000/chat \
  -H "Content-Type: application/json" \
  -H "X-MS-USERNAME: dev_user@local" \
  -d '{"message": "Hello", "sessionId": "your_session_id"}'

Running Without Backend

The frontend is now configured to run independently in development mode, even if the backend is not available. This is useful for:

1. UI development without setting up the full backend stack
2. Testing the chat interface flow without a working backend API
3. Demonstrating the UI to stakeholders without backend dependencies

In this mode, all chat messages will receive simulated responses, and the conversation history will be populated with mock data.