# jerrygoodboi/aurenlm architecture

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

- Interactive diagram: https://gitdiagram.com/jerrygoodboi/aurenlm
- Repository: https://github.com/jerrygoodboi/aurenlm

## Overview

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: [`src/components/Studio.js`](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/Studio.js) (Studio), [`python_backend/app.py`](https://github.com/jerrygoodboi/aurenlm/blob/main/python_backend/app.py) (Backend app), [`src/App.js`](https://github.com/jerrygoodboi/aurenlm/blob/main/src/App.js) (App frame), [`src/AuthContext.js`](https://github.com/jerrygoodboi/aurenlm/blob/main/src/AuthContext.js) (Auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_public_shell["SPA shell<br/>static host<br/>[index.html]"]
  node_app_entry["App entry<br/>react bootstrap<br/>[index.js]"]
  node_app_frame["App frame<br/>react shell<br/>[App.js]"]
  node_auth_ctx(("Auth state<br/>react context<br/>[AuthContext.js]"))
  node_theme_ctx(("Theme state<br/>react context<br/>[ThemeContext.js]"))
  node_notify_hook(("Notifications<br/>ui hook<br/>[useNotification.js]"))
  node_login_page["Login page<br/>auth view<br/>[LoginPage.js]"]
  node_studio["Studio<br/>workspace<br/>[Studio.js]"]
  node_documents["Documents<br/>document panel<br/>[DocumentList.js]"]
  node_sessions["Sessions<br/>session panel<br/>[ChatSessionList.js]"]
  node_chat["Chat<br/>ai interaction<br/>[Chat.js]"]
  node_quiz["Quiz view<br/>study artifact<br/>[QuizView.js]"]
  node_empty_state["Empty state<br/>ui state<br/>[EmptyState.js]"]
  node_shortcuts["Shortcuts<br/>ux help"]
end

subgraph group_backend["Flask API"]
  node_backend_app["Backend app<br/>flask entrypoint<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
end

subgraph group_external["External services"]
  node_gemini{{"Gemini<br/>external AI"}}
  node_database[("Database<br/>persistent storage")]
end

node_public_shell -->|"loads"| node_app_entry
node_app_entry -->|"mounts"| node_app_frame
node_app_frame -->|"uses"| node_auth_ctx
node_app_frame -->|"uses"| node_theme_ctx
node_app_frame -->|"uses"| node_notify_hook
node_auth_ctx -->|"gates"| node_login_page
node_auth_ctx -->|"unlocks"| node_studio
node_studio -->|"coordinates"| node_documents
node_studio -->|"coordinates"| node_sessions
node_studio -->|"hosts"| node_chat
node_studio -->|"hosts"| node_quiz
node_studio -->|"falls back to"| node_empty_state
node_studio -->|"exposes"| node_shortcuts
node_chat -->|"requests"| node_backend_app
node_quiz -->|"requests"| node_backend_app
node_sessions -->|"loads"| node_backend_app
node_documents -->|"loads"| node_backend_app
node_backend_app -->|"reads"| node_backend_config
node_backend_app -->|"calls"| node_gemini
node_backend_app -->|"persists"| node_database
node_chat -->|"triggers"| node_notify_hook
node_theme_ctx -->|"styles"| node_login_page
node_theme_ctx -->|"styles"| node_studio

click node_public_shell "https://github.com/jerrygoodboi/aurenlm/blob/main/public/index.html"
click node_app_entry "https://github.com/jerrygoodboi/aurenlm/blob/main/src/index.js"
click node_app_frame "https://github.com/jerrygoodboi/aurenlm/blob/main/src/App.js"
click node_auth_ctx "https://github.com/jerrygoodboi/aurenlm/blob/main/src/AuthContext.js"
click node_theme_ctx "https://github.com/jerrygoodboi/aurenlm/blob/main/src/ThemeContext.js"
click node_notify_hook "https://github.com/jerrygoodboi/aurenlm/blob/main/src/hooks/useNotification.js"
click node_login_page "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/LoginPage.js"
click node_studio "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/Studio.js"
click node_documents "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/DocumentList.js"
click node_sessions "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/ChatSessionList.js"
click node_chat "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/Chat.js"
click node_quiz "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/QuizView.js"
click node_empty_state "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/EmptyState.js"
click node_shortcuts "https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/KeyboardShortcuts.js"
click node_backend_app "https://github.com/jerrygoodboi/aurenlm/blob/main/python_backend/app.py"
click node_backend_config "https://github.com/jerrygoodboi/aurenlm/blob/main/python_backend/config.py"

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_public_shell,node_app_entry,node_app_frame,node_auth_ctx,node_theme_ctx,node_notify_hook,node_login_page,node_studio,node_documents,node_sessions,node_chat,node_quiz,node_empty_state,node_shortcuts toneBlue
class node_backend_app,node_backend_config toneAmber
class node_gemini,node_database toneMint
```

## Components

### React SPA

Browser-based study experience and UI state

- [SPA shell](https://github.com/jerrygoodboi/aurenlm/blob/main/public/index.html): static host · Browser entry page and manifest for the React app · `public/index.html`
- [App entry](https://github.com/jerrygoodboi/aurenlm/blob/main/src/index.js): react bootstrap · Top-level React mount and application startup · `src/index.js`
- [App frame](https://github.com/jerrygoodboi/aurenlm/blob/main/src/App.js): react shell · Global application composition and routing shell · `src/App.js`
- [Auth state](https://github.com/jerrygoodboi/aurenlm/blob/main/src/AuthContext.js): react context · Manages authentication and active user/session identity · `src/AuthContext.js`
- [Theme state](https://github.com/jerrygoodboi/aurenlm/blob/main/src/ThemeContext.js): react context · Coordinates light/dark theme across the UI · `src/ThemeContext.js`
- [Notifications](https://github.com/jerrygoodboi/aurenlm/blob/main/src/hooks/useNotification.js): ui hook · Toast-style user feedback and alerts · `src/hooks/useNotification.js`
- [Login page](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/LoginPage.js): auth view · Sign-in entry point for the study experience · `src/components/LoginPage.js`
- [Studio](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/Studio.js): workspace · Main study workspace orchestrating document, chat, and quiz flows · `src/components/Studio.js`
- [Documents](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/DocumentList.js): document panel · Document selection and source-context management · `src/components/DocumentList.js`
- [Sessions](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/ChatSessionList.js): session panel · Study session navigation and persistence-aware selection · `src/components/ChatSessionList.js`
- [Chat](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/Chat.js): ai interaction · Conversational interface for AI responses and streaming output · `src/components/Chat.js`
- [Quiz view](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/QuizView.js): study artifact · Rendered quiz generation and practice output · `src/components/QuizView.js`
- [Empty state](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/EmptyState.js): ui state · Fallback screen when no study content is active · `src/components/EmptyState.js`
- [Shortcuts](https://github.com/jerrygoodboi/aurenlm/blob/main/src/components/KeyboardShortcuts.js): ux help · Keyboard shortcuts and interaction hints · `src/components/KeyboardShortcuts.js`

### Flask API

Python backend for AI, persistence, and session APIs

- [Backend app](https://github.com/jerrygoodboi/aurenlm/blob/main/python_backend/app.py): flask entrypoint · API server entrypoint for AI and persistence workflows · `python_backend/app.py`
- [Config](https://github.com/jerrygoodboi/aurenlm/blob/main/python_backend/config.py): runtime config · Environment and service configuration for the backend · `python_backend/config.py`

### External services

Third-party and platform dependencies

- **Gemini**: external AI · Google Gemini generation service invoked by the backend
- **Database**: persistent storage · Durable storage for sessions, messages, and related study state

## Connections

- 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
