# paulgoffin802/project_marlin architecture

> Architecture diagram of the GitHub repository paulgoffin802/project_marlin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paulgoffin802/project_marlin
- Repository: https://github.com/paulgoffin802/project_marlin

## Overview

Marlin combines a Rayfin-hosted programme-data model and React app with a separately deployed, Entra-protected MCP service. The main user-to-result path is an MCP caller submitting a read-only search request, passing token validation, and receiving cited Orbus results; programme-context search is exposed but currently fails closed unless a user-authorized Rayfin connector is configured. The React app provides local or Fabric-backed authentication. Edges reflect the excerpts, SOURCE INDEX references, or README; no Rayfin connector implementation is shown.

Main entry points: [`marlin/mcp-server/src/server.ts`](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/server.ts) (MCP routes and tools), [`marlin/src/services/bootstrap.ts`](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/bootstrap.ts) (Auth bootstrap), [`marlin/src/services/rayfinClient.ts`](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/rayfinClient.ts) (Rayfin client), [`marlin/src/main.tsx`](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/main.tsx) (React app entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP service"]
  node_server["MCP routes and tools<br/>[server.ts]"]
  node_config["Service configuration<br/>[config.ts]"]
  node_orbus["Orbus search client<br/>[orbus.ts]"]
  node_orbus_service[("Orbus Infinity")]
end

subgraph group_identity["Identity and clients"]
  node_auth["Token validation<br/>[auth.ts]"]
  node_entra["Microsoft Entra"]
end

subgraph group_rayfin["Rayfin programme data"]
  node_programme_connector["Programme context connector<br/>[server.ts]"]
  node_records["Programme records<br/>[ProgrammeRecord.ts]"]
  node_facts["Knowledge facts<br/>[KnowledgeFact.ts]"]
  node_schema["Rayfin data schema<br/>[schema.ts]"]
end

subgraph group_web["React application"]
  node_web_entry["React app entry<br/>[main.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_auth_context["Auth provider<br/>[AuthContext.tsx]"]
  node_auth_page["Sign-in page<br/>[AuthPage.tsx]"]
  node_home["Home page<br/>[HomePage.tsx]"]
  node_bootstrap["Auth bootstrap<br/>[bootstrap.ts]"]
  node_auth_contract["Auth service contract<br/>[IAuthService.ts]"]
  node_mock_auth["Local auth service<br/>[MockAuthService.ts]"]
  node_rayfin_auth["Fabric auth service"]
  node_rayfin_client["Rayfin client<br/>[rayfinClient.ts]"]
end

node_caller(("MCP caller"))

node_caller -->|"submits MCP requests"| node_server
node_server -->|"validates bearer token"| node_auth
node_auth -->|"checks configured claims"| node_config
node_auth -->|"retrieves signing keys"| node_entra
node_server -->|"reads service settings"| node_config
node_server -->|"dispatches Orbus search"| node_orbus
node_orbus -->|"exchanges token OBO"| node_entra
node_orbus -->|"queries OData"| node_orbus_service
node_server -->|"calls optional search"| node_programme_connector
node_programme_connector -.->|"searches records"| node_records
node_programme_connector -.->|"searches facts"| node_facts
node_schema -->|"registers entity"| node_records
node_schema -->|"registers entity"| node_facts
node_web_entry -->|"wraps app"| node_auth_context
node_web_entry -->|"renders"| node_app
node_web_entry -->|"initializes auth"| node_bootstrap
node_bootstrap -->|"selects local service"| node_mock_auth
node_bootstrap -->|"selects Fabric service"| node_rayfin_auth
node_bootstrap -->|"initializes client"| node_rayfin_client
node_mock_auth -->|"implements contract"| node_auth_contract
node_rayfin_auth -->|"implements contract"| node_auth_contract
node_mock_auth -->|"uses client session"| node_rayfin_client
node_rayfin_auth -->|"uses client session"| node_rayfin_client
node_rayfin_client -->|"types client"| node_schema

click node_server "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/server.ts"
click node_config "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/config.ts"
click node_auth "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/auth.ts"
click node_orbus "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/orbus.ts"
click node_programme_connector "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/server.ts"
click node_records "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/ProgrammeRecord.ts"
click node_facts "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/KnowledgeFact.ts"
click node_schema "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/schema.ts"
click node_web_entry "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/main.tsx"
click node_app "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/App.tsx"
click node_auth_context "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/hooks/AuthContext.tsx"
click node_auth_page "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/components/AuthPage.tsx"
click node_home "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/pages/HomePage.tsx"
click node_bootstrap "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/bootstrap.ts"
click node_auth_contract "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/IAuthService.ts"
click node_mock_auth "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/MockAuthService.ts"
click node_rayfin_auth "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/RayfinAuthService.ts"
click node_rayfin_client "https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/rayfinClient.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_config,node_orbus,node_orbus_service toneBlue
class node_auth,node_entra toneAmber
class node_programme_connector,node_records,node_facts,node_schema toneMint
class node_web_entry,node_app,node_auth_context,node_auth_page,node_home,node_bootstrap,node_auth_contract,node_mock_auth,node_rayfin_auth,node_rayfin_client toneRose
class node_caller toneIndigo
```

## Components

### MCP service

- [MCP routes and tools](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/server.ts): `marlin/mcp-server/src/server.ts`
- [Service configuration](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/config.ts): `marlin/mcp-server/src/config.ts`
- [Orbus search client](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/orbus.ts): `marlin/mcp-server/src/orbus.ts`
- **Orbus Infinity**

### Identity and clients

- [Token validation](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/auth.ts): `marlin/mcp-server/src/auth.ts`
- **Microsoft Entra**

### Rayfin programme data

- [Programme context connector](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/mcp-server/src/server.ts): `marlin/mcp-server/src/server.ts`
- [Programme records](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/ProgrammeRecord.ts): `marlin/rayfin/data/ProgrammeRecord.ts`
- [Knowledge facts](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/KnowledgeFact.ts): `marlin/rayfin/data/KnowledgeFact.ts`
- [Rayfin data schema](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/rayfin/data/schema.ts): `marlin/rayfin/data/schema.ts`

### React application

- [React app entry](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/main.tsx): `marlin/src/main.tsx`
- [App shell](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/App.tsx): `marlin/src/App.tsx`
- [Auth provider](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/hooks/AuthContext.tsx): `marlin/src/hooks/AuthContext.tsx`
- [Sign-in page](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/components/AuthPage.tsx): `marlin/src/components/AuthPage.tsx`
- [Home page](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/pages/HomePage.tsx): `marlin/src/pages/HomePage.tsx`
- [Auth bootstrap](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/bootstrap.ts): `marlin/src/services/bootstrap.ts`
- [Auth service contract](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/IAuthService.ts): `marlin/src/services/IAuthService.ts`
- [Local auth service](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/MockAuthService.ts): `marlin/src/services/MockAuthService.ts`
- [Fabric auth service](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/RayfinAuthService.ts): `marlin/src/services/RayfinAuthService.ts`
- [Rayfin client](https://github.com/paulgoffin802/project_marlin/blob/main/marlin/src/services/rayfinClient.ts): `marlin/src/services/rayfinClient.ts`

### Other components

- **MCP caller**

## Connections

- MCP caller → MCP routes and tools: submits MCP requests (evidence: `README.md`)
- MCP routes and tools → Token validation: validates bearer token (evidence: `marlin/mcp-server/src/server.ts`)
- Token validation → Service configuration: checks configured claims (evidence: `marlin/mcp-server/src/auth.ts`)
- Token validation → Microsoft Entra: retrieves signing keys (evidence: `marlin/mcp-server/src/auth.ts`)
- MCP routes and tools → Service configuration: reads service settings (evidence: `marlin/mcp-server/src/server.ts`)
- MCP routes and tools → Orbus search client: dispatches Orbus search (evidence: `marlin/mcp-server/src/server.ts`)
- Orbus search client → Microsoft Entra: exchanges token OBO (evidence: `marlin/mcp-server/src/orbus.ts`)
- Orbus search client → Orbus Infinity: queries OData (evidence: `marlin/mcp-server/src/orbus.ts`)
- MCP routes and tools → Programme context connector: calls optional search (evidence: `marlin/mcp-server/src/server.ts`)
- Programme context connector → Programme records: searches records
- Programme context connector → Knowledge facts: searches facts
- Rayfin data schema → Programme records: registers entity (evidence: `marlin/rayfin/data/schema.ts`)
- Rayfin data schema → Knowledge facts: registers entity (evidence: `marlin/rayfin/data/schema.ts`)
- React app entry → Auth provider: wraps app (evidence: `marlin/src/main.tsx`)
- React app entry → App shell: renders (evidence: `marlin/src/main.tsx`)
- React app entry → Auth bootstrap: initializes auth (evidence: `marlin/src/main.tsx`)
- Auth bootstrap → Local auth service: selects local service (evidence: `marlin/src/services/bootstrap.ts`)
- Auth bootstrap → Fabric auth service: selects Fabric service (evidence: `marlin/src/services/bootstrap.ts`)
- Auth bootstrap → Rayfin client: initializes client (evidence: `marlin/src/services/bootstrap.ts`)
- Local auth service → Auth service contract: implements contract (evidence: `marlin/src/services/MockAuthService.ts`)
- Fabric auth service → Auth service contract: implements contract (evidence: `marlin/src/services/RayfinAuthService.ts`)
- Local auth service → Rayfin client: uses client session (evidence: `marlin/src/services/MockAuthService.ts`)
- Fabric auth service → Rayfin client: uses client session (evidence: `marlin/src/services/RayfinAuthService.ts`)
- Rayfin client → Rayfin data schema: types client (evidence: `marlin/src/services/rayfinClient.ts`)
