1  # Meridian Studio — Project Context
 2  
 3  ## What is this?
 4  React frontend for the Meridian RAG knowledge engine. Provides a Query console, AI Operations Agent (ReAct reasoning), Ingestion Pipeline (document chunking, embedding, indexing), Cognitive AI Services (Language, Vision, Speech, Document Intelligence), and a Settings page.
 5  
 6  ## Tech Stack
 7  - **Framework**: React 19 + TypeScript + Vite 7
 8  - **Styling**: Tailwind CSS v4
 9  - **State**: TanStack React Query v5
10  - **Routing**: React Router v7
11  - **Testing**: Vitest + MSW + Testing Library (ADR-0003)
12  - **CI**: GitHub Actions (lint → test → build)
13  
14  ## Architecture
15  - `src/api/client.ts` — shared fetch wrapper with 30s timeout (AbortController)
16  - `src/api/meridian.ts` — Meridian API + MCP server calls (port 8000 / 8001)
17  - `src/api/azure-ai.ts` — Azure Cognitive AI Services calls
18  - `src/hooks/` — DiagnosticsContext, DiagnosticsProvider, useDiagnostics, useTrackedMutation
19  - `src/pages/` — one component per route
20  - `src/__fixtures__/` — real backend response fixtures for contract tests
21  - `adr/` — architecture decision records (0001–0007)
22  
23  ## Backends
24  | Service | Default URL | Purpose |
25  |---------|-------------|---------|
26  | Meridian API | `http://localhost:8000` | RAG engine (health, settings, upload, agent) |
27  | MCP Server | `http://localhost:8001` | Tool calls (query_knowledge_base) |
28  
29  The MCP `tools/call` endpoint expects: `{ name: "query_knowledge_base", arguments: { question } }`
30  
31  ## Conventions
32  
33  ### Commits
34  - Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `test:`
35  - Always end with `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`
36  - Update CHANGELOG.md under `[Unreleased]` in every commit with code changes
37  
38  ### Before declaring any task done
39  Run `/verify`. No exceptions. Re-reads changed files, runs tests (`npm test`), checks for secrets. Only report done after VERDICT: READY TO SHIP.
40  
41  ### Before every commit
42  1. `npm run lint` — 0 errors (warnings OK)
43  2. `npm test` — all tests pass
44  3. `npm run build` — TypeScript + Vite build clean
45  4. CHANGELOG.md updated
46  5. ADR written for architectural decisions
47  
48  ### After every commit (mandatory)
49  1. Determine version bump from commit prefix: `fix:` = patch, `feat:` = minor, breaking change = major
50  2. Move `[Unreleased]` entries in CHANGELOG.md to new `[x.y.z] — YYYY-MM-DD` section
51  3. Add fresh empty `[Unreleased]` section above
52  4. Update CHANGELOG comparison links at bottom of file
53  5. Commit: `chore: release vX.Y.Z`
54  6. Tag: `git tag vX.Y.Z`
55  7. Push: `git push && git push origin vX.Y.Z`
56  
57  This is enforced by a `postToolUse` hook on `git commit`. Never skip tagging.
58  
59  ### Code style
60  - Prefer "Cognitive AI Services" (not "Azure AI Services")
61  - No emojis in code or docs unless explicitly asked
62  - Keep files focused — components, hooks, and context in separate files
63  - API response fixtures come from real curl/backend output
64  - Never hardcode version strings — import `version` from `package.json` (single source of truth)
65  
66  ### Testing (ADR-0003)
67  - Every API mapping function gets a contract test
68  - Fixtures in `src/__fixtures__/` from real backend responses
69  - MSW intercepts at network level — same fetch code runs in tests and production
70  - Tests must pass in CI before merge
71  
72  ## Related repos
73  - `s:\Dev\meridian` — Python backend (uvicorn api.main:app)
74  - `s:\Dev\meridian-infra` — Terraform IaC for Azure
75  - `s:\Dev\meridian-mcp` — MCP server
76  
77  ## Azure Resources (meridian-rg)
78  - ACR: `meridian.azurecr.io`
79  - Container Apps: `meridian-studio`, `meridian-api`, `meridian-mcp`
80  - Cognitive Services: meridian-language, meridian-speech, meridian-vision-app, meridian-docintel-formrecognizer, meridian-openai, meridian-llm
81  - Azure AI Search: `meridian-search-tvp`
82  - Azure SQL: `meridian-db` (serverless GP_S_Gen5, westus2)