# nghiathan13/app_vocabulary architecture

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

- Interactive diagram: https://gitdiagram.com/nghiathan13/app_vocabulary
- Repository: https://github.com/nghiathan13/app_vocabulary

## Overview

1. **What this repo is**
   - This is a **desktop app** for learning English vocabulary, not a pure web app.
   - The architecture is a **Tauri shell**: a React + TypeScript frontend runs in a native desktop window, while a Rust backend handles desktop/runtime capabilities and local persistence.

2. **Frontend application shell**
   - The frontend entry points are `index.html`, `src/main.tsx`, and `src/App.tsx`.
   - `App.tsx` is the top-level composition point where the main screens and shared UI are assembled.
   - Styling is mostly component-scoped CSS alongside a global `App.css`.

3. **Primary UI subsystems**
   - The app is organized into major feature areas under `src/components/`:
     - `Home` for landing/overview
     - `Practice` for study mode
     - `Review` for review mode
     - `Insights` for analytics and vocabulary management
     - `Navbar` for cross-screen navigation
     - `Toast` for app-wide feedback messages
   - This suggests a **screen-based desktop workflow** rather than a deeply nested SPA route hierarchy.

4. **Practice and review flow**
   - `Practice` and `Review` are separate feature modules, which implies distinct user flows for active learning and later reinforcement.
   - These screens likely consume the shared vocabulary dataset and present it in different interaction modes.
   - The presence of `src/services/audio.ts` indicates pronunciation or sound playback is part of the learning loop.

5. **Insights and vocabulary management**
   - `src/components/Insights/` is the most complex subsystem.
   - It includes:
     - `Chart` for visual summaries
     - `Table` for listing and editing vocabulary data
     - import-related UI (`Table_Import`)
     - persistence/save UI (`Table_SaveModal`)
     - table actions, grid layout, and search helpers
   - This area functions as the **management console** for the word dataset and its derived analytics.

6. **Data flow for words**
   - `src/services/words.ts` is the likely frontend service boundary for all vocabulary data operations.
   - The frontend does not appear to access storage directly; instead it likely goes through this service layer to read/write words and to keep UI components isolated from persistence details.
   - `src/types.ts` defines the shared data model used across pages, services, and tables.

7. **Local desktop backend**
   - The `src-tauri/` directory is the native side of the app.
   - `src-tauri/src/main.rs` and `src-tauri/src/lib.rs` are the Rust runtime entry points for Tauri commands, setup, and application lifecycle.
   - This backend is where desktop-specific integration and any privileged operations live.

8. **Persistence layer**
   - `src-tauri/migrations/001_create_words.sql` shows the app uses a **local database schema** with at least one `words` table.
   - That strongly suggests vocabulary data is stored locally on the user’s machine, fitting a desktop-first offline architecture.
   - The migration folder implies the schema is managed over time rather than created ad hoc.

9. **Command/boundary model**
   - The architecture likely follows the standard Tauri boundary: **React UI → TypeScript service layer → Tauri commands → Rust backend → local DB/system APIs**.
   - `src/services/words.ts` and `src/services/audio.ts` are the frontend-facing façade for those calls.
   - `src-tauri/capabilities/default.json` indicates the backend capabilities are explicitly constrained, which is important for a secure desktop app.

10. **Shared utilities and cross-cutting concerns**
   - `src/utils.ts` holds reusable helpers used across multiple features.
   - `src/components/Toast/ToastProvider.tsx` provides a global notification mechanism, probably used by import/save/practice actions to surface success or error feedback.
   - This keeps user feedback decoupled from the feature modules.

11. **Build and packaging**
   - Frontend build tooling is **Vite** with TypeScript (`vite.config.ts`, `tsconfig*.json`).
   - The backend is Rust/Cargo (`src-tauri/Cargo.toml`, `Cargo.lock`), with `build.rs` likely handling native build-time setup.
   - `src-tauri/tauri.conf.json` and the icon assets show this is packaged as a native desktop application.

12. **Architecture summary for a diagram**
   - A good diagram would show three main layers:
     - **UI layer**: Home / Practice / Review / Insights / Navbar / Toast
     - **Service layer**: audio + words + shared types/utils
     - **Native layer**: Tauri Rust app + local database migrations
   - The central business object is the **vocabulary word dataset**, which feeds practice, review, charts, and table management.
   - The main external boundary is **local desktop persistence and audio playback**, not a remote server.

Main entry points: [`src/App.tsx`](https://github.com/nghiathan13/app_vocabulary/blob/main/src/App.tsx) (App), [`src/services/words.ts`](https://github.com/nghiathan13/app_vocabulary/blob/main/src/services/words.ts) (Words), [`src/components/Practice/Practice.tsx`](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Practice/Practice.tsx) (Practice), [`src/components/Review/Review.tsx`](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Review/Review.tsx) (Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_main_tsx["main.tsx<br/>ui bootstrap<br/>[main.tsx]"]
  node_app_tsx["App<br/>shell composition<br/>[App.tsx]"]
  node_navbar["Navbar<br/>navigation<br/>[Navbar.tsx]"]
  node_home["Home<br/>landing screen<br/>[Home.tsx]"]
  node_practice["Practice<br/>study screen<br/>[Practice.tsx]"]
  node_review["Review<br/>reinforcement screen<br/>[Review.tsx]"]
  node_insights["Insights<br/>analytics screen<br/>[Insights.tsx]"]
  node_chart["Chart<br/>analytics view<br/>[Chart.tsx]"]
  node_table["Table<br/>data grid<br/>[Table.tsx]"]
  node_toast["Toast<br/>feedback layer<br/>[ToastProvider.tsx]"]
  node_words_service["Words<br/>data service<br/>[words.ts]"]
  node_audio_service["Audio<br/>media service<br/>[audio.ts]"]
end

subgraph group_shared["Shared"]
  node_types["Types<br/>domain model<br/>[types.ts]"]
  node_utils["Utils<br/>helpers<br/>[utils.ts]"]
end

subgraph group_native["Native"]
  node_tauri_runtime["Tauri runtime<br/>rust app<br/>[main.rs]"]
  node_tauri_lib["Backend lib<br/>rust core<br/>[lib.rs]"]
  node_migration["Words schema<br/>db migration"]
end

node_index_html -->|"loads"| node_main_tsx
node_main_tsx -->|"renders"| node_app_tsx
node_app_tsx -->|"composes"| node_navbar
node_app_tsx -->|"shows"| node_home
node_app_tsx -->|"shows"| node_practice
node_app_tsx -->|"shows"| node_review
node_app_tsx -->|"shows"| node_insights
node_app_tsx -->|"provides"| node_toast
node_practice -->|"uses"| node_words_service
node_practice -->|"uses"| node_audio_service
node_review -->|"uses"| node_words_service
node_review -->|"uses"| node_audio_service
node_insights -->|"contains"| node_chart
node_insights -->|"contains"| node_table
node_table -->|"uses"| node_words_service
node_words_service -->|"models"| node_types
node_words_service -->|"invokes"| node_tauri_runtime
node_audio_service -->|"invokes"| node_tauri_runtime
node_tauri_runtime -->|"delegates"| node_tauri_lib
node_tauri_lib -->|"persists"| node_migration
node_app_tsx -->|"uses"| node_utils
node_table -.->|"notifies"| node_toast

click node_index_html "https://github.com/nghiathan13/app_vocabulary/blob/main/index.html"
click node_main_tsx "https://github.com/nghiathan13/app_vocabulary/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/nghiathan13/app_vocabulary/blob/main/src/App.tsx"
click node_navbar "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Navbar/Navbar.tsx"
click node_home "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Home/Home.tsx"
click node_practice "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Practice/Practice.tsx"
click node_review "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Review/Review.tsx"
click node_insights "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Insights.tsx"
click node_chart "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Chart/Chart.tsx"
click node_table "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Table/Table.tsx"
click node_toast "https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Toast/ToastProvider.tsx"
click node_words_service "https://github.com/nghiathan13/app_vocabulary/blob/main/src/services/words.ts"
click node_audio_service "https://github.com/nghiathan13/app_vocabulary/blob/main/src/services/audio.ts"
click node_types "https://github.com/nghiathan13/app_vocabulary/blob/main/src/types.ts"
click node_utils "https://github.com/nghiathan13/app_vocabulary/blob/main/src/utils.ts"
click node_tauri_runtime "https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/src/main.rs"
click node_tauri_lib "https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/src/lib.rs"
click node_migration "https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/migrations/001_create_words.sql"

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_index_html,node_main_tsx,node_app_tsx,node_navbar,node_home,node_practice,node_review,node_insights,node_chart,node_table,node_toast,node_words_service,node_audio_service toneBlue
class node_types,node_utils toneAmber
class node_tauri_runtime,node_tauri_lib,node_migration toneMint
```

## Components

### Frontend

React + TypeScript desktop UI

- [index.html](https://github.com/nghiathan13/app_vocabulary/blob/main/index.html): entry page · Desktop app mount point · `index.html`
- [main.tsx](https://github.com/nghiathan13/app_vocabulary/blob/main/src/main.tsx): ui bootstrap · React application entry · `src/main.tsx`
- [App](https://github.com/nghiathan13/app_vocabulary/blob/main/src/App.tsx): shell composition · Top-level screen assembly · `src/App.tsx`
- [Navbar](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Navbar/Navbar.tsx): navigation · Cross-screen navigation · `src/components/Navbar/Navbar.tsx`
- [Home](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Home/Home.tsx): landing screen · Overview and start point · `src/components/Home/Home.tsx`
- [Practice](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Practice/Practice.tsx): study screen · Active vocabulary practice · `src/components/Practice/Practice.tsx`
- [Review](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Review/Review.tsx): reinforcement screen · Review and repetition flow · `src/components/Review/Review.tsx`
- [Insights](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Insights.tsx): analytics screen · Vocabulary management and analytics · `src/components/Insights/Insights.tsx`
- [Chart](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Chart/Chart.tsx): analytics view · Visual summaries of word data · `src/components/Insights/Chart/Chart.tsx`
- [Table](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Insights/Table/Table.tsx): data grid · List, edit, import, save words · `src/components/Insights/Table/Table.tsx`
- [Toast](https://github.com/nghiathan13/app_vocabulary/blob/main/src/components/Toast/ToastProvider.tsx): feedback layer · App-wide notifications · `src/components/Toast/ToastProvider.tsx`
- [Words](https://github.com/nghiathan13/app_vocabulary/blob/main/src/services/words.ts): data service · Frontend boundary for vocabulary operations · `src/services/words.ts`
- [Audio](https://github.com/nghiathan13/app_vocabulary/blob/main/src/services/audio.ts): media service · Pronunciation and sound playback · `src/services/audio.ts`

### Shared

Cross-cutting models and helpers

- [Types](https://github.com/nghiathan13/app_vocabulary/blob/main/src/types.ts): domain model · Shared vocabulary data shapes · `src/types.ts`
- [Utils](https://github.com/nghiathan13/app_vocabulary/blob/main/src/utils.ts): helpers · Reusable cross-feature helpers · `src/utils.ts`

### Native

Tauri Rust backend and local persistence

- [Tauri runtime](https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/src/main.rs): rust app · Desktop shell and command host · `src-tauri/src/main.rs`
- [Backend lib](https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/src/lib.rs): rust core · Tauri setup and command wiring · `src-tauri/src/lib.rs`
- [Words schema](https://github.com/nghiathan13/app_vocabulary/blob/main/src-tauri/migrations/001_create_words.sql): db migration · Local words table schema · `src-tauri/migrations/001_create_words.sql`

## Connections

- index.html → main.tsx: loads · Browser window mounts the React app
- main.tsx → App: renders · Bootstraps the top-level UI shell
- App → Navbar: composes · Shared navigation across screens
- App → Home: shows · Landing and overview screen
- App → Practice: shows · Active learning flow
- App → Review: shows · Reinforcement flow
- App → Insights: shows · Management and analytics workspace
- App → Toast: provides · Global feedback channel
- Practice → Words: uses · Reads and updates study data
- Practice → Audio: uses · Plays pronunciation audio
- Review → Words: uses · Consumes vocab set for review
- Review → Audio: uses · Supports listening feedback
- Insights → Chart: contains · Analytics visualization
- Insights → Table: contains · Vocabulary management UI
- Table → Words: uses · Import, save, and edit operations
- Words → Types: models · Shared vocabulary domain types
- Words → Tauri runtime: invokes · Crosses the desktop backend boundary
- Audio → Tauri runtime: invokes · Uses native runtime capabilities
- Tauri runtime → Backend lib: delegates · Backend setup and command handling
- Backend lib → Words schema: persists · Local database schema for words
- App → Utils: uses · Shared UI and data helpers
- Table → Toast: notifies · Save/import feedback