AI Ticketing Assistant

Internal help-desk assistant that answers REDCap questions. The project consists of:

• backend/ – FastAPI service that calls Azure OpenAI and streams responses with Server-Sent Events.
• ai-ticketing-app/ – React SPA (Vite) that renders the chat console with real-time streaming.
• sample_data.txt – Local knowledge base supplied to each request.
• sampleFAQScript.py – Helper script for rebuilding the knowledge base from REDCap exports.

Quick Start

Backend

1. Create and activate a Python 3.10+ virtual environment.
2. Install dependencies:

   python -m pip install -r requirements.txt

3. Configure environment variables: Inside backend/, duplicate the environment template:

   cp backend/.env.template backend/.env

   Then open backend/.env and add your Azure OpenAI credentials
4. Run the API:

   python -m uvicorn main:app --reload --app-dir backend

Frontend

Open a new terminal

1. Install dependencies:

   cd ai-ticketing-app
   npm install

2. Start the dev server:

   npm run dev

Features

• Real-time streaming responses – Responses stream incrementally using Server-Sent Events (SSE)
• Multi-turn conversations – Maintains conversation context across multiple exchanges
• Conversation persistence – Saves conversation history to browser localStorage
• Enhanced UI/UX – Modern, responsive design with dark/light mode toggle, clean typography, spacing, and smooth animation.
• Azure OpenAI integration – Uses Azure OpenAI API with LangChain for LLM interactions
• Knowledge base – Answers questions based on REDCap and Dataverse documentation

Testing

The project includes a comprehensive test suite with 52+ tests across 7 test suites. Tests automatically start services if needed.

Quick Test Run

First-time setup required: Before running tests, ensure you've completed the setup steps:

1. Backend: Python virtual environment, dependencies installed, .env file configured
2. Frontend: Dependencies installed (cd ai-ticketing-app && npm install)
3. Test dependencies: Puppeteer installed (npm install puppeteer in project root)
4. Setup test scripts: Run npm run setup to add test scripts to package.json (if not already present)

See tests/README.md for detailed setup instructions.

# Run all tests (auto-starts services)
npm test

# Run specific test suites
npm run test:backend      # Backend API tests
npm run test:frontend     # Frontend UI tests (requires Puppeteer)
npm run test:integration  # Integration tests
npm run test:edge         # Edge cases
npm run test:performance  # Performance tests
npm run test:security     # Security tests
npm run test:browser      # Browser compatibility

Important: When running individual test suites (e.g., npm run test:frontend or npm run test:integration), you must manually start the backend and frontend services first. Only npm test (which runs all tests) automatically starts services.

To start services manually:

# Terminal 1 - Backend:
uvicorn main:app --reload --app-dir backend --host 0.0.0.0 --port 8000

# Terminal 2 - Frontend:
cd ai-ticketing-app && npm run dev

# Or use helper script (runs in background):
bash tests/start_services.sh

Test Coverage

• Backend API (9 tests): Endpoints, validation, streaming, CORS, error handling
• Frontend UI (12 tests): User interactions, components, state management
• Integration (5 tests): End-to-end flows, conversation context
• Edge Cases (9 tests): Unusual inputs, boundary conditions
• Performance (5 tests): Response times, throughput
• Security (7 tests): Vulnerability testing, input validation
• Browser Compatibility (5 tests): Cross-browser checks

For detailed testing documentation and troubleshooting, see tests/README.md.

Development Notes

• Azure OpenAI's built-in policies handle safety.
• Streaming keeps the UI responsive while responses are generated.
• Tests use cross-platform compatible methods (works on macOS, Linux, Windows/WSL).