---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/ai
- domain/security
- tech/azure-ad
- tech/react
- tech/typescript
- type/reference
type: reference
---

# APAC Ops Bot - Developer Manual

## Architecture Overview
The APAC Ops Bot is a modern web application built with React for the frontend and a separate backend API (not shown in codebase snippets but implied by service calls). It uses React Context for state management and MSAL for authentication.

```
[Browser] --> [React Frontend] --> [Backend API] --> [Database/LLM Provider]
                 |
                 +-- MSAL Browser (Auth)
                 +-- Contexts (Auth, Chat)
```

## Tech Stack
- **Frontend**: React 18, TypeScript, React Router DOM
- **Authentication**: Microsoft Authentication Library (MSAL) for Azure AD, plus fallback simple login.
- **State Management**: React Context API (`AuthContext`, `ChatContext`)
- **Styling**: CSS Modules/Global CSS (`styles/global.css`, etc.)
- **UI Components**: Custom React components with `react-markdown` and `react-syntax-highlighter`

## Local Setup

### Prerequisites
- Node.js (v16+)
- npm or yarn
- Access to the repository and backend API credentials

### Installation
1. Clone the repository.
2. Navigate to the frontend directory:
   ```bash
   cd apac-ops-bot/frontend
   ```
3. Install dependencies:
   ```bash
   npm install
   ```

### Running the Application
```bash
npm start
```
The app will launch at `http://localhost:3000`.

## Environment Variables
The following environment variables are required in `.env`:

| Variable | Description | Required |
|----------|-------------|----------|
| `REACT_APP_AZURE_CLIENT_ID` | Azure AD App Registration Client ID | Conditional (if using MSAL) |
| `REACT_APP_AZURE_TENANT_ID` | Azure AD Tenant ID | Conditional (if using MSAL) |
| `REACT_APP_API_URL` | Base URL for the backend API | Yes |

**Note**: If `REACT_APP_AZURE_CLIENT_ID` is not set or is the placeholder `your-client-id-here`, the app will fall back to simple login mode.

## Key Services & Entry Points

### Entry Point
- `src/index.tsx`: Initializes the React app and mounts `<App />`.

### Contexts
- **`src/context/AuthContext.tsx`**:
  - Manages user authentication state.
  - Initializes MSAL if configured.
  - Handles login/logout and session validation.
  - Exports `AuthProvider` and `useAuth` hook.

- **`src/context/ChatContext.tsx`**:
  - Manages chat state: conversations, messages, loading/error states.
  - Interfaces with backend via `conversationAPI` and `messageAPI`.
  - Exports `ChatProvider` and `useChat` hook.

### Components
- **`src/App.tsx`**: Root component handling routing, auth gating, and layout (sidebar/header).
- **`src/components/SimpleLogin.tsx`**: Login form for non-Azure users.
- **`src/components/ChatInterface.tsx`**: Main chat view, handles message sending, markdown rendering, and copy functionality.
- **`src/components/ChatList.tsx`**: Sidebar with conversation list, CRUD operations.
- **`src/components/AdminPanel.tsx`**: Admin dashboard for user management.
- **`src/components/TokenUsageDashboard.tsx`**: Displays token usage metrics.

### Services
- **`src/services/api.ts`**: Axios/-fetch wrappers for backend API calls.
- **`src/services/authConfig.ts`**: MSAL configuration constants.

## API Reference (Frontend Perspective)

### Auth API
- `POST /api/auth/login`: Login user.
- `POST /api/auth/logout`: Logout user.
- `GET /api/auth/me`: Get current user details.

### Chat API
- `GET /api/conversations`: List user conversations.
- `POST /api/conversations`: Create a new conversation.
- `GET /api/conversations/:id`: Get conversation details.
- `PUT /api/conversations/:id/title`: Update title.
- `DELETE /api/conversations/:id`: Delete conversation.
- `POST /api/conversations/:id/archive`: Archive conversation.
- `POST /api/messages`: Send a message and get response.
- `GET /api/messages?conversation_id=:id`: Get messages for a conversation.

### Admin API
- `GET /api/admin/users`: List all users.
- `PUT /api/admin/users/:id/role`: Update user role.
- `GET /api/admin/usage`: Get token usage statistics.

## Deployment
1. Build the frontend:
   ```bash
   npm run build
   ```
2. Serve the `build/` directory using a web server (Nginx, Apache, or any static file host).
3. Ensure the backend API is deployed and CORS is configured for the frontend domain.
4. Set environment variables on the server or via build process.

## Known Gotchas
- **MSAL Initialization**: MSAL only initializes if Azure AD credentials are provided. Otherwise, simple login is used.
- **Session Timeout**: The `AuthContext` checks for a valid token on load. If invalid, it clears local storage and redirects to login.
- **Chat State Clearing**: Chat state is cleared when the user logs out or switches accounts to prevent data leakage.
- **Markdown Rendering**: The `cleanMarkdown` function in `ChatInterface` attempts to standardize newlines for better rendering. Custom markdown parsers may behave differently.
- **Clipboard Permissions**: In some browsers/iframes, `navigator.clipboard` may fail. The app falls back to `document.execCommand('copy')`.
- **Sidebar Toggle**: The sidebar state is local to `AppContent`. Refreshing the page resets it to open.

## Related
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/baic_dashboard/DEVELOPER_MANUAL.md]]
- [[01 Projects/APAC ops Bot/DEVELOPER_MANUAL.md]]
- [[01 Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL.md]]