Skip to content

⚙️ Centralized Settings & Configuration Guide ​

Flashcard Master uses a Centralized System Settings Architecture that eliminates scattered, hardcoded configuration and replaces static .env dependencies with a dynamic, local-first settings studio backed by SQLite.


🏛️ 3-Tier Configuration Precedence Hierarchy ​

Whenever Flashcard Master resolves a setting or integration parameter, it evaluates values through a strict three-tier precedence hierarchy:

┌────────────────────────────────────────────────────────┐
│  Tier 1: SQLite Key-Value Table (`app_settings`)       │
│  (Configured interactively via Web UI Settings Studio) │
└──────────────────────────┬─────────────────────────────┘
                           │ Fallback if empty
                           ▼
┌────────────────────────────────────────────────────────┐
│  Tier 2: Environment Variables (`process.env`)         │
│  (Supplied via `.env` file, Docker env, or shell)      │
└──────────────────────────┬─────────────────────────────┘
                           │ Fallback if undefined
                           ▼
┌────────────────────────────────────────────────────────┐
│  Tier 3: Safe Hardcoded Code Defaults                  │
│  (Safe, resilient application fallbacks)               │
└────────────────────────────────────────────────────────┘
  1. SQLite Database (app_settings): Any setting adjusted by the user in the Web UI or via the REST API is persisted immediately to the SQLite database. This takes the highest priority.
  2. Environment Variables (process.env): If a setting has never been configured in SQLite (or was deleted/reset), Flashcard Master checks standard environment variable aliases (useful for headless servers, Docker containers, and CI pipelines).
  3. Hardcoded Defaults: If neither SQLite nor environment variables specify a value, the system applies safe, battle-tested defaults.

Dynamic Runtime Application (Zero Server Restarts) ​

Changes to general settings (such as worker pool concurrency limits, task timeouts, or AnkiConnect connection endpoints) apply immediately at runtime:

  • Active worker managers adjust dispatch queues without dropping pending tasks.
  • The AnkiConnect export adapter uses a dynamic resolver to connect to the new endpoint on the next request.
  • The AI Generation Studio reads updated defaults whenever a new session starts.

📋 Comprehensive Settings Registry ​

The following table lists all settings managed by the Centralized Settings Service:

Setting KeyEnvironment Variable(s)Default ValueClamping / ValidationDescription
ankiconnect_urlANKI_CONNECT_URL, ANKICONNECT_URLhttp://127.0.0.1:8765Valid HTTP/HTTPS URLEndpoint URL for the AnkiConnect desktop add-on.
ankiconnect_api_keyANKI_CONNECT_API_KEY, ANKICONNECT_API_KEYnullMasked tokenOptional security key configured in AnkiConnect apiKey.
ankiconnect_timeout_msANKI_CONNECT_TIMEOUT_MS3000Integer $\ge 500$ msConnection timeout for AnkiConnect HTTP requests.
default_ai_providerDEFAULT_AI_PROVIDERollamaollama, openai, gemini, anthropicDefault LLM provider pre-selected in Generate Studio.
default_ai_modelDEFAULT_AI_MODELphi4-miniNon-empty stringDefault model identifier pre-selected in Generate Studio.
default_personaDEFAULT_PERSONAsocratic-mentorValid persona keyDefault cognitive persona used for card generation prompt.
default_difficultyDEFAULT_DIFFICULTYintermediatebeginner, intermediate, expertDefault target difficulty level for cards.
default_card_limitDEFAULT_CARD_LIMIT5Clamped 1–50Default number of flashcards to generate per batch.
default_grounding_enforcedDEFAULT_GROUNDING_ENFORCEDtrueBoolean (true/false)Whether strict verbatim quote verification is enabled by default.
max_generation_workersMAX_GENERATION_WORKERS, WORKER_CONCURRENCY2Clamped 1–16Maximum simultaneous background worker threads for AI generation jobs.
max_sync_workersMAX_SYNC_WORKERS2Clamped 1–16Maximum simultaneous background worker threads for source ingestion jobs.
max_export_workersMAX_EXPORT_WORKERS2Clamped 1–16Maximum simultaneous background worker threads for deck/doc export jobs.
worker_timeout_minutesWORKER_TIMEOUT_MINUTES15Clamped 0–120 min (0 = infinite)Maximum execution duration before an unresponsive worker job is terminated. Set to 0 to disable automatic timeout for long-running batches.
default_slicing_modeDEFAULT_SLICING_MODEoutlineoutline, budgetDefault slicing mode for large documents (Semantic Headings vs Page/Word Budget).
default_page_budgetDEFAULT_PAGE_BUDGET10Integer $\ge 1$Default page or section budget size when budget slicing is active.
epub_default_authorEPUB_DEFAULT_AUTHORFlashcard MasterNon-empty stringDefault author metadata written to generated EPUB eBook study guides.
epub_default_publisherEPUB_DEFAULT_PUBLISHERFlashcard MasterNon-empty stringDefault publisher metadata written to generated EPUB eBook study guides.
default_stt_providerDEFAULT_STT_PROVIDERopenaiopenai, gemini, whisper-localDefault Speech-to-Text provider pre-selected for new Audio, Video, and YouTube media items.
local_whisper_modelLOCAL_WHISPER_MODELbasetiny, base, small, medium, large-v3Model preset used when transcribing with Local Whisper (whisper-local).
local_whisper_endpointLOCAL_WHISPER_ENDPOINT, WHISPER_BINARY_PATH, WHISPER_CPP_PATH""HTTP URL or binary pathOptional whisper.cpp HTTP server URL (e.g. http://localhost:8080) or local CLI binary path.
default_subtitle_languageDEFAULT_SUBTITLE_LANGUAGEenISO 639-1 codePreferred subtitle/caption language code (e.g. en, ro, es) when fetching YouTube tracks.

🔒 Secret Management & Tokens ​

API keys for external services (OpenAI, Anthropic, Google Gemini, Ollama host, and Notion) are managed in SQLite:

  • Masking: Tokens are never transmitted to the browser in plaintext (e.g. sk-pro...8f90 or ••••••••).
  • Validation: Live "Test Connection" buttons in the Web UI allow instant diagnosis of credentials without saving invalid keys.
  • Worker Injection: Active credentials are dynamically injected into isolated worker subprocesses per job.

🖥️ Using the Settings Studio in the Web UI ​

Access the Settings Studio at http://127.0.0.1:3000/#/settings.

1. Visual Source Badges ​

Every configuration card displays an origin badge indicating where the current active value originated:

  • 🟢 Database: Set by you and persisted in SQLite.
  • 🔵 Env: VARIABLE_NAME: Sourced from an environment variable or .env file.
  • ⚪ Default: Using the built-in system default.

2. Anki Desktop Integration & Live Health Check ​

  • Change the AnkiConnect URL if running Anki on a different machine, local VM, or WSL (e.g. http://host.docker.internal:8765).
  • Supply an optional API Key token with a convenient Show/Hide and Clear toggle.
  • Click ⚡ Test Connection to send an instant ping:
    • If Anki is running: displays Connected with detected version (e.g. Version 6) and round-trip latency (e.g. 12ms).
    • If Anki is closed or unreachable: displays an error badge explaining that AnkiConnect was refused.

3. AI Generation Defaults ​

Adjust your preferred default Provider, Model name, Persona, Difficulty, and Batch limit. When you open Generate Studio, these settings automatically pre-populate the synthesizer form.

4. Worker Pool & Concurrency ​

Tune worker thread concurrency limits (1 to 16) and execution timeouts (0 to 120 minutes, where 0 disables timeout for long-running batches) based on your hardware capabilities and CPU core count. When set to 0, worker tasks run indefinitely until finished or manually cancelled via the Task Center.

5. Speech-to-Text & Media Defaults + Dependency Readiness ​

Configure your default Speech-to-Text provider (openai, gemini, or whisper-local), Local Whisper model (tiny–large-v3) and endpoint/binary path, and preferred subtitle language (en, ro, es, etc.). These defaults automatically pre-fill new media items in the Add Data Source modal.

Use the 🔍 Media & STT Dependency Readiness panel in Settings ➔ General ➔ Speech-to-Text & Media Defaults to verify at a glance whether ffmpeg, yt-dlp, whisper-local, OpenAI STT, and Gemini STT are ready on your machine.


🌐 REST API Endpoints ​

Programmatic access to settings is available via the REST API:

GET /api/settings/general ​

Returns all general settings along with their effective values and source metadata:

json
{
  "settings": {
    "ankiconnectUrl": "http://127.0.0.1:8765",
    "ankiconnectApiKey": "••••••••",
    "ankiconnectTimeoutMs": 10000,
    "defaultAiProvider": "ollama",
    "defaultAiModel": "phi4-mini",
    "defaultPersona": "socratic-mentor",
    "defaultDifficulty": "intermediate",
    "defaultCardLimit": 5,
    "defaultGroundingEnforced": true,
    "maxGenerationWorkers": 2,
    "maxSyncWorkers": 2,
    "maxExportWorkers": 2,
    "workerTimeoutMinutes": 15,
    "defaultSlicingMode": "outline",
    "defaultPageBudget": 10,
    "epubDefaultAuthor": "Flashcard Master",
    "epubDefaultPublisher": "Flashcard Master",
    "defaultSttProvider": "openai",
    "localWhisperModel": "base",
    "localWhisperEndpoint": "",
    "defaultSubtitleLanguage": "en"
  },
  "sources": {
    "ankiconnectUrl": { "type": "default" },
    "defaultAiModel": { "type": "database" },
    "maxGenerationWorkers": { "type": "env", "envVar": "MAX_GENERATION_WORKERS" }
  }
}

PUT /api/settings/general ​

Updates one or more general settings in SQLite:

json
{
  "ankiconnectUrl": "http://192.168.1.100:8765",
  "defaultCardLimit": 10,
  "maxGenerationWorkers": 4
}

POST /api/settings/anki/test ​

Performs an active health check ping against AnkiConnect:

json
// Optional body override:
{ "url": "http://127.0.0.1:8765", "apiKey": "optional-key" }

// Response:
{
  "connected": true,
  "version": 6,
  "latencyMs": 14
}

GET /api/settings/media/diagnostics ​

Probes local media dependencies (ffmpeg, yt-dlp, whisper-local) and cloud STT API key configuration:

json
{
  "ffmpeg": { "available": true, "version": "7.1" },
  "ytDlp": { "available": true, "mode": "system" },
  "whisperLocal": { "available": false, "mode": "unconfigured" },
  "openaiStt": { "configured": true },
  "geminiStt": { "configured": false }
}

Released under the GNU Affero General Public License v3.0 (AGPL-3.0).