/ README.md
README.md
1 # Meridian Studio 2 3 The operator interface for [Meridian](https://github.com/tvprasad/meridian) — a governed, enterprise RAG platform. Meridian Studio provides a browser-based interface for querying the knowledge base, running agentic workflows via the aiPolaris Planner → Retriever → Synthesizer DAG, ingesting documents, and managing configuration. 4 5 [](https://github.com/tvprasad/meridian-studio/actions/workflows/ci.yml) 6 [](https://github.com/tvprasad/meridian-studio/actions/workflows/azure-deploy.yml) 7 [](https://github.com/tvprasad/meridian-studio/releases) 8 [](https://react.dev) 9 [](https://www.typescriptlang.org) 10 [](https://vitejs.dev) 11 [](LICENSE) 12 [](ACCESSIBILITY.md) 13 [](ACCESSIBILITY.md) 14 15 --- 16 17 ## Overview 18 19 ### Core 20 21 | Page | Purpose | 22 |---|---| 23 | **Dashboard** | Live snapshot of pipeline status, document count, and active providers | 24 | **Ask Meridian** | Query interface with two modes: RAG Query (stateless, confidence-gated retrieval with citations and audit logging) and Agent Query (aiPolaris Planner → Retriever → Synthesizer DAG with per-node trace inspection and session context) | 25 | **AI Operations Agent** | ReAct reasoning agent with step-by-step tool execution timeline for complex operational queries against ServiceNow and internal knowledge | 26 | **Ingestion Pipeline** | Multi-stage document ingestion (Upload → Extract → Chunk → Embed → Index) with ServiceNow connector | 27 | **Evaluation** | Aggregate metrics dashboard (total queries, avg confidence, refusal rate, latency P50/P95) and paginated query log with sortable columns and filter dropdowns | 28 | **Settings** | Switch LLM/retrieval providers, adjust temperature, view connection details with copy-ready config snippets for Claude Desktop and Semantic Kernel | 29 30 ### Cognitive AI Services 31 32 | Page | Purpose | 33 |---|---| 34 | **Language Intelligence** | Sentiment analysis, entity recognition, key phrase extraction, and language detection | 35 | **Vision Intelligence** | Image analysis (caption, tags, objects) and OCR text extraction | 36 | **Speech Services** | Speech-to-text transcription and text-to-speech synthesis with voice selection | 37 | **Document Intelligence** | Structured data extraction from invoices, receipts, IDs, layouts, and more | 38 39 ### Cross-cutting Features 40 41 - **Authentication** — Azure AD/Entra ID via MSAL.js, gated by `VITE_AUTH_ENABLED` feature flag (off by default) 42 - **Dark mode** — toggle via sun/moon button in sidebar, persisted in localStorage 43 - **Collapsible sidebar** — pin/unpin with icon-only rail, expands on hover when unpinned 44 - **Landing page** — dark hero section with capability cards at `/welcome` 45 - **Offline banner** — automatic disconnect detection when API health check fails 46 - **Keyboard shortcuts** — Ctrl+K to focus input or start new chat, Escape to clear 47 48 ### Diagnostics & Governance 49 50 A collapsible right sidebar appears on all Cognitive AI Services pages, providing: 51 52 - **Diagnostics** — last API call status, latency, request ID, and estimated cost 53 - **Governance** — session totals: call count, cumulative cost estimate, and per-service usage breakdown 54 55 State is session-scoped (resets on page refresh) and tracked automatically via the `useTrackedMutation` hook. See [ADR-0002](adr/0002-diagnostics-governance-panel.md) for design rationale. 56 57 --- 58 59 ## Prerequisites 60 61 - **Node.js** 20+ 62 - **Meridian API** running at `http://localhost:8000` (see [meridian](https://github.com/tvprasad/meridian)) 63 64 --- 65 66 ## Getting Started 67 68 ```bash 69 # 1. Install dependencies 70 npm install 71 72 # 2. Configure environment 73 cp .env.example .env 74 # Edit .env — set VITE_API_BASE_URL and VITE_MCP_BASE_URL 75 76 # 3. Start dev server 77 npm run dev 78 ``` 79 80 The app will be available at `http://localhost:5173`. 81 82 --- 83 84 ## Environment Variables 85 86 | Variable | Default | Description | 87 |---|---|---| 88 | `VITE_API_BASE_URL` | `http://localhost:8000` | Meridian REST API base URL | 89 | `VITE_MCP_BASE_URL` | `http://localhost:8001` | Meridian MCP server base URL | 90 | `VITE_AIPOLARIS_URL` | `http://localhost:8002` | aiPolaris agent DAG base URL (ADR-011) | 91 | `VITE_AUTH_ENABLED` | `false` | Enable Azure AD authentication | 92 | `VITE_AZURE_CLIENT_ID` | — | Azure AD app registration client ID | 93 | `VITE_AZURE_TENANT_ID` | — | Azure AD tenant ID | 94 | `VITE_AZURE_REDIRECT_URI` | `window.location.origin` | Post-login redirect URI | 95 | `VITE_AZURE_API_SCOPE` | — | API scope (e.g., `api://meridian-api/.default`) | 96 97 --- 98 99 ## Authentication Setup 100 101 Authentication is **off by default**. When `VITE_AUTH_ENABLED=true`, Studio uses MSAL.js to authenticate users via Azure AD/Entra ID. The backend must also have `AUTH_ENABLED=true` (available since Meridian API v0.13.0). 102 103 ### 1. Register an Azure AD Application 104 105 1. Go to **Azure Portal** > **Microsoft Entra ID** > **App registrations** > **New registration** 106 2. **Name**: `meridian` 107 3. **Supported account types**: choose based on your needs: 108 - *Single tenant* — only users in your org directory (most secure for production) 109 - *Any Entra ID tenant + Personal Microsoft accounts* — allows personal accounts like `@gmail.com` (useful for dev) 110 4. **Redirect URI**: select **Single-page application (SPA)** and enter `http://localhost:5173` 111 5. Click **Register** 112 113 ### 2. Configure the Manifest (required for multi-tenant + personal accounts) 114 115 If you chose multi-tenant or personal accounts: 116 117 1. Go to **Manifest** in the left sidebar 118 2. Find `"accessTokenAcceptedVersion"` and change it from `null` to `2` 119 3. Click **Save** 120 4. Then set the supported account type under **Authentication** > **Supported accounts** 121 122 ### 3. Note Your IDs 123 124 From the app registration **Overview** page, copy: 125 126 - **Application (client) ID** — this is `VITE_AZURE_CLIENT_ID` 127 - **Directory (tenant) ID** — this is `VITE_AZURE_TENANT_ID` 128 129 ### 4. Add Production Redirect URI 130 131 Under **Authentication** > **Redirect URI configuration**, add your production domain: 132 133 - `https://studio.vplsolutions.com` (type: SPA) 134 135 ### 5. Update Environment Variables 136 137 ```env 138 VITE_AUTH_ENABLED=true 139 VITE_AZURE_CLIENT_ID=<your-client-id> 140 VITE_AZURE_TENANT_ID=<your-tenant-id> 141 VITE_AZURE_REDIRECT_URI=http://localhost:5173 142 # VITE_AZURE_API_SCOPE=api://meridian-api/.default 143 ``` 144 145 ### How It Works 146 147 - **Flag off (default)**: No MSAL code initializes. No login required. App behaves identically to pre-auth versions. 148 - **Flag on**: MSAL acquires tokens silently (from cache/refresh), falling back to Azure AD redirect login. All API calls include `Authorization: Bearer <token>`. Sidebar shows user profile with logout button. Protected routes redirect unauthenticated users to login. `/welcome` remains public. 149 150 See [ADR-0008](adr/0008-msal-authentication.md) for the full architectural decision. 151 152 --- 153 154 ## Scripts 155 156 | Command | Description | 157 |---|---| 158 | `npm run dev` | Start Vite dev server with HMR | 159 | `npm run build` | Type-check + production build | 160 | `npm run lint` | Run ESLint | 161 | `npm test` | Run Vitest contract and component tests | 162 | `npm run test:watch` | Run tests in watch mode | 163 | `npm run preview` | Preview production build locally | 164 165 --- 166 167 ## Tech Stack 168 169 - **React 19** + **TypeScript 5.9** (strict mode) 170 - **Vite 7** — build tooling and dev server 171 - **Tailwind CSS v4** — utility-first styling 172 - **React Router v7** — client-side routing 173 - **TanStack Query v5** — server state and caching 174 - **React Hook Form v7** + **Zod v4** — form validation 175 - **MSAL.js** (`@azure/msal-browser` + `@azure/msal-react`) — Azure AD authentication 176 - **Vitest** + **MSW** + **Testing Library** — contract and component tests 177 - **Lucide React** — icons 178 179 --- 180 181 ## Project Structure 182 183 ``` 184 src/ 185 ├── api/ # API client, Meridian + Azure AI type definitions 186 │ └── __tests__/ # API contract tests (Vitest + MSW) 187 ├── auth/ # MSAL.js authentication (provider, guard, token utility) 188 │ └── __tests__/ # Auth unit and integration tests 189 ├── __fixtures__/ # Real backend response fixtures for tests 190 ├── components/ 191 │ └── ui/ # Shared UI components (Layout, DiagnosticsPanel, …) 192 ├── hooks/ # Custom hooks (useDiagnostics, useTrackedMutation) 193 └── pages/ # Route-level page components 194 adr/ # Architecture decision records (ADR-0001 through ADR-0008) 195 ``` 196 197 --- 198 199 ## Testing 200 201 Contract tests verify that API mapping functions correctly transform backend responses. Fixtures in `src/__fixtures__/` come from real backend output. MSW intercepts at network level so the same `fetch` code runs in tests and production. 202 203 ```bash 204 npm test # run all tests 205 npm run test:watch # watch mode 206 ``` 207 208 See [ADR-0003](adr/0003-testing-framework.md) for the testing strategy. 209 210 --- 211 212 ## Related 213 214 - [meridian](https://github.com/tvprasad/meridian) — governed RAG control plane (backend) 215 - [meridian-infra](https://github.com/tvprasad/meridian-infra) — Terraform IaC for Azure deployment 216 - aiPolaris — agentic orchestration engine (Planner → Retriever → Synthesizer DAG, GCCH-ready) 217 218 --- 219 220 ## License 221 222 [MIT](LICENSE) © Prasad Thiriveedi 223 224 > Microsoft Azure, Amazon Web Services (AWS), and all other third-party product names are trademarks or registered trademarks of their respective owners. Their use here does not imply endorsement or affiliation.