How jerrygoodboi/aurenlm works
AurenLM is split into two major runtime boundaries:
1. A browser-based React single-page application for the study experience.
2. A Python/Flask backend that serves AI, persistence, and session APIs.
The two parts communicate over HTTP, with the backend also calling Google Gemini and likely a database through SQLAlchemy for durable storage.
Main subsystems
Frontend: React SPA
• Entry and shell:
- src/index.js, src/App.js, src/App.css, src/index.css
- public/index.html and public/manifest.json indicate a standard SPA host page.
• Global application state:
- src/AuthContext.js manages authentication/session identity for the UI.
- src/ThemeContext.js manages dark/light theme synchronization across the app.
- src/hooks/useNotification.js wraps toast-style user feedback, likely backed by Notistack as described in the README.
• Main user-facing modules:
- src/components/LoginPage.js for sign-in.
- src/components/Studio.js is the main workspace container where the study flows are assembled.
- src/components/Chat.js handles conversational interaction with the AI assistant.
- src/components/ChatSessionList.js handles session navigation and persistence-oriented session selection.
- src/components/DocumentList.js manages documents available to the assistant.
- src/components/QuizView.js renders quiz generation and practice output.
- src/components/EmptyState.js provides default UI when no document/session is active.
- src/components/KeyboardShortcuts.js exposes product shortcuts and UX help.
• UX and platform helpers:
- src/fixResizeObserver.js is a browser compatibility shim.
- src/reportWebVitals.js and src/setupTests.js are standard React app support files.
- src/fonts and CSS files support the visual system.
Backend: Flask AI service
• python_backend/app.py is the backend entrypoint.
• python_backend/config.py centralizes runtime configuration, probably reading environment variables like the Gemini key and Flask secret.
• python_backend/requirements.txt indicates a Python dependency stack centered on Flask, Gemini integration, and SQLAlchemy.
• The backend’s responsibilities are:
- receiving document/session/chat requests from the frontend,
- invoking Gemini for generation,
- persisting sessions/messages and possibly documents,
- returning structured AI responses to the browser.
Core data flows
1. Authentication and app bootstrap
• The user opens the SPA in the browser.
• LoginPage is shown when the auth context does not contain a valid user/session.
• Once authenticated, AuthContext unlocks the main Studio workspace.
• Theme state is shared globally through ThemeContext, so all major views render consistently.
2. Document-centric study workspace
• Studio appears to be the orchestration layer for the main experience.
• DocumentList provides the set of uploaded or selected source documents.
• The selected document or collection becomes context for downstream features:
- chat,
- summarization,
- quiz generation,
- and likely the mindmap/structured study view referenced in the README.
• EmptyState is used when no study content is available yet.
3. Conversational AI and streaming generation
• Chat is the interactive response surface.
• The README explicitly calls out real-time AI streaming, so the frontend likely receives incremental response chunks from the Flask backend and renders them word-by-word or token-by-token.
• The backend calls Gemini, streams or incrementally returns generated output, and the UI updates in place.
• This chat subsystem is the main bridge between user intent and AI generation.
4. Session management and persistence
• ChatSessionList suggests the app supports multiple study sessions.
• The backend, via SQLAlchemy, is responsible for persisting session metadata and message history so the user can resume work across visits.
• Session selection in the frontend changes the active context for Chat, DocumentList, and QuizView.
5. Quiz and study artifact generation
• QuizView represents generated practice material.
• Based on the README, the app can create quizzes with configurable difficulty and style.
• This is likely generated from the current document context, possibly from a chat session or a specific node in the document hierarchy.
6. Audio tutor
• The README says every AI response can be read aloud.
• This feature is likely implemented entirely in the browser using the Web Speech API.
• That means the audio boundary stays client-side: the backend produces text, the browser converts it to speech.
Important architectural boundaries
Frontend vs backend
• The React app owns user interaction, visual state, theming, and local UX behavior.
• The Flask app owns AI calls, persistence, and any document/session logic that must survive reloads.
• This separation keeps the browser thin and the backend authoritative for stored content.
Ephemeral UI state vs durable data
• React contexts and component state handle transient state such as the current theme, active session, selected document, and in-progress chat.
• SQLAlchemy-backed storage on the backend handles durable state like saved sessions and message history.
External AI dependency
• Google Gemini is a critical external service, but it is not accessed directly by the browser.
• The backend mediates all Gemini usage, which centralizes API key handling and response shaping.
Browser-native audio
• The audio tutor is not a backend service; it is a frontend capability using the browser’s speech synthesis APIs.
• This keeps voice playback local and avoids additional infrastructure.
Likely system shape for an architecture diagram
• Browser client:
- Login page
- Main studio workspace
- Chat, documents, sessions, quizzes, theme/notification state
- Optional speech synthesis
• Flask API server:
- Auth/session endpoints
- Chat generation endpoints
- Quiz generation endpoints
- Persistence layer via SQLAlchemy
- Gemini API integration
• External services:
- Google Gemini for generation
- A database for stored sessions/messages, if configured behind SQLAlchemy
• Static hosting:
- The React app is served as static assets, with public/ providing the shell HTML and manifest.
In short, AurenLM is a document-centered study assistant where the React frontend coordinates the learning workspace, and the Flask backend supplies AI generation and persisted study state. The most important flows are document/session selection into chat or quiz generation, AI responses streaming back into the UI, and persistent session history stored server-side while audio playback remains client-side.
Main entry points: Studio.js Studio · app.py Backend app · App.js App frame · AuthContext.js Auth state
Components 18
React SPA
Browser-based study experience and UI state
- SPA shell · Browser entry page and manifest for the React app
public/index.html - App entry · Top-level React mount and application startup
src/index.js - App frame · Global application composition and routing shell
src/App.js - Auth state · Manages authentication and active user/session identity
src/AuthContext.js - Theme state · Coordinates light/dark theme across the UI
src/ThemeContext.js - Notifications · Toast-style user feedback and alerts
src/hooks/useNotification.js - Login page · Sign-in entry point for the study experience
src/components/LoginPage.js - Studio · Main study workspace orchestrating document, chat, and quiz flows
src/components/Studio.js - Documents · Document selection and source-context management
src/components/DocumentList.js - Sessions · Study session navigation and persistence-aware selection
src/components/ChatSessionList.js - Chat · Conversational interface for AI responses and streaming output
src/components/Chat.js - Quiz view · Rendered quiz generation and practice output
src/components/QuizView.js - Empty state · Fallback screen when no study content is active
src/components/EmptyState.js - Shortcuts · Keyboard shortcuts and interaction hints
src/components/KeyboardShortcuts.js
Flask API
Python backend for AI, persistence, and session APIs
- Backend app · API server entrypoint for AI and persistence workflows
python_backend/app.py - Config · Environment and service configuration for the backend
python_backend/config.py
External services
Third-party and platform dependencies
- Gemini · Google Gemini generation service invoked by the backend
- Database · Durable storage for sessions, messages, and related study state
Connections 23
- SPA shell → App entry: loads · The browser host page loads the React application
- App entry → App frame: mounts · React bootstraps the top-level application shell
- App frame → Auth state: uses · Application shell reads authentication state
- App frame → Theme state: uses · Application shell applies shared theme state
- App frame → Notifications: uses · Global UI surfaces notifications to the user
- Auth state → Login page: gates · Unauthenticated users are routed to sign-in
- Auth state → Studio: unlocks · Authenticated users enter the main workspace
- Studio → Documents: coordinates · Workspace binds selected documents into the study context
- Studio → Sessions: coordinates · Workspace manages active study session selection
- Studio → Chat: hosts · Chat is a central interaction surface in the studio
- Studio → Quiz view: hosts · Quiz generation is part of the study workflow
- Studio → Empty state: falls back to · Empty state appears when no content is selected
- Studio → Shortcuts: exposes · Workspace offers keyboard and UX help
- Chat → Backend app: requests · Chat sends user prompts and receives AI responses via HTTP
- Quiz view → Backend app: requests · Quiz generation is served by the backend API
- Sessions → Backend app: loads · Session metadata and history come from the backend
- Documents → Backend app: loads · Document-related state is mediated by the backend
- Backend app → Config: reads · Server startup and service wiring use runtime config
- Backend app → Gemini: calls · Backend delegates generation to Google Gemini
- Backend app → Database: persists · Backend stores durable session and message data
- Chat → Notifications: triggers · Chat uses notifications for feedback and error states
- Theme state → Login page: styles · Theme state applies across the login experience
- Theme state → Studio: styles · Theme state applies across the main workspace