How Plexi Works

How Plexi Works

This page explains the project in simple terms. You do not need this page to use Plexi, but it helps contributors understand the system.

Short Version

Plexi has:

• A student web app.
• A material library.
• An AI search system.
• A gateway that connects the web app, materials, backend, and AI providers.

The Main Repositories

Folder / repository	Purpose
plexi-remake/plexi-web	React web app used by students.
plexi-remake/plexi-worker	Cloudflare Worker API gateway.
plexi-remake/plexi-api	FastAPI backend for material retrieval.
plexi-materials	Study material catalog and AI index.
plexi.wiki	GitHub Wiki guide.

Student Flow

When a student opens Materials:

1. The web app asks for the material list.
2. The Worker fetches or returns a cached manifest.
3. The web app shows semesters, subjects, material types, and files.
4. When a file is opened, the Worker proxies the file so it can be previewed.

When a student asks Chat:

1. The web app sends the question, semester, and subject to the Worker.
2. The Worker checks rate limits and cache.
3. The Worker asks the FastAPI backend for relevant material chunks.
4. The backend searches the LlamaIndex vector index.
5. The web app builds a prompt using the retrieved chunks.
6. The Worker sends the prompt to the selected AI provider using the student's API key.
7. The answer streams back to the web app.

What the Materials Repository Stores

plexi-materials contains:

• manifest.json: the material list used by the app.
• indexed_files.json: a record of files processed into the AI index.
• index/: the vector index used for retrieval.

What RAG Means

RAG means Retrieval-Augmented Generation.

In Plexi, that means:

1. Retrieve useful text from uploaded materials.
2. Give that text to the AI.
3. Ask the AI to answer using that text.

This helps reduce generic answers because the AI sees the course material before responding.

Why Plexi Uses a Worker

The Cloudflare Worker acts as a middle layer.

It helps with:

• Caching material lists.
• Caching repeated retrieval and answer requests.
• Rate limiting.
• Proxying files for preview.
• Calling different AI providers through a common chat-completions style request.

Why Uploads Use GitHub Issues

Direct material commits can break the manifest or AI index.

The issue workflow keeps uploads safer:

1. Student submits file through an issue.
2. Maintainer reviews it.
3. Maintainer adds approved.
4. Automation updates the material list and AI index together.

This keeps Plexi's library and AI search in sync.