# vanshraj07/brain-memory architecture

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

- Interactive diagram: https://gitdiagram.com/vanshraj07/brain-memory
- Repository: https://github.com/vanshraj07/brain-memory

## Overview

BrainWave is an AI-assisted second-brain app for saving notes and links, organizing them as memories, searching by semantic relevance, and asking Gemini questions against retrieved context. The main flow is an authenticated user adding a memory, the API enriching and embedding it before persistence, then searching to retrieve related memories and request an AI answer. The graph captures sampled calls and README-described capabilities; website/YouTube previews and some client routes are documented or visible, but unsampled wiring is not inferred.

Main entry points: [`src/Routes/user.ts`](https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts) (User API routes), [`src/components/AfterSearchMainApp.jsx`](https://github.com/vanshraj07/brain-memory/blob/main/src/components/AfterSearchMainApp.jsx) (Search results), [`src/components/MainAppHome.jsx`](https://github.com/vanshraj07/brain-memory/blob/main/src/components/MainAppHome.jsx) (Memory home), [`src/components/MemoryCard.jsx`](https://github.com/vanshraj07/brain-memory/blob/main/src/components/MemoryCard.jsx) (Memory cards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route shell<br/>[App.jsx]"]
  node_home["Memory home<br/>[MainAppHome.jsx]"]
  node_search["Search entry<br/>[SearchBar.jsx]"]
  node_add["Add memory form<br/>[Modal.jsx]"]
  node_card["Memory cards<br/>[MemoryCard.jsx]"]
  node_results["Search results"]
  node_state["Client memory state<br/>[atoms.js]"]
  node_auth["Sign-in and signup<br/>[SignIn.jsx]"]
end

subgraph group_api["API and identity"]
  node_api_entry["API server<br/>[index.ts]"]
  node_routes["User API routes<br/>[user.ts]"]
  node_middleware["JWT middleware<br/>[user.ts]"]
end

subgraph group_memory["Memory services"]
  node_db[("MongoDB models<br/>[db.ts]")]
  node_scrape["Link enrichment<br/>[helper.ts]"]
  node_embed["Semantic embeddings<br/>[helper.ts]"]
  node_retrieval["Relevant memory retrieval<br/>[user.ts]"]
  node_gemini["Contextual Q&amp;A<br/>[user.ts]"]
end

subgraph group_integrations["External services"]
  node_mongodb[("MongoDB")]
  node_google["Google Gemini API"]
  node_website["Websites and YouTube"]
end

node_user(("User"))

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_auth
node_app -->|"routes to"| node_results
node_home -->|"loads memories"| node_state
node_home -->|"renders"| node_search
node_home -->|"renders"| node_add
node_home -->|"renders"| node_card
node_search -->|"navigates"| node_results
node_search -->|"sets query"| node_state
node_add -->|"posts memory"| node_routes
node_add -->|"updates list"| node_state
node_card -->|"updates bookmark"| node_routes
node_card -->|"deletes memory"| node_routes
node_card -->|"updates list"| node_state
node_results -->|"requests matches"| node_routes
node_results -->|"requests answer"| node_routes
node_results -->|"renders matches"| node_card
node_results -->|"reads query"| node_state
node_api_entry -->|"mounts routes"| node_routes
node_routes -->|"authenticates"| node_middleware
node_middleware -->|"sets user identity"| node_routes
node_routes -->|"reads and writes"| node_db
node_db -.->|"persists models"| node_mongodb
node_routes -->|"enriches links"| node_scrape
node_routes -->|"creates vectors"| node_embed
node_retrieval -->|"loads memories"| node_db
node_retrieval -->|"embeds query"| node_embed
node_routes -->|"handles search"| node_retrieval
node_routes -->|"generates answer"| node_gemini
node_gemini -->|"sends prompt"| node_google
node_scrape -.->|"fetches previews"| node_website
node_user -->|"signs in"| node_auth
node_user -->|"searches memories"| node_search
node_user -->|"submits memory"| node_add

click node_app "https://github.com/vanshraj07/brain-memory/blob/main/src/App.jsx"
click node_home "https://github.com/vanshraj07/brain-memory/blob/main/src/components/MainAppHome.jsx"
click node_search "https://github.com/vanshraj07/brain-memory/blob/main/src/components/SearchBar.jsx"
click node_add "https://github.com/vanshraj07/brain-memory/blob/main/src/components/Modal.jsx"
click node_card "https://github.com/vanshraj07/brain-memory/blob/main/src/components/MemoryCard.jsx"
click node_results "https://github.com/vanshraj07/brain-memory/blob/main/src/components/AfterSearchMainApp.jsx"
click node_state "https://github.com/vanshraj07/brain-memory/blob/main/atoms.js"
click node_auth "https://github.com/vanshraj07/brain-memory/blob/main/src/components/SignIn.jsx"
click node_api_entry "https://github.com/vanshraj07/brain-memory/blob/main/src/index.ts"
click node_routes "https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts"
click node_middleware "https://github.com/vanshraj07/brain-memory/blob/main/src/middlewares/user.ts"
click node_db "https://github.com/vanshraj07/brain-memory/blob/main/src/db.ts"
click node_scrape "https://github.com/vanshraj07/brain-memory/blob/main/src/Scraping/helper.ts"
click node_embed "https://github.com/vanshraj07/brain-memory/blob/main/src/Scraping/helper.ts"
click node_retrieval "https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts"
click node_gemini "https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts"

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_app,node_home,node_search,node_add,node_card,node_results,node_state,node_auth,node_user toneBlue
class node_api_entry,node_routes,node_middleware toneAmber
class node_db,node_scrape,node_embed,node_retrieval,node_gemini toneMint
class node_mongodb,node_google,node_website toneRose
```

## Components

### Web client

- [Route shell](https://github.com/vanshraj07/brain-memory/blob/main/src/App.jsx): `src/App.jsx`
- [Memory home](https://github.com/vanshraj07/brain-memory/blob/main/src/components/MainAppHome.jsx): `src/components/MainAppHome.jsx`
- [Search entry](https://github.com/vanshraj07/brain-memory/blob/main/src/components/SearchBar.jsx): `src/components/SearchBar.jsx`
- [Add memory form](https://github.com/vanshraj07/brain-memory/blob/main/src/components/Modal.jsx): `src/components/Modal.jsx`
- [Memory cards](https://github.com/vanshraj07/brain-memory/blob/main/src/components/MemoryCard.jsx): `src/components/MemoryCard.jsx`
- [Search results](https://github.com/vanshraj07/brain-memory/blob/main/src/components/AfterSearchMainApp.jsx): `src/components/AfterSearchMainApp.jsx`
- [Client memory state](https://github.com/vanshraj07/brain-memory/blob/main/atoms.js): `atoms.js`
- [Sign-in and signup](https://github.com/vanshraj07/brain-memory/blob/main/src/components/SignIn.jsx): `src/components/SignIn.jsx`

### API and identity

- [API server](https://github.com/vanshraj07/brain-memory/blob/main/src/index.ts): `src/index.ts`
- [User API routes](https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts): `src/Routes/user.ts`
- [JWT middleware](https://github.com/vanshraj07/brain-memory/blob/main/src/middlewares/user.ts): `src/middlewares/user.ts`

### Memory services

- [MongoDB models](https://github.com/vanshraj07/brain-memory/blob/main/src/db.ts): `src/db.ts`
- [Link enrichment](https://github.com/vanshraj07/brain-memory/blob/main/src/Scraping/helper.ts): `src/Scraping/helper.ts`
- [Semantic embeddings](https://github.com/vanshraj07/brain-memory/blob/main/src/Scraping/helper.ts): `src/Scraping/helper.ts`
- [Relevant memory retrieval](https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts): `src/Routes/user.ts`
- [Contextual Q&A](https://github.com/vanshraj07/brain-memory/blob/main/src/Routes/user.ts): `src/Routes/user.ts`

### External services

- **MongoDB**
- **Google Gemini API**
- **Websites and YouTube**

### Other components

- **User**

## Connections

- User → Route shell: opens (evidence: `src/App.jsx`)
- Route shell → Memory home: routes to (evidence: `src/App.jsx`)
- Route shell → Sign-in and signup: routes to (evidence: `src/App.jsx`)
- Route shell → Search results: routes to (evidence: `src/App.jsx`)
- Memory home → Client memory state: loads memories (evidence: `src/components/MainAppHome.jsx`)
- Memory home → Search entry: renders (evidence: `src/components/MainAppHome.jsx`)
- Memory home → Add memory form: renders (evidence: `src/components/MainAppHome.jsx`)
- Memory home → Memory cards: renders (evidence: `src/components/MainAppHome.jsx`)
- Search entry → Search results: navigates (evidence: `src/components/SearchBar.jsx`)
- Search entry → Client memory state: sets query (evidence: `src/components/SearchBar.jsx`)
- Add memory form → User API routes: posts memory (evidence: `src/components/Modal.jsx`)
- Add memory form → Client memory state: updates list (evidence: `src/components/Modal.jsx`)
- Memory cards → User API routes: updates bookmark (evidence: `src/components/MemoryCard.jsx`)
- Memory cards → User API routes: deletes memory (evidence: `src/components/MemoryCard.jsx`)
- Memory cards → Client memory state: updates list (evidence: `src/components/MemoryCard.jsx`)
- Search results → User API routes: requests matches (evidence: `src/components/AfterSearchMainApp.jsx`)
- Search results → User API routes: requests answer (evidence: `src/components/AfterSearchMainApp.jsx`)
- Search results → Memory cards: renders matches (evidence: `src/components/AfterSearchMainApp.jsx`)
- Search results → Client memory state: reads query (evidence: `src/components/AfterSearchMainApp.jsx`)
- API server → User API routes: mounts routes (evidence: `src/index.ts`)
- User API routes → JWT middleware: authenticates (evidence: `src/Routes/user.ts`)
- JWT middleware → User API routes: sets user identity (evidence: `src/middlewares/user.ts`)
- User API routes → MongoDB models: reads and writes (evidence: `src/Routes/user.ts`)
- MongoDB models → MongoDB: persists models
- User API routes → Link enrichment: enriches links (evidence: `src/Routes/user.ts`)
- User API routes → Semantic embeddings: creates vectors (evidence: `src/Routes/user.ts`)
- Relevant memory retrieval → MongoDB models: loads memories (evidence: `src/Routes/user.ts`)
- Relevant memory retrieval → Semantic embeddings: embeds query (evidence: `src/Routes/user.ts`)
- User API routes → Relevant memory retrieval: handles search (evidence: `src/Routes/user.ts`)
- User API routes → Contextual Q&A: generates answer (evidence: `src/Routes/user.ts`)
- Contextual Q&A → Google Gemini API: sends prompt (evidence: `src/Routes/user.ts`)
- Link enrichment → Websites and YouTube: fetches previews (evidence: `README.md`)
- User → Sign-in and signup: signs in
- User → Search entry: searches memories (evidence: `src/components/SearchBar.jsx`)
- User → Add memory form: submits memory (evidence: `src/components/Modal.jsx`)
