INTEGRATION_GUIDE.md

FinSight Frontend-Backend-Models Integration Guide

This document describes the integration between the Frontend, Backend, and Models services in the FinSight application.

Architecture Overview

The FinSight application consists of three main services:

1. Frontend (React + Vite) - Runs on port 5173
2. Backend (Django REST Framework) - Runs on port 8000
3. Models (FastAPI) - Runs on port 8001

Service Communication

Frontend ↔ Backend

The frontend communicates with the backend via REST APIs for:

• User authentication (register, login, OTP verification)
• Chat message storage
• Data ingestion

Base URL: http://localhost:8000

Frontend ↔ Models

The frontend communicates directly with the models service for:

• Audio transcription
• Text processing (PII filtering and structured output)

Base URL: http://localhost:8001

API Integration

Authentication Flow

1. Sign Up (POST /api/auth/register/)

   • Registers a new user
   • Automatically sends OTP to user's email

2. OTP Verification (POST /api/auth/verify-otp/)

   • Verifies the OTP sent to user's email
   • Marks email as verified

3. Sign In (POST /api/auth/login/)

   • Authenticates user with email/username and password
   • Returns JWT access and refresh tokens
   • Requires verified email

4. Get User Profile (GET /api/auth/me/)

   • Retrieves current user information
   • Requires JWT authentication

Feature Integrations

1. Chatbot (POST /api/chat/message/)

• Stores user messages in encrypted format
• Requires JWT authentication
• Located at: /chatbot route

2. Audio Transcription (POST /transcribe)

• Transcribes audio files (.wav, .mp3) to text
• Communicates with Models service (port 8001)
• Located at: /transcribe route

3. Text Processing (POST /filtertext/process)

• Processes transcript text through PII filtering pipeline
• Generates structured output
• Communicates with Models service (port 8001)
• Located at: /process-text route

4. Data Ingestion (POST /api/ai/ingest/)

• Ingests confidential and non-confidential data
• Stores data in encrypted format
• Requires JWT authentication
• Located at: /data-ingest route

API Client

The frontend uses a centralized API client (/frontend/src/utils/api.js) that provides:

• backendAPI - Functions for backend communication
• modelsAPI - Functions for models service communication

Authentication Management

JWT tokens are managed through:

• AuthContext - Provides authentication state and functions
• localStorage - Stores access and refresh tokens
• Protected routes use ProtectedRoute component

Running the Application

Prerequisites

Ensure all three services are running:

1. Backend Server (Port 8000)

   cd backend
   python manage.py runserver 8000
   

2. Models Server (Port 8001)

   cd models
   uvicorn app:app --host 0.0.0.0 --port 8001
   

   Note: The app.py file has port 8000 hardcoded. Use the uvicorn command above to override it.

3. Frontend Server (Port 5173)

   cd frontend
   npm run dev
   

Access Points

• Landing Page: http://localhost:5173/
• Sign In: http://localhost:5173/signin
• Sign Up: http://localhost:5173/signup
• Dashboard: http://localhost:5173/dashboard (requires authentication)

Routes

Public Routes

• / - Landing page
• /signin - Sign in page
• /signup - Sign up page
• /verify-otp - OTP verification page

Protected Routes (Require Authentication)

• /dashboard - Main dashboard with feature access
• /chatbot - AI chatbot interface
• /transcribe - Audio transcription interface
• /process-text - Text processing interface
• /data-ingest - Data ingestion interface

API Response Format

Backend Responses

All backend endpoints return responses in this format:

Success:

{
  "success": true,
  "data": { /* response data */ },
  "error": null
}

Error:

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Models Service Responses

Models endpoints return direct JSON responses without the success wrapper.

CORS Configuration

• Backend has CORS enabled for all origins (CORS_ALLOW_ALL_ORIGINS = True)
• Models service allows origins from environment variable ALLOWED_ORIGINS

Environment Variables

Backend

• DJANGO_SECRET_KEY - Django secret key
• DJANGO_DEBUG - Debug mode
• GOOGLE_CLIENT_ID - Google OAuth client ID
• FIELD_ENCRYPTION_KEY - Encryption key for sensitive data

Models

• GROQ_API_KEY - Groq API key for transcription
• BACKBOARD_API_KEY - Backboard API key for text processing
• ALLOWED_ORIGINS - Allowed CORS origins

Security

• JWT tokens are used for authentication
• Sensitive data is encrypted before storage
• Protected routes require valid JWT tokens
• Tokens are stored in localStorage
• Email verification is required before login

Testing Integration

You can test the integration using curl:

Test Backend Health

curl http://localhost:8000/api/auth/me/

Test Models Health

curl http://localhost:8001/health

Test Frontend

Navigate to http://localhost:5173 in your browser.

Troubleshooting

1. CORS Errors: Ensure all services are running on their designated ports
2. Authentication Errors: Check that JWT tokens are valid and not expired
3. Connection Refused: Verify that all services are running
4. OTP Not Received: Check email configuration in Django settings

Future Enhancements

• Add real-time chat using WebSockets
• Implement token refresh mechanism
• Add file upload progress indicators
• Enhance error handling and user feedback
• Add comprehensive testing suite