System Architecture

1. High-Level Flow

BacMR operates on a "Teacher-as-a-Service" model using an Agentic RAG architecture.

graph TD
    A[Student] -->|Chat Request| B(FastAPI)
    B -->|Verify JWT| C[Supabase Auth]
    B -->|Check Balance| D[Supabase DB / Wallet]
    B -->|Invoke Agent| E{LangGraph Teacher}
    E -->|Search| F[Pinecone Vector DB]
    E -->|Rerank| G[OpenAI gpt-4o-mini]
    E -->|Generate| H[OpenAI gpt-4o]
    H -->|Stream SSE| A
    E -->|Log Usage| I[Supabase DB / Logs]

2. Core Components

2.1 API Layer (FastAPI)

• Framework: FastAPI with Pydantic for schema validation.
• Streaming: Server-Sent Events (SSE) for real-time token delivery.
• Middleware: CORS configured for production and local development.

2.2 Intelligence Layer (LangGraph & OpenAI)

• Reasoning: teacher_agent.py defines a StateGraph that manages the chat lifecycle.
• Retrieval: Multi-stage (Dense Vector Search -> LLM Reranking).
• Models:
• Embedding: text-embedding-3-small
• Reranking: gpt-4o-mini
• Chat: gpt-4o

2.3 Data Layer

• Relational (Supabase/Postgres): Stores user profiles, wallets, ledger, usage logs, and scraping references.
• Vector (Pinecone): Stores curriculum chunks with metadata.

3. Security

• Authentication: Supabase JWT validation.
• Authorization: Role-based access (student, admin).
• Billing: Pre-check balance before any LLM invocation.

Back to Index