Oliver-ai-bot_2.0/frontend

🚀 Enterprise AI Hub "Nexus" - Frontend

Next.js 14 frontend for the Enterprise AI Hub, featuring three powerful AI modes: RAG (knowledge base), Assistant (productivity tools), and Notebook (document analysis).

📋 Table of Contents

• Tech Stack
• Getting Started
• Project Structure
• Environment Variables
• Development
• Available Scripts
• API Integration
• Authentication Flow

---

🛠️ Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• Icons: Lucide React
• State Management: Zustand
• Data Fetching: TanStack Query (React Query)
• HTTP Client: Axios
• SSE Streaming: EventSource Polyfill

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Backend API running on http://localhost:8000
• Microsoft Entra ID (Azure AD) application configured

Installation

1. Install dependencies:

   npm install
   

2. Set up environment variables:

   cp .env.local.example .env.local
   

   Edit .env.local and add your configuration:

   NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
   NEXT_PUBLIC_ENTRA_CLIENT_ID=your_client_id
   NEXT_PUBLIC_ENTRA_TENANT_ID=your_tenant_id
   

3. Run the development server:

   npm run dev
   

4. Open your browser: Navigate to http://localhost:3000

---

📁 Project Structure

frontend/
├── app/                    # Next.js App Router pages
│   ├── layout.tsx         # Root layout
│   ├── page.tsx           # Home page
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   └── features/         # Feature-specific components
├── lib/                   # Utility functions
│   ├── api-client.ts     # Axios instance with interceptors
│   ├── auth.ts           # Authentication utilities
│   └── utils.ts          # General utilities (cn, etc.)
├── store/                 # Zustand stores
├── types/                 # TypeScript type definitions
│   └── index.ts          # API types matching backend
├── next.config.mjs       # Next.js configuration
├── tailwind.config.ts    # Tailwind CSS configuration
└── tsconfig.json         # TypeScript configuration

---

🔐 Environment Variables

Create a .env.local file with the following variables:

Required

Variable	Description	Example
NEXT_PUBLIC_API_URL	Backend API URL	http://localhost:8000/api/v1
NEXT_PUBLIC_ENTRA_CLIENT_ID	Microsoft Entra ID client ID	abc123...
NEXT_PUBLIC_ENTRA_TENANT_ID	Microsoft Entra ID tenant ID	def456...

Optional

Variable	Description	Default
NEXT_PUBLIC_ENTRA_REDIRECT_URI	OAuth redirect URI	http://localhost:3000/auth/callback
NEXT_PUBLIC_MAX_FILE_SIZE	Max file upload size (bytes)	104857600 (100MB)
NEXT_PUBLIC_NOTEBOOK_SESSION_EXPIRY_HOURS	Session expiry time	24

---

💻 Development

Adding a new page

Create a new folder in app/ with a page.tsx file:

// app/chat/page.tsx
export default function ChatPage() {
  return <div>Chat Page</div>;
}

Adding a shadcn/ui component

npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add card

Components will be added to components/ui/.

Creating a custom component

// components/features/ChatMessage.tsx
interface ChatMessageProps {
  content: string;
  role: 'user' | 'assistant';
}

export function ChatMessage({ content, role }: ChatMessageProps) {
  return (
    <div className={role === 'user' ? 'text-right' : 'text-left'}>
      <p>{content}</p>
    </div>
  );
}

---

📡 API Integration

Making API Calls

import apiClient from '@/lib/api-client';
import type { User } from '@/types';

// GET request
const { data } = await apiClient.get<User>('/auth/me');

// POST request
const { data } = await apiClient.post('/chat/conversations', {
  mode: 'rag',
  title: 'My Conversation'
});

SSE Streaming Example

const eventSource = new EventSource(
  `${process.env.NEXT_PUBLIC_API_URL}/chat/chat?conversation_id=${id}&message=${msg}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.token) {
    // Append token to response
  } else if (data.done) {
    eventSource.close();
  }
};

---

🔑 Authentication Flow

1. User clicks "Login with Microsoft"
2. Frontend redirects to Microsoft Entra ID
3. User authenticates with Microsoft
4. Microsoft redirects back with authorization code
5. Frontend sends code to backend (POST /auth/login)
6. Backend returns JWT tokens + user data
7. Frontend stores tokens in localStorage
8. All subsequent requests include JWT in Authorization header

Token Refresh

The API client automatically refreshes expired access tokens:

• Access token expires in 15 minutes
• Refresh token expires in 7 days
• On 401 error, client automatically requests new access token
• If refresh fails, user is redirected to login

---

📜 Available Scripts

Command	Description
npm run dev	Start development server (http://localhost:3000)
npm run build	Build production bundle
npm run start	Start production server
npm run lint	Run ESLint
npm run type-check	Run TypeScript type checking

---

🎨 Styling Guidelines

Using Tailwind CSS

<div className="flex items-center gap-4 p-6 bg-white rounded-lg shadow-md">
  <h1 className="text-2xl font-bold text-gray-900">Hello</h1>
</div>

Using cn() utility

Combine classes with clsx and tailwind-merge:

import { cn } from '@/lib/utils';

<button className={cn(
  'px-4 py-2 rounded-md',
  isPrimary && 'bg-blue-500 text-white',
  isDisabled && 'opacity-50 cursor-not-allowed'
)}>
  Click me
</button>

---

🧪 Testing API Endpoints

Use the backend Swagger UI for testing:

• Local: http://localhost:8000/docs
• API Base URL: http://localhost:8000/api/v1

---

📚 Additional Resources

• Next.js Documentation
• shadcn/ui Documentation
• TanStack Query Documentation
• Backend API Documentation

---

🐛 Troubleshooting

Port 3000 already in use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

API requests failing (CORS)

• Ensure backend is running on port 8000
• Check next.config.mjs proxy configuration
• Verify NEXT_PUBLIC_API_URL in .env.local

Authentication not working

• Check Microsoft Entra ID configuration
• Verify NEXT_PUBLIC_ENTRA_CLIENT_ID and NEXT_PUBLIC_ENTRA_TENANT_ID
• Clear localStorage and try again

---

📝 Notes

• This is Phase 6 of the implementation
• Backend API is complete and documented
• Frontend foundation is set up, ready for page development
• Authentication flow uses Microsoft Entra ID (OAuth2)

---

Status: ✅ Foundation Complete - Ready for UI Development

Last Updated: 2026-02-12