# open-spaced-repetition/ts-fsrs architecture

> Architecture diagram of the GitHub repository open-spaced-repetition/ts-fsrs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-spaced-repetition/ts-fsrs
- Repository: https://github.com/open-spaced-repetition/ts-fsrs

## Overview

##### Project Type and Purpose
- This project is a scheduling library, implementing the Free Spaced Repetition Scheduler (FSRS) algorithm in TypeScript for use in flashcard or spaced repetition applications.
- The package supports various module systems (ES modules, CommonJS, UMD) and is meant to be integrated into other applications that require spaced repetition scheduling.
- The README highlights usage examples, parameter configuration, and core API functions for scheduling cards based on user ratings.

##### File Structure
- Top-level Directories/Files:
- The .github directory: Contains funding, dependabot, and CI workflows (ci.yml, deploy.yml, npm-publish.yml) indicating a well-managed CI/CD pipeline.
- __tests__: Contains extensive unit tests for various functionalities, including the FSRS algorithm, strategies, and implementation-specific tests.
- src/fsrs: The heart of the library, with separate modules for abstract scheduling, core algorithm, conversion utilities, default behavior, multiple implementations (basic and long-term schedulers), and strategies.
- debug and example directories: Provide testing and usage demonstration, with demo components in both HTML and JSX files.
- Configuration files (tsconfig.json, rollup.config.ts, eslint, prettier, etc.) indicate a properly structured TypeScript project ready for building and publishing.
- The structure follows a modular design where the core algorithm, its strategies, and its different scheduler implementations (through abstraction and concrete classes) are clearly separated.

##### Insights from the README
- The README shows real-world usage examples for creating cards, configuring parameters via generatorParameters, and scheduling them with fsrs and its various methods.
- It also details the core data models (Card and ReviewLog) and logs the scheduling process based on different user ratings.

a. Main Components to Include:
- Client/Application Code: Illustrate how a consumer (e.g., a flashcard application or demo client) imports and utilizes the ts-fsrs API.
- FSRS Core Module: The primary component (src/fsrs) which houses the domain logic for scheduling.
- Parameter Generator: The generatorParameters function/module used to configure scheduling parameters.
- Card and ReviewLog Data Models: Represent the state encapsulation for flashcards and their associated review logs.
- Abstract Scheduler & Strategy Components: Separate modules for the abstract scheduler interface, its basic implementation (src/fsrs/impl/basic_scheduler.ts), long-term scheduler (src/fsrs/impl/long_term_scheduler.ts), and strategies logic (src/fsrs/strategies).
- Utility Modules: Additional modules like algorithm computations, conversion utilities, and help/documentation functions.
- Testing and Debug: Optional but useful to include testing (from __tests__) and debug (from debug/) paths to show how these modules relate to the core functionality.

b. Relationships and Interactions:
- External integrations (such as CI workflows and package publishing) to denote how changes propagate through the build/deploy system.

c. Architectural Patterns & Design Principles:
- Modular design where separate concerns—like scheduling logic, parameter configuration, and logging—are well isolated.
- Use of abstraction (with an abstract scheduler) and strategy patterns (allowing different scheduling algorithms or adaptations such as basic vs. long term).
- Testability, using a dedicated __tests__ folder where unit tests confirm the correctness of each component.

d. Relevant Technologies:
- TypeScript for strong typing and maintainability.
- Node.js environment (with Node version dependencies as mentioned in the README).
- Module systems (ES Modules, CommonJS, UMD) which illustrate how the library is consumed in different contexts.
- Build tools and linters (rollup, eslint, prettier) that support robust development.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client/Application Code"]:::client
    end

    %% FSRS Domain
    subgraph "FSRS Domain"
        FSRS["FSRS Core Module"]:::core
        Param["Parameter Generator"]:::util
        Data["Data Models (Card & ReviewLog)"]:::models
        AbsSched["Abstract Scheduler"]:::scheduler
        BasicSched["Basic Scheduler Implementation"]:::scheduler
        LongSched["Long-Term Scheduler Implementation"]:::scheduler
        Strategies["Strategies Module"]:::strategy
        Utils["Utility Modules"]:::util
    end

    %% Testing and Debug
    subgraph "Testing and Debug"
        Test["Testing Suite"]:::test
        Debug["Debug/Usage Demonstrations"]:::debug
    end

    %% Build and CI Pipeline
    subgraph "Build and CI"
        CI["Build/CI Pipeline"]:::ci
    end

    %% Connections
    Client -->|"calls"| FSRS
    FSRS -->|"configuresWith"| Param
    FSRS -->|"updates"| Data
    FSRS -->|"delegatesTo"| AbsSched
    FSRS -->|"applies"| Strategies
    FSRS -->|"utilizes"| Utils
    AbsSched -->|"implementsUsing"| BasicSched
    AbsSched -->|"implementsUsing"| LongSched
    BasicSched -->|"updates"| Data
    LongSched -->|"updates"| Data
    Strategies -->|"guides"| BasicSched
    Strategies -->|"guides"| LongSched
    Test -->|"validates"| FSRS
    Test -->|"validates"| AbsSched
    CI -->|"deploys"| FSRS
    CI -->|"runsTestsOn"| Test
    Debug -->|"supports"| Client

    %% Click Events for Client/Application Code
    click Client "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/example/example.html"
    click Client "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/example/example.jsx"
    click Client "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/example/exampleComponent.jsx"

    %% Click Events for FSRS Core Module
    click FSRS "https://github.com/open-spaced-repetition/ts-fsrs/tree/main/src/fsrs"
    click FSRS "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/fsrs.ts"

    %% Click Event for Parameter Generator
    click Param "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/default.ts"

    %% Click Event for Data Models
    click Data "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/models.ts"

    %% Click Event for Abstract Scheduler
    click AbsSched "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/abstract_scheduler.ts"

    %% Click Event for Basic Scheduler Implementation
    click BasicSched "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/impl/basic_scheduler.ts"

    %% Click Event for Long-Term Scheduler Implementation
    click LongSched "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/impl/long_term_scheduler.ts"

    %% Click Events for Strategies Module
    click Strategies "https://github.com/open-spaced-repetition/ts-fsrs/tree/main/src/fsrs/strategies"
    click Strategies "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/strategies/index.ts"
    click Strategies "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/strategies/seed.ts"

    %% Click Events for Utility Modules
    click Utils "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/algorithm.ts"
    click Utils "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/convert.ts"
    click Utils "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/src/fsrs/help.ts"

    %% Click Events for Testing Suite
    click Test "https://github.com/open-spaced-repetition/ts-fsrs/tree/main/__tests__"
    click Test "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/__tests__/FSRSV5.test.ts"
    click Test "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/__tests__/impl/basic_scheduler.test.ts"

    %% Click Events for Build/CI Pipeline
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/tree/main/.github/workflows"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/.github/workflows/deploy.yml"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/.github/workflows/npm-publish.yml"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/rollup.config.ts"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/tsconfig.json"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/eslint.config.mjs"
    click CI "https://github.com/open-spaced-repetition/ts-fsrs/blob/main/.prettierrc.json"

    %% Click Event for Debug Directory
    click Debug "https://github.com/open-spaced-repetition/ts-fsrs/tree/main/debug"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef core fill:#FFF4B2,stroke:#000,stroke-width:2px;
    classDef util fill:#C2EABD,stroke:#000,stroke-width:2px;
    classDef models fill:#F7C6C7,stroke:#000,stroke-width:2px;
    classDef scheduler fill:#D1B2FF,stroke:#000,stroke-width:2px;
    classDef strategy fill:#FFC1C1,stroke:#000,stroke-width:2px;
    classDef test fill:#FFF2CC,stroke:#000,stroke-width:2px;
    classDef ci fill:#D5E8D4,stroke:#000,stroke-width:2px;
    classDef debug fill:#E0E0E0,stroke:#000,stroke-width:2px;
```
