iblai-ontology — Architecture

Mirrored from iblai/ontology · docs/architecture.md. This page is generated — edit it in the repository, not here.

Codename: iblai-ontology Status: Architecture for the on-premise knowledge layer, ported and expanded from the design proposal and aligned with what is implemented in this repository.

This document is the master plan. It explains why iblai-ontology exists, the seven components that make it up, the design decisions that hold the whole thing together, and the phased rollout. Each component has its own deep-dive page; links are inline and collected at the end.

---

Executive Positioning

The prevailing approach in higher-education AI is to extract institutional data through a VPN tunnel into the vendor's cloud. The university gets a "kill switch" on the tunnel, but the data — normalized, projected, queryable — lives on someone else's servers. The vendor controls the compute, the access, and the pipeline.

iblai-ontology is fundamentally different. We deploy a unified knowledge layer inside the university's network. No data extraction. No VPN to our cloud. No third-party infrastructure holding institutional data. The university owns the data, the knowledge base, and the infrastructure that runs it. We build the plumbing that makes their existing systems queryable by AI — all under their roof.

The agent runtime — where the AI models actually execute — is a separate concern. It can run on ibl.ai's infrastructure, on the university's own compute, or anywhere else. The critical insight is that the knowledge layer (the data, the cache, the permissions) stays on-premise and is exposed via MCP so that any authorized agent runtime can securely connect to it.

This is the same positioning we use with the federal government:

You will have your data, and we may not even have access to it.

---

What It Is, Technically

iblai-ontology makes a university's existing systems — PeopleSoft/Oracle, Ellucian Banner, Canvas, Slate, EAB Navigate, Workday, LDAP/Active Directory — queryable by AI agents over the Model Context Protocol (MCP), without copying institutional data to any vendor cloud.

It is delivered as a hybrid stack:

• A lean, self-documenting CLI — the ontology command (package iblai_ontology, distribution iblai-ontology) — built on typer + rich. The CLI and configuration layer are intentionally Django-free, so ontology config init works on a fresh checkout before any backend exists.
• A Django + Celery backend for the long-running services: the sync engine, the discovery/provisioning engines, the identity gateway, and the outbound MCP server. The CLI dispatches into the backend (via a bootstrap() call) only for commands that need it.

The runtime is deployed as a Docker Compose stack on university infrastructure. See deployment.md.

---

Architecture Overview

The on-premise knowledge layer has seven components. Components 1–4 form the data and access layer. Components 5–7 form the operations layer — the tooling that makes the system discoverable, provisionable, and manageable. The agent runtime is separate and connects remotely via MCP.

UNIVERSITY NETWORK (ON-PREMISE)
================================================

  Source Systems (existing)
  PeopleSoft  Canvas  Slate  Navigate  Workday  LDAP/AD
      |          |       |       |        |       |
      v          v       v       v        v       v
  +-------------------------------------------------+
  | COMPONENT 1: MCP INBOUND CONNECTIVITY            |
  |                                                   |
  |  MCP Toolbox for        Custom MCP Servers        |
  |  Databases              (Canvas, Slate,           |
  |  (Oracle, Postgres,      Navigate, LDAP)          |
  |   SQL Server)                                     |
  +-------------------------+-------------------------+
                            |
                            v
  +-------------------------------------------------+
  | COMPONENT 2: KNOWLEDGE MATERIALIZATION           |
  |              ("iblai-ontology")                   |
  |                                                   |
  |  Sync Engine (scheduled)                          |
  |       |                                           |
  |       v                                           |
  |  Text Memories    Structured Cache    Vector      |
  |  (Markdown)       (PostgreSQL)        Index       |
  |  /ontology/       students, courses,  (ChromaDB)  |
  |  students/        enrollment, holds,              |
  |  courses/         financial_aid ...               |
  |  financial-aid/                                   |
  +-------------------------------------------------+
                            |
                            v
  +-------------------------------------------------+
  | COMPONENT 3: IDENTITY & PERMISSIONS              |
  |                                                   |
  |  Microsoft Entra ID (Azure AD)                    |
  |  SAML / OIDC / OAuth 2.0                          |
  |                                                   |
  |  JWT token validation on every request            |
  |  Role-to-toolset mapping (roles.yaml)             |
  |  X-Iblai-Role header (set by ibl.ai platform)     |
  +-------------------------------------------------+
                            |
                            v
  +-------------------------------------------------+
  | COMPONENT 4: MCP OUTBOUND EXPOSURE               |
  |                                                   |
  |  iblai-ontology exposed as an MCP server          |
  |  over HTTPS (port 443, streamable_http)           |
  |                                                   |
  |  Firewall-gated: only authorized IPs/networks     |
  |  Token-authenticated: Entra ID OAuth 2.0          |
  |  Toolsets scoped by caller's role                 |
  +-------------------------------------------------+
          |
          | HTTPS (MCP over streamable_http)
          | Through university firewall
          v

EXTERNAL
================================================

  +----------------------------------------------+
  |  AGENT RUNTIME (ibl.ai infrastructure)        |
  |                                                |
  |  Enrollment  Financial  Advising  IT Help      |
  |  Agent       Aid Agent  Agent     Desk Agent   |
  |                                                |
  |  Agents connect to the on-premise ontology     |
  |  via MCP. They forward the user's Entra ID     |
  |  token + X-Iblai-Role on every request. The    |
  |  on-premise layer validates the token and      |
  |  scopes the response to the user's role.       |
  |                                                |
  |  Agents never store institutional data.        |
  +----------------------------------------------+

OPERATIONS LAYER (Components 5-7)
================================================

  +----------------------------------------------+
  |  COMPONENT 7: CLI (ontology)                  |
  |                                                |
  |  $ ontology service add                        |
  |  $ ontology service list / status / sync       |
  |  $ ontology config init / show / set           |
  |  $ ontology sync run / status / history        |
  |  $ ontology health / deploy / mcp / data       |
  +----------------------------------------------+
          |
          v
  +----------------------------------------------+
  |  COMPONENT 5: SERVICE DISCOVERY ENGINE        |
  |                                                |
  |  Connect -> Safety Check -> Schema Introspect |
  |      -> LLM Analysis -> Generate Config       |
  |                                                |
  |  Pre-built adapters: PeopleSoft, Banner,       |
  |  Canvas, Slate, Workday, Navigate, Generic     |
  +----------------------------------------------+
          |
          v
  +----------------------------------------------+
  |  COMPONENT 6: PROVISIONING ENGINE             |
  |                                                |
  |  Generate: cache schema, text templates,       |
  |  tools.yaml, sync-schedules.yaml,             |
  |  docker-compose updates                        |
  |                                                |
  |  Validate: end-to-end test sync per service    |
  +----------------------------------------------+
          |
          v
  [Components 1-4 are configured and running]

---

The Seven Components

---

Key Design Decisions

These principles are non-negotiable and recur throughout every component.

Read-only everywhere

No source-system writes in v1. Every connection is SELECT-only / GET-only. Before iblai-ontology touches a single row, the safety verification suite (Component 5) proves the supplied credentials cannot write — it attempts seven write operations and requires that all seven be denied. If any write succeeds, the system refuses to proceed and prints remediation SQL. Write-back, behind human approval workflows, is an explicit future item (see Open Design Questions).

Credential isolation

Each MCP server has its own credential scope. PeopleSoft credentials are never accessible from the Canvas MCP server. Source-system credentials are encrypted at rest (Fernet) in the service registry and supplied to each container via its own env file.

No data crosses MCP boundaries

Each MCP server is a process-isolated container. Data flows up to the sync engine or the exposure gateway — never sideways between MCP servers. On the Docker network, the ontology-internal network is marked internal: true, so the databases, MCP Toolbox, and sync engine cannot reach the internet at all; only the gateway and the reverse proxy bridge to the outside.

Identity is borrowed, not built

We use the university's existing Entra ID for authentication. No new passwords, no new MFA. The on-premise gateway validates the JWT and answers exactly one authorization question: "Given this role, what can the user access?" It does not decide who has a role. See the split below.

Clean separation of identity, role assignment, and role permissions

Agent-native storage

Knowledge is materialized primarily as Markdown text files, which LLMs read and reason over without ORMs, query languages, or schema mapping. The files are inspectable, git-diffable, and permission-mappable at the filesystem level. A PostgreSQL cache backs the queries that need structure (aggregations, joins, analytics), and a vector index enables semantic search.

---

Implementation Decisions (as implemented in this repo)

Where the original design proposal left options open, this repository commits to a specific shape. These are stated here as fact; component docs note them again where relevant.

• Hybrid stack. A Django-free CLI/config layer (iblai_ontology) plus a Django + Celery backend for long-running services. CLI commands that need the backend call bootstrap() lazily.
• Identity Option A first. The gateway validates the Entra ID JWT and trusts an X-Iblai-Role header that the ibl.ai platform sets per request; roles.yaml maps role → access. Option B (on-prem OAuth, Notion-style, exposing RFC 9728 Protected Resource Metadata + RFC 7591 Dynamic Client Registration) is documented as the roadmap alternative and can coexist. See identity.md.
• LLM defaults are BYOK. The university provides its own key; iblai-ontology never ships one. Default models: anthropic → claude-opus-4-8, openai → gpt-4o. Without a key, a rule-based analyzer handles common higher-ed schema patterns.
• Canonical config and SQL. Large configuration and schema artifacts live in config/ (tools.yaml, roles.yaml, sync-schedules.yaml, services.yaml, ontology.yaml) and sql/ (schema.sql, views.sql). The docs summarize and reference these rather than reproducing every statement.

---

Platform Integration (facts from the live ibl.ai codebase)

The ibl.ai platform already models MCP Server, MCP Server Connection, and Connected Service. It implements discover_and_register_mcp_oauth_service using RFC 9728 (Protected Resource Metadata discovery) and RFC 7591 (Dynamic Client Registration). Per-user in-chat OAuth creates a ConnectedService plus an MCPServerConnection. The runtime resolution chain is user → agent → platform scope, and the user's role is forwarded via extra_headers as X-Iblai-Role. Registration endpoints live under:

base.manager.iblai.app/api/ai-agent/orgs/<org>/users/admin/mcp-servers/
base.manager.iblai.app/api/ai-agent/orgs/<org>/users/admin/mcp-server-connections/

Full detail, including the curl calls and the in-chat OAuth sequence, is in platform-integration.md.

---

Competitive Positioning

---

Phased Implementation

A condensed view of the rollout; the full week-by-week checklist is in deployment.md.

• Phase 1 — Foundation (Weeks 1–3). Stand up Postgres + MCP Toolbox + ChromaDB, connect the first source (PeopleSoft), run the initial full sync, bring up the gateway + reverse proxy, configure the Entra ID app registration, register iblai-ontology in the ibl.ai platform, and validate an end-to-end agent interaction with role scoping.
• Phase 2 — Expand sources (Weeks 3–6). Add Canvas and Slate MCP servers, enrich student memory files, build and test the Financial Aid and Advising agents, and verify role-based access boundaries.
• Phase 3 — Full iblai-ontology (Weeks 6–10). Add Navigate, LDAP/AD, and others; build department agents; enable vector search; build the admin dashboard; production-harden (TLS, backups, monitoring, log aggregation); load test.
• Phase 4 — Advanced (ongoing). Event-driven sync via webhooks, student-facing self-service agents, cross-institutional templates, and write-back with approval workflows.

---

The Shared IT Vision

Because iblai-ontology deploys as a standard Docker Compose stack with a standard directory structure and MCP-based connectors, multiple institutions can run the same stack independently:

1. Build the template ontology once for PeopleSoft + Canvas + Slate.
2. Deploy at a small institution — same stack, different credentials.
3. Deploy across a consortium — same stack, same pattern.
4. Share agents — the Financial Aid Agent does not need to be rebuilt per school.
5. Stay isolated — each institution runs its own stack; no data sharing unless explicitly configured.

---

Open Design Questions

1. Per-user vs. per-entity memory files. Current design is per-entity (one file per student). A per-user view that aggregates only role-relevant entities trades storage for permission simplicity.
2. Embedding model for air-gapped deployments. nomic-embed-text runs locally but is less capable; it needs benchmarking against university-scale queries.
3. Write-back architecture. When agents eventually update source systems (e.g., approve an aid package), the proposed flow is: agent creates a pending action → human approves in the UI → action executes via an MCP write tool.
4. Sync conflict / freshness signaling. Every memory file carries a "Last synced" timestamp; agents should state confidence in data recency when source data may have changed mid-cycle.
5. Multi-institution sharing. For the consortium vision, is there a federated layer where institutions can share aggregate, anonymized data for benchmarking with explicit consent?
6. Multi-tenant MCP server sharing. The platform supports is_featured servers shared across tenants. Should each university register its own MCP Server, or should a featured meta-server route to the correct on-premise instance by tenant?

---

Document Index

• components/01-mcp-inbound.md — Component 1
• components/02-knowledge-materialization.md — Component 2
• components/03-identity.md — Component 3 (pointer)
• components/04-mcp-outbound.md — Component 4
• components/05-service-discovery.md — Component 5
• components/06-provisioning.md — Component 6
• components/07-cli.md — Component 7
• identity.md — Component 3 deep dive (Entra ID flow, roles.yaml, Option A vs B)
• platform-integration.md — Component 4 deep dive (ibl.ai platform)
• deployment.md — Docker Compose stack and phased rollout