Relevant source files

The following files were used as context for generating this wiki page: - [src/utils/db/dexie/app-db.ts](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/db/dexie/app-db.ts) - [src/utils/db/dexie/tables/translation-cache.ts](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/db/dexie/tables/translation-cache.ts) - [src/utils/db/dexie/tables/article-summary-cache.ts](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/db/dexie/tables/article-summary-cache.ts) - [src/utils/db/dexie/tables/batch-request-record.ts](https://github.com/mengxi-ream/read-frog/blob/main/src/utils/db/dexie/tables/batch-request-record.ts) - [src/entrypoints/background/mock-data.ts](https://github.com/mengxi-ream/read-frog/blob/main/src/entrypoints/background/mock-data.ts) - [CLAUDE.md](https://github.com/mengxi-ream/read-frog/blob/main/CLAUDE.md)

# Database Schema (Dexie.js) The Read Frog extension utilizes Dexie.js, a minimalist wrapper for IndexedDB, to manage local data persistence. This client-side database is crucial for caching data such as translation results, article summaries, and AI request records. The primary goals are to improve performance by reducing redundant API calls, enhance user experience with faster data retrieval, and provide some offline functionality. The database is named `${upperCamelCase(APP_NAME)}DB`, where `APP_NAME` is "read-frog", resulting in the database name `ReadFrogDB`. The implementation follows a versioned schema approach, allowing for seamless upgrades as the application evolves. *Sources: [src/utils/db/dexie/app-db.ts:4,19](), [CLAUDE.md:104]()* ## Database Architecture The database is managed through the `AppDB` class, which extends `Dexie`. This class defines the database schema, including its tables and versions. Each table is represented by a corresponding class that maps to the table's structure. *Sources: [src/utils/db/dexie/app-db.ts:9]()* ### Class Diagram The following diagram illustrates the relationship between the main `AppDB` class and the entity classes for each table. ```mermaid classDiagram direction LR class Dexie { <> } class AppDB { +translationCache: EntityTable~TranslationCache~ +batchRequestRecord: EntityTable~BatchRequestRecord~ +articleSummaryCache: EntityTable~ArticleSummaryCache~ +constructor() } class TranslationCache { <> key: string translation: string createdAt: Date } class BatchRequestRecord { <> key: string createdAt: Date originalRequestCount: number provider: string model: string } class ArticleSummaryCache { <> key: string summary: string createdAt: Date } Dexie <|-- AppDB AppDB o-- TranslationCache AppDB o-- BatchRequestRecord AppDB o-- ArticleSummaryCache ``` *Sources: [src/utils/db/dexie/app-db.ts:9-20](), [src/utils/db/dexie/tables/translation-cache.ts](), [src/utils/db/dexie/tables/batch-request-record.ts](), [src/utils/db/dexie/tables/article-summary-cache.ts]()* ### Entity Relationship Diagram This diagram shows the tables and their fields within the IndexedDB database. There are no explicit relationships defined between the tables; they function as independent collections of documents. ```mermaid erDiagram translationCache { string key PK "Primary Key" string translation Date createdAt } batchRequestRecord { string key PK "Primary Key" Date createdAt number originalRequestCount string provider string model } articleSummaryCache { string key PK "Primary Key" string summary Date createdAt } ``` *Sources: [src/utils/db/dexie/app-db.ts:21-42](), [src/utils/db/dexie/tables/translation-cache.ts](), [src/utils/db/dexie/tables/batch-request-record.ts](), [src/utils/db/dexie/tables/article-summary-cache.ts]()* ## Database Versioning The database schema is versioned to handle migrations and updates. The `AppDB` constructor defines the schema for each version. *Sources: [src/utils/db/dexie/app-db.ts:20-42]()* ```typescript // src/utils/db/dexie/app-db.ts:20-42 export default class AppDB extends Dexie { // ... constructor() { super(`${upperCamelCase(APP_NAME)}DB`) this.version(1).stores({ translationCache: ` key, translation, createdAt`, }) this.version(2).stores({ translationCache: ` key, translation, createdAt`, batchRequestRecord: ` key, createdAt, originalRequestCount, provider, model`, }) this.version(3).stores({ translationCache: ` key, translation, createdAt`, batchRequestRecord: ` key, createdAt, originalRequestCount, provider, model`, articleSummaryCache: ` key, createdAt`, }) // ... } } ``` The versioning flow introduces new tables incrementally without losing existing data. ```mermaid graph TD subgraph DB Versions v1["Version 1"] --> v2["Version 2"] v2 --> v3["Version 3"] end subgraph Tables T1[translationCache] T2[batchRequestRecord] T3[articleSummaryCache] end v1 -- "Introduces" --> T1 v2 -- "Introduces" --> T2 v3 -- "Introduces" --> T3 ``` ### Version History | Version | Tables Added/Modified - | Description - | | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `translationCache` - | Initial schema with a single table for caching translations. - | | 2 | `batchRequestRecord` - | Adds a table to record batch AI requests. `translationCache` is retained. - | | 3 | `articleSummaryCache` - | Adds a table for caching article summaries. `translationCache` and `batchRequestRecord` are retained. - | *Sources: [src/utils/db/dexie/app-db.ts:21-42]()* ## Table Schemas ### `translationCache` This table stores cached translations to avoid re-requesting the same translation from an API. | Field | Type | Indexes | Description | | :------------ | :------- | :----------- | :---------------------------------------- | | `key` | `string` | Primary Key | A unique key for the translation request. | | `translation` | `string` | - | The translated text. | | `createdAt` | `Date` | Indexed | Timestamp of when the cache entry was created. | *Sources: [src/utils/db/dexie/app-db.ts:22-25](), [src/utils/db/dexie/tables/translation-cache.ts]()* ### `batchRequestRecord` This table logs records of batch requests made to AI providers, likely for analytics or debugging purposes. | Field | Type | Indexes | Description | | :--------------------- | :------- | :---------- | :---------------------------------------- | | `key` | `string` | Primary Key | A unique key for the batch request. | | `createdAt` | `Date` | Indexed | Timestamp of when the record was created. | | `originalRequestCount` | `number` | Indexed | The number of original requests in the batch. | | `provider` | `string` | Indexed | The AI provider used for the request. | | `model` | `string` | Indexed | The specific AI model used. | *Sources: [src/utils/db/dexie/app-db.ts:29-34](), [src/utils/db/dexie/tables/batch-request-record.ts]()* ### `articleSummaryCache` This table caches summaries of articles generated by the AI. | Field | Type | Indexes | Description | | :---------- | :------- | :---------- | :---------------------------------------- | | `key` | `string` | Primary Key | A unique key for the article summary. The key is a `Sha256Hex` of the content hash and provider config. | | `summary` | `string` | - | The cached summary text. | | `createdAt` | `Date` | Indexed | Timestamp of when the cache entry was created. | *Sources: [src/utils/db/dexie/app-db.ts:38-41](), [src/utils/db/dexie/tables/article-summary-cache.ts]()* ## Data Management ### Mock Data Initialization During development, if the `WXT_MOCK_DATA` environment variable is set to `'true'`, the application can populate the `batchRequestRecord` table with mock data. This is handled by the `initMockData` function, which checks if records already exist before generating new ones. This is useful for testing features that rely on database records without manual setup. *Sources: [src/entrypoints/background/mock-data.ts:8-22]()*