# xs19895310614/english-learning-agent architecture

> Architecture diagram of the GitHub repository xs19895310614/english-learning-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xs19895310614/english-learning-agent
- Repository: https://github.com/xs19895310614/english-learning-agent

## Overview

English Learning Agent is a Windows-oriented desktop app for spoken-English practice and vocabulary study. A learner sends a message from the React interface; the Electron bridge dispatches it to DeepSeek-backed chat, which uses saved conversation history and persists the exchange. The same interface supports dictionary lookup, enrichment, and saving words, phrases, or sentences as study cards. Lookup prioritizes the local ECDICT database and can fall back to DeepSeek; Collins lookup is a separate capability. IPC and preload wiring is represented from the API contract and file layout; their source was not sampled.

Main entry points: [`electron/ipc.ts`](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/ipc.ts) (IPC handlers), [`electron/dictionary.ts`](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/dictionary.ts) (Lookup router), [`electron/deepseek.ts`](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/deepseek.ts) (Chat service), [`electron/store.ts`](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/store.ts) (User data store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_app["React app<br/>[App.tsx]"]
  node_main["Electron main<br/>[main.ts]"]
  node_preload["Preload bridge<br/>[preload.ts]"]
  node_ipc["IPC handlers<br/>[ipc.ts]"]
end

subgraph group_conversation["Conversation practice"]
  node_chat["Chat service<br/>[deepseek.ts]"]
end

subgraph group_vocabulary["Vocabulary study"]
  node_study_analysis["Card relations<br/>[study-analysis.ts]"]
  node_dictionary["Lookup router<br/>[dictionary.ts]"]
  node_local_dictionary["ECDICT lookup"]
  node_dictionary_db[("ECDICT database")]
  node_collins["Collins lookup<br/>[collins.ts]"]
end

subgraph group_persistence["Local persistence"]
  node_store[("User data store<br/>[store.ts]")]
end

node_learner(("Learner"))
node_deepseek{{"DeepSeek API"}}
node_collins_site{{"Collins Dictionary"}}

node_learner -->|"uses"| node_app
node_main -->|"registers handlers"| node_ipc
node_main -->|"loads bridge"| node_preload
node_main -->|"warms lookup"| node_local_dictionary
node_app -->|"invokes API"| node_preload
node_preload -->|"forwards requests"| node_ipc
node_ipc -->|"dispatches chat"| node_chat
node_chat -->|"requests replies"| node_deepseek
node_chat -->|"reads and writes history"| node_store
node_ipc -->|"dispatches lookup"| node_dictionary
node_dictionary -->|"tries local lookup"| node_local_dictionary
node_local_dictionary -->|"reads entries"| node_dictionary_db
node_dictionary -.->|"requests AI lookup"| node_chat
node_dictionary -->|"reads and writes cache"| node_store
node_ipc -.->|"opens Collins"| node_collins
node_collins -.->|"fetches pages"| node_collins_site
node_collins -->|"reads and writes cache"| node_store
node_ipc -->|"handles card and settings data"| node_store
node_app -->|"finds card relations"| node_study_analysis

click node_app "https://github.com/xs19895310614/english-learning-agent/blob/main/src/App.tsx"
click node_main "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/main.ts"
click node_preload "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/preload.ts"
click node_ipc "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/ipc.ts"
click node_chat "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/deepseek.ts"
click node_study_analysis "https://github.com/xs19895310614/english-learning-agent/blob/main/src/study-analysis.ts"
click node_dictionary "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/dictionary.ts"
click node_local_dictionary "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/local-dictionary.ts"
click node_dictionary_db "https://github.com/xs19895310614/english-learning-agent/tree/main/resources/dictionary"
click node_collins "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/collins.ts"
click node_store "https://github.com/xs19895310614/english-learning-agent/blob/main/electron/store.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_main,node_preload,node_ipc toneBlue
class node_chat toneAmber
class node_study_analysis,node_dictionary,node_local_dictionary,node_dictionary_db,node_collins,node_deepseek toneMint
class node_store toneRose
class node_learner,node_collins_site toneIndigo
```

## Components

### Desktop interface

- [React app](https://github.com/xs19895310614/english-learning-agent/blob/main/src/App.tsx): `src/App.tsx`
- [Electron main](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/main.ts): `electron/main.ts`
- [Preload bridge](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/preload.ts): `electron/preload.ts`
- [IPC handlers](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/ipc.ts): `electron/ipc.ts`

### Conversation practice

- [Chat service](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/deepseek.ts): `electron/deepseek.ts`

### Vocabulary study

- [Card relations](https://github.com/xs19895310614/english-learning-agent/blob/main/src/study-analysis.ts): `src/study-analysis.ts`
- [Lookup router](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/dictionary.ts): `electron/dictionary.ts`
- [ECDICT lookup](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/local-dictionary.ts): `electron/local-dictionary.ts`
- [ECDICT database](https://github.com/xs19895310614/english-learning-agent/tree/main/resources/dictionary): `resources/dictionary`
- [Collins lookup](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/collins.ts): `electron/collins.ts`

### Local persistence

- [User data store](https://github.com/xs19895310614/english-learning-agent/blob/main/electron/store.ts): `electron/store.ts`

### Other components

- **Learner**
- **DeepSeek API**
- **Collins Dictionary**

## Connections

- Learner → React app: uses
- Electron main → IPC handlers: registers handlers
- Electron main → Preload bridge: loads bridge
- Electron main → ECDICT lookup: warms lookup
- React app → Preload bridge: invokes API
- Preload bridge → IPC handlers: forwards requests
- IPC handlers → Chat service: dispatches chat
- Chat service → DeepSeek API: requests replies
- Chat service → User data store: reads and writes history
- IPC handlers → Lookup router: dispatches lookup
- Lookup router → ECDICT lookup: tries local lookup
- ECDICT lookup → ECDICT database: reads entries
- Lookup router → Chat service: requests AI lookup
- Lookup router → User data store: reads and writes cache
- IPC handlers → Collins lookup: opens Collins
- Collins lookup → Collins Dictionary: fetches pages
- Collins lookup → User data store: reads and writes cache
- IPC handlers → User data store: handles card and settings data
- React app → Card relations: finds card relations