# braaaeeedyn/bearlm architecture

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

- Interactive diagram: https://gitdiagram.com/braaaeeedyn/bearlm
- Repository: https://github.com/braaaeeedyn/bearlm

## Overview

BearLM is a cited, grounded Q&A assistant over course materials, with persistent project conversations and ad-hoc PDF chat as additional workflows. Course content is extracted, split, embedded, and stored; questions enter through the web/API, then retrieval and answer generation produce citations or a refusal. Projects add their own PDF collections and can fall back to the course corpus; ad-hoc uploads remain document-only. Analytics records query activity. The README and excerpts establish the main flows; some API, analytics, and project details are unsampled, so uncertain internal links are omitted.

Main entry points: [`src/bearlm/rag.py`](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rag.py) (Answer orchestration), [`src/bearlm/api.py`](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/api.py) (HTTP API), [`src/bearlm/projects.py`](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/projects.py) (Project management), [`src/bearlm/local_store.py`](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py) (Vector collections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Corpus ingestion"]
  node_coursefiles["Course materials"]
  node_extract["Document extraction<br/>[doc_processor.py]"]
  node_split["Text splitting<br/>[text_splitter.py]"]
  node_ingeststore["Corpus ingestion<br/>[local_store.py]"]
  node_vectorstore[("Vector collections<br/>[local_store.py]")]
end

subgraph group_answering["Grounded answering"]
  node_rag["Answer orchestration<br/>[rag.py]"]
  node_retrieval["Hybrid retrieval<br/>[search.py]"]
  node_rerank["Confidence reranking<br/>[rerank.py]"]
  node_generator["Answer model<br/>[rag.py]"]
  node_settings["Backend configuration<br/>[config.py]"]
end

subgraph group_personal["Personal documents"]
  node_projects["Project management<br/>[projects.py]"]
  node_projectdocs["Project PDF ingestion<br/>[local_store.py]"]
  node_uploadchat["Ad-hoc PDF chat<br/>[api.py]"]
end

subgraph group_product["App and analytics"]
  node_webapp["Web interface<br/>[app.js]"]
  node_projectsui["Projects interface<br/>[projects-app.js]"]
  node_api["HTTP API<br/>[api.py]"]
  node_analytics["Usage analytics<br/>[analytics.py]"]
end

node_learner(("Learner"))
node_ollama["Ollama models"]
node_atlas[("MongoDB Atlas")]

node_learner -->|"asks through"| node_webapp
node_learner -->|"manages documents"| node_projectsui
node_webapp -->|"calls"| node_api
node_projectsui -->|"calls"| node_api
node_api -->|"answers via"| node_rag
node_api -->|"routes project actions"| node_projects
node_api -->|"routes upload chat"| node_uploadchat
node_api -->|"records queries"| node_analytics
node_api -->|"serves frontend"| node_webapp
node_coursefiles -->|"provides content"| node_extract
node_extract -->|"extracts pages"| node_ingeststore
node_ingeststore -->|"splits text"| node_split
node_ingeststore -->|"embeds and stores"| node_vectorstore
node_rag -->|"gets candidates"| node_retrieval
node_rag -->|"reranks candidates"| node_rerank
node_rag -->|"generates answer"| node_generator
node_retrieval -->|"searches vectors"| node_vectorstore
node_rerank -->|"scores passages"| node_generator
node_rag -->|"uses local models"| node_ollama
node_rag -.->|"uses OpenAI backend"| node_atlas
node_settings -->|"selects backend"| node_rag
node_projects -->|"ingests project PDFs"| node_projectdocs
node_projectdocs -->|"stores project chunks"| node_vectorstore
node_projects -->|"grounds project answers"| node_rag
node_uploadchat -->|"creates upload collection"| node_projects
node_uploadchat -->|"answers without fallback"| node_rag
node_analytics -.->|"reads corpus stats"| node_vectorstore

click node_webapp "https://github.com/braaaeeedyn/bearlm/blob/main/web/app.js"
click node_projectsui "https://github.com/braaaeeedyn/bearlm/blob/main/web/projects-app.js"
click node_api "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/api.py"
click node_analytics "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/analytics.py"
click node_extract "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/doc_processor.py"
click node_split "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/text_splitter.py"
click node_ingeststore "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py"
click node_vectorstore "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py"
click node_rag "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rag.py"
click node_retrieval "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/search.py"
click node_rerank "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rerank.py"
click node_generator "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rag.py"
click node_projects "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/projects.py"
click node_projectdocs "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py"
click node_uploadchat "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/api.py"
click node_settings "https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/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_coursefiles,node_extract,node_split,node_ingeststore,node_vectorstore toneBlue
class node_rag,node_retrieval,node_rerank,node_generator,node_settings,node_atlas toneAmber
class node_projects,node_projectdocs,node_uploadchat toneMint
class node_webapp,node_projectsui,node_api,node_analytics toneRose
class node_learner,node_ollama toneIndigo
```

## Components

### Corpus ingestion

- **Course materials**
- [Document extraction](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/doc_processor.py): `src/bearlm/doc_processor.py`
- [Text splitting](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/text_splitter.py): `src/bearlm/text_splitter.py`
- [Corpus ingestion](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py): `src/bearlm/local_store.py`
- [Vector collections](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py): `src/bearlm/local_store.py`

### Grounded answering

- [Answer orchestration](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rag.py): `src/bearlm/rag.py`
- [Hybrid retrieval](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/search.py): `src/bearlm/search.py`
- [Confidence reranking](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rerank.py): `src/bearlm/rerank.py`
- [Answer model](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/rag.py): `src/bearlm/rag.py`
- [Backend configuration](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/config.py): `src/bearlm/config.py`

### Personal documents

- [Project management](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/projects.py): `src/bearlm/projects.py`
- [Project PDF ingestion](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/local_store.py): `src/bearlm/local_store.py`
- [Ad-hoc PDF chat](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/api.py): `src/bearlm/api.py`

### App and analytics

- [Web interface](https://github.com/braaaeeedyn/bearlm/blob/main/web/app.js): `web/app.js`
- [Projects interface](https://github.com/braaaeeedyn/bearlm/blob/main/web/projects-app.js): `web/projects-app.js`
- [HTTP API](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/api.py): `src/bearlm/api.py`
- [Usage analytics](https://github.com/braaaeeedyn/bearlm/blob/main/src/bearlm/analytics.py): `src/bearlm/analytics.py`

### Other components

- **Learner**
- **Ollama models**
- **MongoDB Atlas**

## Connections

- Learner → Web interface: asks through (evidence: `README.md`)
- Learner → Projects interface: manages documents (evidence: `README.md`)
- Web interface → HTTP API: calls (evidence: `README.md`)
- Projects interface → HTTP API: calls (evidence: `README.md`)
- HTTP API → Answer orchestration: answers via (evidence: `src/bearlm/api.py`)
- HTTP API → Project management: routes project actions (evidence: `src/bearlm/api.py`)
- HTTP API → Ad-hoc PDF chat: routes upload chat (evidence: `src/bearlm/api.py`)
- HTTP API → Usage analytics: records queries (evidence: `src/bearlm/api.py`)
- HTTP API → Web interface: serves frontend (evidence: `README.md`)
- Course materials → Document extraction: provides content (evidence: `README.md`)
- Document extraction → Corpus ingestion: extracts pages (evidence: `src/bearlm/local_store.py`)
- Corpus ingestion → Text splitting: splits text (evidence: `src/bearlm/local_store.py`)
- Corpus ingestion → Vector collections: embeds and stores (evidence: `README.md`)
- Answer orchestration → Hybrid retrieval: gets candidates (evidence: `src/bearlm/rag.py`)
- Answer orchestration → Confidence reranking: reranks candidates (evidence: `src/bearlm/rag.py`)
- Answer orchestration → Answer model: generates answer (evidence: `src/bearlm/rag.py`)
- Hybrid retrieval → Vector collections: searches vectors (evidence: `src/bearlm/search.py`)
- Confidence reranking → Answer model: scores passages (evidence: `README.md`)
- Answer orchestration → Ollama models: uses local models (evidence: `README.md`)
- Answer orchestration → MongoDB Atlas: uses OpenAI backend (evidence: `README.md`)
- Backend configuration → Answer orchestration: selects backend (evidence: `src/bearlm/rag.py`)
- Project management → Project PDF ingestion: ingests project PDFs (evidence: `src/bearlm/projects.py`)
- Project PDF ingestion → Vector collections: stores project chunks (evidence: `src/bearlm/local_store.py`)
- Project management → Answer orchestration: grounds project answers (evidence: `src/bearlm/projects.py`)
- Ad-hoc PDF chat → Project management: creates upload collection (evidence: `src/bearlm/api.py`)
- Ad-hoc PDF chat → Answer orchestration: answers without fallback (evidence: `src/bearlm/api.py`)
- Usage analytics → Vector collections: reads corpus stats (evidence: `src/bearlm/analytics.py`)
