---
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
- status/active
- tech/azure-ad
- tech/docker
- tech/flask
- tech/python
- tech/react
- tech/typescript
- type/sop
type: sop
---

# Oliver Agency Reporting Module - Developer Manual

## Architecture Overview
The application is a **Full-Stack Web App** with:
- **Frontend**: React 18 + Vite, styled with CSS, using Azure MSAL for authentication.
- **Backend**: Python Flask API running on a separate port (default 5001).
- **Data Source**: External Make.com Webhook providing JSON data.
- **Deployment**: Configurable base path and domain via environment variables.

The frontend communicates with the backend, which likely fetches or proxies data from the Make.com webhook. Authentication is handled via Azure AD (MSAL).

## Tech Stack
- **Frontend**: React, Vite, `@azure/msal-react`, `@azure/msal-browser`, Recharts (for graphs), date-fns.
- **Backend**: Python 3, Flask.
- **Authentication**: Azure Active Directory (OAuth2/OIDC).
- **Data Processing**: Client-side aggregation using `userAggregation.js`.

## Local Setup

### Prerequisites
- Node.js (v18+)
- Python 3.8+
- Make.com Account (for webhook data)
- Azure AD App Registration

### 1. Clone and Configure
```bash
git clone <repo-url>
cd Oliver-Agency-Reporting-Module
cp .env.example .env
```

Edit `.env` with your:
- `DOMAIN`
- `BASE_PATH`
- `AZURE_TENANT_ID`
- `AZURE_CLIENT_ID`
- `MAKE_WEBHOOK_URL`

### 2. Backend Setup
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Load env vars and start server
set -a && source ../.env && set +a
python app.py
```
Backend runs on `http://localhost:5001`.

### 3. Frontend Setup
```bash
cd frontend
npm install
npm run dev
```
Frontend runs on `http://localhost:5173`.

### 4. Quick Start (Alternative)
Run `./run.sh` from the root directory to start both servers simultaneously.

## Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `DOMAIN` | Deployment domain (e.g., `example.com`) | Yes |
| `BASE_PATH` | App base path (e.g., `/dashboard/`) | Yes |
| `AZURE_TENANT_ID` | Azure AD Tenant ID | Yes |
| `AZURE_CLIENT_ID` | Azure AD Client ID | Yes |
| `BACKEND_PORT` | Flask server port | No (default: 5001) |
| `MAKE_WEBHOOK_URL` | Source data webhook URL | Yes |
| `VITE_*` | Frontend build-time variables mirroring above | Yes |
| `VITE_REDIRECT_URI` | Azure AD redirect URI (Production) | Yes |
| `VITE_REDIRECT_URI_DEV` | Azure AD redirect URI (Dev) | Yes |

## Key Services & Entry Points

### Frontend Entry: `frontend/src/main.jsx`
- Initializes MSAL instance.
- Handles redirect promise for auth flow.
- Renders `<MsalProvider>` wrapping `<App>`.

### Auth Config: `frontend/src/authConfig.ts`
- Defines `msalConfig` (clientId, tenantId, scopes).
- Defines `loginRequest` scopes (e.g., `User.Read`).

### Dashboard Logic: `frontend/src/components/Dashboard.jsx`
- Manages state for filters (organization, user, assistant, dateRange).
- Fetches data (implied via props or API calls not fully shown in snippet, but likely from backend).
- Filters `conversations` and `messages` arrays.

### Data Aggregation: `frontend/src/utils/userAggregation.js`
- `aggregateMessagesByUser(filteredMessages, processedUserData)`: Aggregates message counts per user.

### Authentication Components
- `LoginComponent.jsx`: Handles popup login via `instance.loginPopup()`.
- `AuthenticatedApp.jsx`: Renders main dashboard after auth.

## API Reference
*Note: Specific API endpoints are not fully visible in the provided snippets, but the backend (`app.py`) likely exposes:
- `GET /api/data`: Fetches conversation/message data from Make.com webhook.
- `POST /api/...`: If any write operations exist.

The frontend likely calls an internal proxy endpoint (e.g., `/api/data`) which forwards to `MAKE_WEBHOOK_URL`.*

## Deployment
1. **Build Frontend**: `npm run build`.
2. **Configure Web Server**: Ensure your web server (Nginx, Apache, or static host) serves the `dist` folder.
3. **Base Path**: Ensure the web server routes all requests to `index.html` for SPA routing (e.g., `/dashboard/...`).
4. **Azure AD**: Ensure `VITE_REDIRECT_URI` matches the Azure Portal redirect URI exactly.
5. **Backend**: Deploy Flask app (e.g., via Gunicorn) on the specified `BACKEND_PORT`.

## Known Gotchas
1. **Azure AD Redirect URIs**: Must match exactly. Dev uses `http://localhost:5173`, Prod uses `https://yourdomain.com/dashboard/`.
2. **Date Formatting**: Use `date-fns` for consistent ISO formatting. Avoid native `Date` parsing for complex ranges.
3. **CORS**: Backend must allow CORS from the frontend domain.
4. **Webhook Latency**: Make.com webhooks can have delay. Cache data appropriately if performance is an issue.
5. **CSV Export**: Large datasets may cause browser memory issues during client-side CSV generation. Consider server-side export for large volumes.
6. **Path Trailing Slashes**: Ensure `BASE_PATH` ends with `/` as per config requirements.

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