Building ContextGuard AI: A Grounded MERN Study Assistant with Flashcards, Mermaid Diagrams, and PDF Uploads

0xErick — Sat, 21 Mar 2026 15:13:03 +0000

Building ContextGuard AI: A Grounded MERN Study Assistant with Flashcards, Mermaid Diagrams, and PDF Uploads

Introduction

Students deal with a familiar problem: too many notes, too little time, and no easy way to turn raw lecture material into something they can review quickly.

That was the motivation behind ContextGuard AI, a MERN stack project that takes lecture notes, extracts key concepts, generates evidence-backed flashcards, and builds a Mermaid concept map from the same source material.

The most important design choice in this project is not just “use AI.” It is use grounded AI.

Instead of letting the model freely invent or enrich information, the app is designed to:

work only from the user’s notes
refuse weak or insufficient input
attach evidence to each flashcard
validate Mermaid output before showing it
save everything to MongoDB for later use

In this post, I’ll walk through the project step by step and explain how the frontend, backend, and database work together.

What the App Does

ContextGuard AI supports this workflow:

A user pastes lecture notes or uploads a PDF/text file.
The frontend extracts the note text.
The text is sent to the backend.
The backend generates:
- exactly 5 flashcards
- a Mermaid graph TD concept map
- evidence spans showing where each flashcard came from
The generated study deck is stored in MongoDB.
The frontend displays the flashcards and diagram in a split workspace.

That gives the user both:

a quick recall format for revision
a visual map for concept understanding

Tech Stack

This project uses a MERN architecture:

MongoDB + Mongoose for persistence
Express for the backend API
React for the frontend
Node.js for the runtime

On top of that:

Tailwind CSS powers the UI styling
pdfjs-dist extracts text from uploaded PDFs
react-mermaid2 renders concept maps
OpenAI is optionally used for live generation

If no API key is configured, the app falls back to a grounded heuristic generator so the workflow still works.

Project Structure

At a high level, the repository is split into client and server.

contextguard AI/
|- client/
|  `- src/
|     `- components/
|        |- Workspace.jsx
|        |- Diagramview.jsx
|        `- Loadingskeleton.jsx
|- server/
|  |- models/
|  |  `- StudyDeck.js
|  `- routes/
|     `- ai.js
|- package.json
`- README.md

The frontend handles user interaction and rendering.

The backend handles generation, validation, and storage.

Step 1: Designing the Data Model

Before building the AI route, I defined the shape of the saved study deck in MongoDB.

That schema lives in server/models/StudyDeck.js.

The model stores:

the original rawNotes
generated flashcards
mermaidCode
Mermaid validation metadata
warning messages
refusal state
generation provider/model metadata

Each flashcard also stores an evidence object:

quote
startChar
endChar

That evidence layer is important because it turns a generic AI feature into a verifiable study tool.

Here is the core idea of the schema:

const FlashcardSchema = new mongoose.Schema(
  {
    term: String,
    definition: String,
    evidence: {
      quote: String,
      startChar: Number,
      endChar: Number,
    },
    verificationStatus: {
      type: String,
      enum: ['grounded', 'unverified'],
    },
  },
  { _id: false }
);

This means every saved card is traceable to a specific piece of source text.

Step 2: Building a Grounded AI Route

The main backend logic lives in server/routes/ai.js.

The route exposes:

POST /api/ai/generate

It expects:

{
  "rawNotes": "Your notes here"
}

The route starts by validating the request:

if (!rawNotes || !rawNotes.trim()) {
  return res.status(400).json({ message: 'rawNotes field is required.' });
}

That keeps empty submissions out of the generation pipeline.

The System Prompt

The most important prompt design rule is simple:

Use only the supplied notes. Do not use outside knowledge.

The backend prompt enforces:

grounded generation
exact JSON output
exactly 5 flashcards
verbatim evidence quotes
refusal behavior when notes are too weak

This turns the route into a structured generation endpoint instead of a free-form chatbot.

Structured Output

The route expects output in this shape:

{
  "status": "generated" | "refused",
  "refusalReason": "string",
  "flashcards": [
    {
      "term": "string",
      "definition": "string",
      "evidence": {
        "quote": "string",
        "startChar": 0,
        "endChar": 20
      }
    }
  ],
  "mermaidCode": "graph TD ..."
}

That structure matters because it makes the frontend predictable and testable.

Step 3: Supporting Live AI and a Fallback Generator

One practical problem in hackathon and student apps is API dependency.

If the OpenAI key is missing or the network call fails, the whole product should not collapse.

To solve that, the route supports two generation modes:

Live OpenAI generation
Grounded heuristic fallback

If OPENAI_API_KEY exists, the route tries OpenAI first.

If that fails, it falls back to local logic:

if (OPENAI_API_KEY) {
  try {
    generationResult = await generateWithOpenAI(cleanedRawNotes);
  } catch (error) {
    generationResult = generateFallbackDeck(cleanedRawNotes);
  }
} else {
  generationResult = generateFallbackDeck(cleanedRawNotes);
}

This made the project much more resilient during development and demos.

Step 4: Extracting Evidence from Notes

The project does not just create terms and definitions.

It also attaches evidence using a helper that finds where a quote exists inside the notes:

function createEvidence(rawNotes, quote) {
  const startChar = rawNotes.indexOf(quote);

  if (startChar === -1) {
    return null;
  }

  return {
    quote,
    startChar,
    endChar: startChar + quote.length,
  };
}

This is a small utility, but it unlocks one of the strongest parts of the app:

users can inspect what the flashcard was grounded on
the system can reject unsupported output
the saved data becomes much more trustworthy

Step 5: Validating Mermaid Before Rendering

Mermaid diagrams are a great way to visualize relationships, but AI-generated Mermaid can fail.

So the backend validates Mermaid output before storing it:

function validateMermaidCode(mermaidCode) {
  const trimmed = typeof mermaidCode === 'string' ? mermaidCode.trim() : '';

  if (!trimmed.startsWith('graph TD')) {
    return { isValid: false, errorMessage: 'Mermaid code must begin with "graph TD".' };
  }

  return { isValid: true, errorMessage: '' };
}

That result gets saved in MongoDB as mermaidValidation.

Step 6: Saving the Generated Deck to MongoDB

Once the generation result is ready, the route creates a StudyDeck document and saves it:

const newStudyDeck = new StudyDeck({
  rawNotes: cleanedRawNotes,
  flashcards,
  mermaidCode,
  mermaidValidation,
  warnings,
  status,
  refusalReason,
  generation: {
    promptVersion: 'v2',
    provider,
    model,
    flashcardCount: flashcards.length,
  },
});

await newStudyDeck.save();

This means every generation is stored as a complete record, not just a temporary response.

That opens the door for:

deck history
re-reviewing past outputs
analytics
future quiz/repetition features

Step 7: Building the Frontend Workspace

The main frontend interface lives in client/src/components/Workspace.jsx.

The workspace is split into two sides:

left: note input
right: generated output

This split makes the workflow easy to understand:

input on one side
output on the other

Local UI State

The component tracks:

rawNotes
flashcards
mermaidCode
isLoading
isUploading
error
uploadMessage
deckMeta
activeTab

That keeps the interface responsive while generation happens.

Step 8: Adding PDF Upload Support

Instead of only supporting pasted text, the app also supports PDF upload using pdfjs-dist.

That logic is inside Workspace.jsx:

async function readPdfFile(file) {
  const arrayBuffer = await file.arrayBuffer();
  const pdf = await getDocument({ data: arrayBuffer }).promise;
  const pages = [];

  for (let pageNumber = 1; pageNumber <= pdf.numPages; pageNumber += 1) {
    const page = await pdf.getPage(pageNumber);
    const textContent = await page.getTextContent();
    const text = textContent.items.map((item) => item.str).join(' ').replace(/\s+/g, ' ').trim();
    if (text) pages.push(text);
  }

  return pages.join('\\n\\n');
}

This gives the app a much more realistic student workflow:

upload a lecture handout
extract note text
generate revision material immediately

Step 9: Rendering Output with Tabs

The output panel uses a simple tab model:

const tabs = [
  { id: 'flashcards', label: 'Flashcards' },
  { id: 'diagram', label: 'Diagram' },
];

Why tabs?

Because the user has two different study modes:

rapid recall with flashcards
concept understanding with diagrams

Putting both into one scroll stream would make the interface harder to use.

Step 10: Showing Loading and Refusal States

Good AI UX is not just about the final answer.

It also needs:

loading states
warnings
refusal messaging
graceful empty states

The project uses a LoadingSkeleton component while generation runs and displays warnings or refusal messages above the output.

This makes the app feel much more intentional and reliable.

Step 11: Handling Mermaid Rendering Errors Gracefully

Mermaid rendering is handled in client/src/components/Diagramview.jsx.

This component does three things:

shows a placeholder when there is no diagram
shows raw Mermaid code if validation failed
uses an error boundary to catch runtime render failures

The error boundary is especially useful:

class MermaidErrorBoundary extends React.Component {
  static getDerivedStateFromError() {
    return { hasError: true };
  }
}

That means a bad Mermaid string does not crash the app.

Instead, the user sees a safe fallback and can still inspect the generated code.

Step 12: Responsible AI in the UI

The frontend also includes visible warning copy to reinforce good usage:

the app is grounded to the user’s notes
users should verify evidence before treating output as exam-ready

This matters because responsible AI is not only a backend prompt problem.

It is also a UX problem.

Users should be reminded what the system can and cannot guarantee.

Step 13: Environment Variables

The backend is configured through server/.env:

MONGODB_URI=...
PORT=5000
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini

This supports:

MongoDB Atlas or local MongoDB
optional OpenAI usage
easy environment switching

Step 14: Running the App

At the root level, the app can be started with:

npm run dev

Frontend:

cd client
pnpm dev

Backend:

cd server
pnpm start

Step 15: What Makes This Project Interesting

There are a lot of AI apps that just wrap a chat box around a model.

This project goes a step further by combining:

structured output
verifiable evidence
visualization
refusal behavior
persistent storage

That makes it more useful than a generic summarizer and more trustworthy than a free-form study assistant.

Challenges I Ran Into

A few practical challenges came up while building this:

AI output has to be validated, not trusted
Mermaid rendering can fail if syntax is malformed
PDF extraction needs cleanup because raw text is often noisy
frontend layout can look broken if the Tailwind pipeline is misconfigured
Vite and environment issues can look like UI bugs at first

These are the kinds of problems that turn a demo into an actual engineering project.

Where This Could Go Next

There are plenty of natural next steps:

deck history and saved sessions
spaced repetition scheduling
quiz mode
source-linked Mermaid nodes
multi-file note ingestion
confidence scoring per flashcard

The data model already supports many of these extensions.

Final Thoughts

ContextGuard AI started as a study productivity idea, but the more interesting part became the architecture around grounded generation.

The lesson from this project is simple:

If you want AI features to feel useful in a real product, you need more than generation.

You need:

structure
validation
traceability
graceful failure states
good UX

That combination is what turns “AI output” into a tool users can actually work with.

DEV Community: 0xErick

Building ContextGuard AI: A Grounded MERN Study Assistant with Flashcards, Mermaid Diagrams, and PDF Uploads

Building ContextGuard AI: A Grounded MERN Study Assistant with Flashcards, Mermaid Diagrams, and PDF Uploads

Introduction

What the App Does

Tech Stack

Project Structure

Step 1: Designing the Data Model

Step 2: Building a Grounded AI Route

The System Prompt

Structured Output

Step 3: Supporting Live AI and a Fallback Generator

Step 4: Extracting Evidence from Notes

Step 5: Validating Mermaid Before Rendering

Step 6: Saving the Generated Deck to MongoDB

Step 7: Building the Frontend Workspace

Local UI State

Step 8: Adding PDF Upload Support

Step 9: Rendering Output with Tabs

Step 10: Showing Loading and Refusal States

Step 11: Handling Mermaid Rendering Errors Gracefully

Step 12: Responsible AI in the UI

Step 13: Environment Variables

Step 14: Running the App

Step 15: What Makes This Project Interesting

Challenges I Ran Into

Where This Could Go Next

Final Thoughts