# longbatman09/r2p-enterprise architecture

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

- Interactive diagram: https://gitdiagram.com/longbatman09/r2p-enterprise
- Repository: https://github.com/longbatman09/r2p-enterprise

## Overview

#### Purpose and Entry Points
R2P Enterprise is a multi-tenant school platform that converts unstructured student reports into extracted marks, charts, and optional presentation decks, while offering isolated per-student textbook RAG. Its production boundary is the FastAPI MCP backend: `mcp_backend/main.py`, with dashboard REST endpoints and authenticated MCP JSON-RPC/SSE access. Schools primarily consume it through `r2p_school_sdk/client.py`.

#### API, Identity, and Tenant Boundary
The backend supports Supabase email/password sessions for dashboard users and `sk_...` API keys for SDK/MCP callers. JWT/API-key authentication is unified at the MCP boundary; service credentials can be stored for users, with AES-GCM protection when configured. School, student, key, invoice, and report entities are scoped to the school tenant.
- `mcp_backend/auth_routes.py`
- `mcp_backend/auth_supabase.py`
- `mcp_backend/school_routes.py`
- `mcp_backend/database.py`
- `supabase/schema.sql`

#### Report Analysis Pipeline
A caller uploads a report through an MCP tool. The UI orchestration layer coordinates prescan/upload analysis; vision extraction invokes Gemini to identify exam, student, subject, marks, and attendance from PDFs or images. Local pipeline agents merge extracted file/page results into student-oriented JSON, then chart/PPT rendering produces user-facing artifacts.
- `mcp_servers/ui_orchestrator.py`
- `mcp_servers/vision_extractor.py`
- `agents/orchestrator.py`
- `agents/local_mem.py`
- `mcp_servers/plot_renderer.py`

#### Retrieval-Augmented Textbook Service
Textbook ingestion and question answering are separate from report extraction. Content is embedded using NVIDIA NIM and stored/searchable in Pinecone namespaces partitioned by student, preventing cross-student retrieval. The MCP RAG module is the service-side implementation; the SDK exposes the school-facing call shape.
- `mcp_servers/rag_system.py`
- `r2p_school_sdk/rag/manager.py`
- `r2p_school_sdk/rag/pinecone_helper.py`
- `migrate_rag_supabase.sql`

#### School SDK and Commercial Integrations
`r2p_school_sdk` is the thin Python integration layer: it sends authenticated report and RAG requests to the backend rather than exposing MCP mechanics to schools. It also contains administrative/dashboard access and Stripe invoicing support. Backend persistence remains authoritative for tenant data and API-key lifecycle.
- `r2p_school_sdk/client.py`
- `r2p_school_sdk/admin/dashboard.py`
- `r2p_school_sdk/invoicing/stripe_service.py`

#### Runtime and Deployment
The primary runtime is Python/FastAPI/Uvicorn in Docker, deployed via Render. Supabase provides Auth and Postgres; Google Gemini provides document extraction; NVIDIA NIM and Pinecone provide RAG; Stripe handles invoices. Local composition and Render provisioning define the backend deployment path.
- `mcp_backend/Dockerfile`
- `mcp_backend/requirements.txt`
- `docker-compose.yml`
- `render.yaml`

#### Secondary Agent Runtimes
Two Google Agents CLI/ADK applications appear to be independently deployable agent runtimes, likely for conversational/orchestration and scanning roles. They are separate from the primary FastAPI MCP service but include telemetry and Terraform deployment definitions.
- `my-agent/app/agent_runtime_app.py`
- `scan-agent/app/agent_runtime_app.py`
- `my-agent/deployment/terraform/single-project/service.tf`

Main entry points: [`mcp_backend/main.py`](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/main.py) (FastAPI MCP service), [`mcp_servers/vision_extractor.py`](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/vision_extractor.py) (Vision extraction), [`mcp_servers/rag_system.py`](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/rag_system.py) (RAG MCP service), [`mcp_backend/auth_routes.py`](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/auth_routes.py) (Auth and tenant routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["School clients"]
  node_sdk["School SDK<br/>Python SDK<br/>[client.py]"]
  node_sdk_dashboard["SDK dashboard admin<br/>admin module<br/>[dashboard.py]"]
  node_sdk_stripe["SDK invoicing<br/>Stripe integration<br/>[stripe_service.py]"]
end

subgraph group_backend["MCP backend"]
  node_api{{"FastAPI MCP service<br/>FastAPI / JSON-RPC SSE<br/>[main.py]"}}
  node_identity["Auth and tenant routes<br/>identity boundary<br/>[auth_routes.py]"]
  node_school_api["School API routes<br/>tenant REST API<br/>[school_routes.py]"]
  node_tenant_db[("Tenant persistence<br/>Postgres data layer<br/>[database.py]")]
end

subgraph group_analysis["Report analysis"]
  node_ui_orchestrator["Upload orchestration<br/>MCP UI workflow<br/>[ui_orchestrator.py]"]
  node_vision["Vision extraction<br/>document extraction"]
  node_report_agents["Report merge agents<br/>local agent pipeline<br/>[orchestrator.py]"]
  node_renderer["Chart and PPT renderer<br/>artifact rendering<br/>[plot_renderer.py]"]
end

subgraph group_rag["Textbook RAG"]
  node_rag_service["RAG MCP service<br/>textbook RAG<br/>[rag_system.py]"]
  node_rag_sdk["SDK RAG manager<br/>RAG client facade<br/>[manager.py]"]
end

subgraph group_agents["Secondary agent runtimes"]
  node_agent_runtime{{"Conversational agent runtime<br/>Google ADK app"}}
  node_scan_runtime{{"Scanning agent runtime<br/>Google ADK app"}}
end

subgraph group_platform["Managed platform"]
  node_supabase[("Supabase<br/>Auth and Postgres<br/>[schema.sql]")]
  node_gemini["Google Gemini<br/>vision model"]
  node_nim_pinecone[("NVIDIA NIM + Pinecone<br/>embeddings and vector search<br/>[pinecone_helper.py]")]
  node_stripe["Stripe<br/>billing platform"]
  node_deployment["Docker / Render deployment<br/>service deployment<br/>[render.yaml]"]
end

node_sdk -->|"authenticated report and RAG requests"| node_api
node_sdk_dashboard -->|"administration"| node_api
node_sdk_stripe -->|"invoices"| node_stripe
node_api -->|"authenticates callers"| node_identity
node_api -->|"serves dashboard APIs"| node_school_api
node_identity -->|"email/password sessions"| node_supabase
node_school_api -->|"tenant-scoped records"| node_tenant_db
node_tenant_db -->|"persists via"| node_supabase
node_api -->|"report upload tool"| node_ui_orchestrator
node_ui_orchestrator -->|"prescan and extraction"| node_vision
node_vision -->|"PDF/image analysis"| node_gemini
node_vision -->|"file/page results"| node_report_agents
node_report_agents -->|"student JSON"| node_renderer
node_api -->|"RAG tools"| node_rag_service
node_rag_sdk -->|"school RAG calls"| node_rag_service
node_rag_service -->|"embed and student-scoped search"| node_nim_pinecone
node_deployment -->|"deploys"| node_api
node_agent_runtime -.->|"separate runtime"| node_api
node_scan_runtime -.->|"separate runtime"| node_api

click node_sdk "https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/client.py"
click node_sdk_dashboard "https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/admin/dashboard.py"
click node_sdk_stripe "https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/invoicing/stripe_service.py"
click node_api "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/main.py"
click node_identity "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/auth_routes.py"
click node_school_api "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/school_routes.py"
click node_tenant_db "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/database.py"
click node_ui_orchestrator "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/ui_orchestrator.py"
click node_vision "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/vision_extractor.py"
click node_report_agents "https://github.com/longbatman09/r2p-enterprise/blob/main/agents/orchestrator.py"
click node_renderer "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/plot_renderer.py"
click node_rag_service "https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/rag_system.py"
click node_rag_sdk "https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/rag/manager.py"
click node_agent_runtime "https://github.com/longbatman09/r2p-enterprise/blob/main/my-agent/app/agent_runtime_app.py"
click node_scan_runtime "https://github.com/longbatman09/r2p-enterprise/blob/main/scan-agent/app/agent_runtime_app.py"
click node_supabase "https://github.com/longbatman09/r2p-enterprise/blob/main/supabase/schema.sql"
click node_nim_pinecone "https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/rag/pinecone_helper.py"
click node_deployment "https://github.com/longbatman09/r2p-enterprise/blob/main/render.yaml"

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_sdk,node_sdk_dashboard,node_sdk_stripe toneBlue
class node_api,node_identity,node_school_api,node_tenant_db toneAmber
class node_ui_orchestrator,node_vision,node_report_agents,node_renderer toneMint
class node_rag_service,node_rag_sdk toneRose
class node_agent_runtime,node_scan_runtime toneIndigo
class node_supabase,node_gemini,node_nim_pinecone,node_stripe,node_deployment toneTeal
```

## Components

### School clients

- [School SDK](https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/client.py): Python SDK · School-facing authenticated integration layer. · `r2p_school_sdk/client.py`
- [SDK dashboard admin](https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/admin/dashboard.py): admin module · `r2p_school_sdk/admin/dashboard.py`
- [SDK invoicing](https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/invoicing/stripe_service.py): Stripe integration · `r2p_school_sdk/invoicing/stripe_service.py`

### MCP backend

Primary FastAPI production boundary.

- [FastAPI MCP service](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/main.py): FastAPI / JSON-RPC SSE · Dashboard REST and authenticated MCP entry point. · `mcp_backend/main.py`
- [Auth and tenant routes](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/auth_routes.py): identity boundary · Unifies Supabase sessions and sk_ API keys. · `mcp_backend/auth_routes.py`
- [School API routes](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/school_routes.py): tenant REST API · `mcp_backend/school_routes.py`
- [Tenant persistence](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_backend/database.py): Postgres data layer · Authoritative school, student, report, key, and invoice records. · `mcp_backend/database.py`

### Report analysis

- [Upload orchestration](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/ui_orchestrator.py): MCP UI workflow · Coordinates prescan and report upload analysis. · `mcp_servers/ui_orchestrator.py`
- [Vision extraction](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/vision_extractor.py): document extraction · Extracts exam, student, subjects, marks, and attendance. · `mcp_servers/vision_extractor.py`
- [Report merge agents](https://github.com/longbatman09/r2p-enterprise/blob/main/agents/orchestrator.py): local agent pipeline · Merges file and page results into student JSON. · `agents/orchestrator.py`
- [Chart and PPT renderer](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/plot_renderer.py): artifact rendering · `mcp_servers/plot_renderer.py`

### Textbook RAG

- [RAG MCP service](https://github.com/longbatman09/r2p-enterprise/blob/main/mcp_servers/rag_system.py): textbook RAG · Ingests textbooks and answers student-scoped questions. · `mcp_servers/rag_system.py`
- [SDK RAG manager](https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/rag/manager.py): RAG client facade · `r2p_school_sdk/rag/manager.py`

### Secondary agent runtimes

Independently deployable ADK applications.

- [Conversational agent runtime](https://github.com/longbatman09/r2p-enterprise/blob/main/my-agent/app/agent_runtime_app.py): Google ADK app · `my-agent/app/agent_runtime_app.py`
- [Scanning agent runtime](https://github.com/longbatman09/r2p-enterprise/blob/main/scan-agent/app/agent_runtime_app.py): Google ADK app · `scan-agent/app/agent_runtime_app.py`

### Managed platform

- [Supabase](https://github.com/longbatman09/r2p-enterprise/blob/main/supabase/schema.sql): Auth and Postgres · Authentication and tenant schema provider. · `supabase/schema.sql`
- **Google Gemini**: vision model
- [NVIDIA NIM + Pinecone](https://github.com/longbatman09/r2p-enterprise/blob/main/r2p_school_sdk/rag/pinecone_helper.py): embeddings and vector search · Pinecone namespaces isolate each student's retrieval. · `r2p_school_sdk/rag/pinecone_helper.py`
- **Stripe**: billing platform
- [Docker / Render deployment](https://github.com/longbatman09/r2p-enterprise/blob/main/render.yaml): service deployment · `render.yaml`

## Connections

- School SDK → FastAPI MCP service: authenticated report and RAG requests
- SDK dashboard admin → FastAPI MCP service: administration
- SDK invoicing → Stripe: invoices
- FastAPI MCP service → Auth and tenant routes: authenticates callers
- FastAPI MCP service → School API routes: serves dashboard APIs
- Auth and tenant routes → Supabase: email/password sessions
- School API routes → Tenant persistence: tenant-scoped records
- Tenant persistence → Supabase: persists via
- FastAPI MCP service → Upload orchestration: report upload tool
- Upload orchestration → Vision extraction: prescan and extraction
- Vision extraction → Google Gemini: PDF/image analysis
- Vision extraction → Report merge agents: file/page results
- Report merge agents → Chart and PPT renderer: student JSON
- FastAPI MCP service → RAG MCP service: RAG tools
- SDK RAG manager → RAG MCP service: school RAG calls
- RAG MCP service → NVIDIA NIM + Pinecone: embed and student-scoped search
- Docker / Render deployment → FastAPI MCP service: deploys
- Conversational agent runtime → FastAPI MCP service: separate runtime
- Scanning agent runtime → FastAPI MCP service: separate runtime