ποΈ Flashcard Master Architecture & System Design β
Document Version: 1.0.0
Target Audience: Core Contributors, System Architects & Extension Developers
1. Architectural Philosophy & Invariants β
Flashcard Master is built on five non-negotiable core invariants:
- Local-First & Zero Telemetry: All data sources, extracted articles, vector hashes, settings, and flashcards reside strictly on the user's local disk in SQLite (
~/.flashcard-master/data.sqlite). No telemetry or user content is ever sent to external cloud servers (except direct user-configured LLM API calls). - Strict Factual Grounding (Zero Hallucinations): Every flashcard MUST cite an exact, verbatim substring from the source document. Flashcards with altered, paraphrased, or hallucinated quotes are automatically rejected by
GroundingGuard. - Ports & Adapters (Hexagonal Architecture): Domain logic and core services are isolated from infrastructure. Database engines, LLMs, ingestion protocols, and exporters are swappable ports.
- Adaptive Synthesis & Density Guarantee: When card generation is requested, the system uses oversampling and bounded backfill loops to guarantee the exact target card quota is delivered even when ungrounded drafts are discarded.
- Minimal Information Principle: Questions prioritize atomic active recall, structured cognitive calibration (Beginner, Intermediate, Expert), and customizable learning personas.
2. Monorepo Package Topology β
graph TD
DESKTOP["@flashcard-master/desktop<br/>(Electron, System Tray, Unified DB)"]
CLI["@flashcard-master/cli<br/>(Commander.js, Inquirer.js, App Context)"]
WEB["@flashcard-master/web<br/>(Node.js REST API Server + Svelte 5 Client)"]
ADAPTERS["@flashcard-master/adapters<br/>(Ingestion, LLMs, Exporters)"]
CORE["@flashcard-master/core<br/>(Domain Models, Storage, Services, Ports)"]
DESKTOP --> CORE
DESKTOP --> ADAPTERS
DESKTOP --> WEB
DESKTOP --> CLI
CLI --> CORE
CLI --> ADAPTERS
CLI --> WEB
WEB --> CORE
WEB --> ADAPTERS
ADAPTERS --> COREPackage Responsibilities: β
| Package | Role | Key Components |
|---|---|---|
@flashcard-master/core | Domain Kernel & Data Access | Flashcard, DataSource, CleanTextDocument, CardGenerationService, DocumentSlicingEngine, SubtitleParser, TextChunker, PromptBuilder, GroundingGuard, CardDeduplicationService, SpeechToTextPort, FlashcardRepository, DataSourceRepository, SyncStateRepository, DocumentRepository, createDatabaseClient. |
@flashcard-master/adapters | External Protocols & Vendor SDKs | RssIngestionStrategy, WebReaderStrategy, LocalFileStrategy, AudioIngestionStrategy, VideoIngestionStrategy, YouTubeIngestionStrategy, AudioTrimmer, OpenAiSttAdapter, GeminiSttAdapter, LocalWhisperSttAdapter, EpubParser, SitemapIngestionStrategy, LlmsTxtIngestionStrategy, OllamaAdapter, OpenAIAdapter, GeminiAdapter, AnthropicAdapter, AnkiPackageExporter, AnkiConnectAdapter, MarkdownExporter, HtmlStudyGuideExporter, PdfStudyGuideExporter, CsvExporter, TsvExporter. |
@flashcard-master/cli | Headless CLI & Terminal Wizards | createCli(), createAppContext(), Interactive Setup Wizard, Commands (init, source, sync, generate, export, cards, serve). |
@flashcard-master/web | Local SPA & REST Backend | createWebServer(), server.ts HTTP router, Svelte 5 single-page application (DashboardView, SourcesView, GenerateStudio, QuestionExplorer, ExportCenter). |
@flashcard-master/desktop | Standalone Cross-Platform Desktop App | bootstrapDesktopServer(), Electron main process (main.ts), custom dark slate window framing, system tray minimize/restore, unified ~/.flashcard-master/ data storage, and multi-OS electron-builder packaging (.exe, .dmg, .AppImage, .deb). |
3. Detailed Subsystem Lifecycles β
3.1 Ingestion & Document Pipeline β
sequenceDiagram
participant User/Timer as User / CLI / Web UI
participant IngestionSvc as IngestionService
participant Strategy as IngestionStrategyPort
participant SourceRepo as DataSourceRepository
participant SyncRepo as SyncStateRepository
participant DocRepo as DocumentRepository
User/Timer->>IngestionSvc: syncSource(sourceId)
IngestionSvc->>SourceRepo: getById(sourceId)
IngestionSvc->>SyncRepo: get(sourceId)
IngestionSvc->>Strategy: fetch(source, lastSync)
Strategy-->>IngestionSvc: RawDocument[]
loop Each Raw Document
IngestionSvc->>Strategy: extractCleanText(rawDoc)
Strategy-->>IngestionSvc: CleanTextDocument
IngestionSvc->>DocRepo: upsertDocument(cleanDoc)
end
IngestionSvc->>SyncRepo: recordSync(sourceId, itemCount, hash)
IngestionSvc-->>User/Timer: SyncResult (newCount, totalDocuments)3.2 AI Card Generation & Verification Pipeline β
sequenceDiagram
participant Studio as Generate Studio / CLI
participant GenSvc as CardGenerationService
participant Chunker as TextChunker
participant Prompt as PromptBuilder
participant LLM as LLMProviderPort
participant Guard as GroundingGuard
participant Dedup as CardDeduplicationService
participant CardRepo as FlashcardRepository
Studio->>GenSvc: generateFromDocument(doc, options)
GenSvc->>Chunker: chunkText(doc.textContent, chunkMultiplier)
Chunker-->>GenSvc: Chunks[] (1x, 2x, 3x, or Full Doc)
loop Each Text Chunk
GenSvc->>Prompt: buildGenerationInstructions(targetCount + 2, depthMode, difficulty)
GenSvc->>LLM: generateQAPairs(chunk, prompt)
LLM-->>GenSvc: CandidateDrafts[]
GenSvc->>Guard: filterValidDrafts(CandidateDrafts, chunk)
Guard-->>GenSvc: ValidDrafts[] (Exact Verbatim Substring Verified)
opt If ValidDrafts < targetCount (Adaptive Backfill)
loop Up to 5 Backfill Attempts
GenSvc->>Prompt: buildGenerationInstructions(deficit + 1)
GenSvc->>LLM: generateQAPairs(chunk, retryPrompt)
GenSvc->>Guard: filterValidDrafts(retryDrafts, chunk)
end
end
end
GenSvc->>Dedup: filterUnique(allDrafts, existingDeckCards)
GenSvc->>CardRepo: createBatch(uniqueCards)
CardRepo-->>Studio: Generated Flashcards with Provenance4. SQLite Database Schema & Migration Invariants β
The database client uses better-sqlite3 with Write-Ahead Logging (WAL) mode enabled. Schema migrations in [packages/core/src/storage/db.ts](file:///C:/Users/aprodan/Workspace/Projects/flashcard-master/packages/core/src/storage/db.ts) run automatically on boot.
Core Tables: β
-- 1. Ingestion Sources (Knowledge-First, decoupled from flashcard decks)
CREATE TABLE data_sources (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
type TEXT NOT NULL CHECK(type IN ('rss', 'web', 'local', 'sitemap', 'llms-txt', 'notion')),
uri TEXT NOT NULL,
tags TEXT NOT NULL DEFAULT '[]',
is_active INTEGER NOT NULL DEFAULT 1,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
);
-- 2. Discovered Documents Catalog
CREATE TABLE documents (
id TEXT PRIMARY KEY,
source_id TEXT NOT NULL REFERENCES data_sources(id) ON DELETE CASCADE,
title TEXT NOT NULL,
url TEXT,
text_content TEXT,
content_hash TEXT,
word_count INTEGER DEFAULT 0,
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
);
-- 3. Sync State Metadata
CREATE TABLE sync_state (
source_id TEXT PRIMARY KEY REFERENCES data_sources(id) ON DELETE CASCADE,
last_synced_at TEXT NOT NULL,
last_guid TEXT,
content_hash TEXT,
item_count INTEGER NOT NULL DEFAULT 0
);
-- 4. Flashcards Database (Deck routing designated at generation time)
CREATE TABLE flashcards (
id TEXT PRIMARY KEY,
source_id TEXT REFERENCES data_sources(id) ON DELETE SET NULL,
question TEXT NOT NULL,
answer TEXT NOT NULL,
source_quote TEXT NOT NULL,
source_origin_url TEXT,
document_title TEXT,
keywords TEXT NOT NULL DEFAULT '[]',
source_locator TEXT NOT NULL DEFAULT '',
difficulty TEXT NOT NULL CHECK(difficulty IN ('beginner', 'intermediate', 'expert', 'mixed')),
persona_used TEXT NOT NULL DEFAULT 'socratic-mentor',
target_deck TEXT NOT NULL DEFAULT 'Default',
tags TEXT NOT NULL DEFAULT '[]',
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
);
CREATE INDEX idx_flashcards_created_at_id ON flashcards(created_at DESC, id DESC);
CREATE INDEX idx_flashcards_target_deck ON flashcards(target_deck);
CREATE INDEX idx_flashcards_difficulty ON flashcards(difficulty);
-- 5. System Settings & Credentials Store
CREATE TABLE app_settings (
key TEXT PRIMARY KEY,
value TEXT NOT NULL,
updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
);5. Keyset / Cursor Pagination & Infinite Scrolling β
Flashcard Master implements high-performance keyset / cursor-based pagination for browsing large flashcard collections in the Question Explorer:
Client (IntersectionObserver) βββΆ GET /api/cards?limit=25&cursor=<base64> βββΆ SQLite Keyset Seek- Keyset Query: Paginated queries seek directly on the composite index
(created_at DESC, id DESC):sqlWHERE ((created_at < :cursorCreatedAt) OR (created_at = :cursorCreatedAt AND id < :cursorId)) ORDER BY created_at DESC, id DESC LIMIT :limit + 1; - Opaque Cursor: The cursor is a compact, URL-safe base64 token encoding
{ c: createdAt, i: id }. - Zero Offset Degradation: Cursor pagination performs an $O(1)$ index seek regardless of page depth and is completely immune to page drift or duplicate items caused by concurrent card creation or deletion.
- Backward Compatibility:
GET /api/cardscontinues to return flatFlashcard[]arrays when pagination parameters are omitted, and supportsoffsetqueries as a legacy fallback.
6. Centralized Settings & Configuration Precedence β
Flashcard Master unifies application configurations through SettingsService in @flashcard-master/core. It follows a strict 3-tier precedence hierarchy:
SQLite app_settings βββΆ process.env Fallback βββΆ Hardcoded Default- Dynamic Resolvers: Components such as
AnkiConnectAdapterandJobManageraccept dynamic settings resolvers, enabling instant runtime updates (e.g., changing AnkiConnect port or worker pool concurrency) without restarting the Node.js server. - Secret Protection: API keys and sensitive tokens are masked when sent over REST endpoints and never output to console logs.
- Origin Metadata: Every configuration item tracks its effective origin (
database,env, ordefault), exposed directly to the UI with visual source badges. For a complete registry of configuration keys, see Centralized Settings & Configuration Guide.
7. Deck Operations & Lifecycle Management β
To support flexible study workflows and prevent deck sprawl, Flashcard Master provides atomic, transactional deck manipulation utilities implemented in FlashcardRepository:
Question Explorer UI βββΆ REST Endpoints βββΆ FlashcardRepository (SQLite WAL Transaction)- Deck Cloning (
cloneDeck):POST /api/decks/clone({ sourceDeck, targetDeck })- Duplicates all cards from a source deck into a new target deck with fresh UUIDs.
- Preserves verbatim source quotes, difficulty ratings, tags, keywords, and document origin metadata.
- Executes inside an atomic SQLite transaction (
this.db.transaction()), ensuring all-or-nothing execution.
- Batch Splitting (
splitDeck):POST /api/decks/split({ sourceDeck, batchSize, customPrefix? })- Automatically partitions a large deck into numbered bite-sized sub-decks (e.g.,
${prefix} - Part 1,${prefix} - Part 2). - Ideal for pacing study sessions across multiple days or modules.
- Selective Card Moving (
moveCards):POST /api/decks/move-cards({ cardIds, targetDeck })- Selectively relocates a chosen subset of flashcards from Question Explorer into an existing or newly created deck.
- Updates
target_deckand refreshesupdated_attimestamps transactionally.
8. Exporter Architecture β
Flashcard Master uses an open ExporterRegistry. Exporters implement:
export interface ExporterPort {
readonly format: string;
export(cards: Flashcard[], options?: ExportOptions): Promise<ExportResult>;
}- Anki Package Exporter (
apkg): Builds.apkgSQLite bundles usingsql.jswith front/back templates, CSS styling, and Anki schema tables (col,notes,cards). - AnkiConnect Exporter (
ankiconnect): Communicates with running Anki Desktop instances via HTTP (http://127.0.0.1:8765), creating decks and callingaddNotes. - Markdown Exporter (
markdown): Formats cards into active-recall collapsible<details><summary>HTML blocks. - HTML / Printable PDF Exporter (
html/pdf): Produces a clean 2-column printable study guide with@media printCSS layout, folding cut lines, and browser "Save as PDF" optimization. - Delimited Exporters (
csv/tsv): Exports standard RFC-4180 Anki-compatible delimited text.
Partial, Date-Filtered & Randomized Export Engine β
Flashcard Master supports granular scoping and stochastic subsampling across all export formats, the AnkiConnect live sync integration, the headless CLI, and the web interface:
- Card Filtering Criteria (
CardFilter):createdAfter/createdBefore: ISO 8601 timestamp comparisons (YYYY-MM-DDTHH:mm:ssZorYYYY-MM-DDauto-expanded to start/end of day UTC) evaluated directly againstflashcards.created_at.limit: Numerical upper bound capping the exported card count.shuffle: Enables SQLiteORDER BY RANDOM()for true uniform stochastic subsampling when paired withlimit.
- Exporter Format Independence:
- Because
ExportServicedelegates card fetching directly tocardRepo.list(filter)prior to format rendering, all exporters (apkg,epub,markdown,html,pdf,csv,tsv) inherit date range filtering, card budget limits, and random shuffling with zero format-specific changes.
- Because
- REST Endpoints:
GET /api/export&GET /api/export/:format: Accepts query parametersdeck,tag,after/createdAfter,before/createdBefore,limit, andshuffle=true. Returns HTTP 404 with a structured error message if filter criteria match 0 cards.POST /api/ankiconnect/sync: Accepts JSON body{ targetDeck?, tag?, createdAfter?, createdBefore?, limit?, shuffle? }to push scoped and randomized subsets directly to Anki Desktop.
- Headless CLI:
flashcard-master export <format> [--deck <name>] [--after <date>] [--before <date>] [--limit <number>] [--shuffle] [--output <path>]
- Interactive UI (
ExportCenter.svelte):- "Time & Scope Filter" accordion card with one-click date range presets (All Time, Last 24 Hours, Last 7 Days, Last 30 Days, Custom Range), custom date pickers, card limit budget input, uniform shuffle toggle, and reactive matching cards counter.
9. Data Source Management & Tag Organization β
Flashcard Master organizes knowledge sources with an interactive, normalized tag taxonomy across both data source creation and editing workflows:
Client (TagInput.svelte) βββΆ GET /api/sources/tags βββΆ DataSourceRepository.listAllTags() (SQLite)- Tag Normalization Invariants:
- All tags are trimmed, lowercased, and stripped of leading hash (
#) symbols upon ingestion and entry. - Tags within a data source are automatically deduplicated into a set.
- Stored as a clean JSON string array in
data_sources.tags.
- All tags are trimmed, lowercased, and stripped of leading hash (
- Distinct Tag Discovery (
listAllTags):GET /api/sources/tagsreturns a sorted array of all unique, lowercased tags currently used across active and inactive sources.- Enables instant auto-suggest dropdowns in the user interface as users type.
- Interactive Tag Input (
TagInput.svelte):- Reusable pill-based input component supporting full keyboard navigation:
Enteror,(comma): commits the current text as a new tag pill.Backspaceon empty input: removes the preceding tag pill.ArrowUp/ArrowDown: highlights auto-suggestions from the filtered list.Escape: dismisses the suggestion dropdown.- Pill removal button (
β): immediately deletes individual tags.
- Reusable pill-based input component supporting full keyboard navigation:
10. Asynchronous Subdocument Generation via Task Center β
Flashcard Master unifies targeted card generation across individual subdocuments, chapters, and sliced sections into the asynchronous background worker queue:
Inspector UI βββΆ POST /api/generate (async) βββΆ JobManager (Worker Queue) βββΆ Task Center (SSE Live Stream)- Non-Blocking User Experience:
- Generating cards for an individual document from
SourceDocumentInspector.svelteimmediately enqueues a background task (HTTP 202 Accepted). - The in-context configuration modal closes instantly, returning control to the user.
- The Task Center drawer opens to the Active Tasks tab, expanding the new task so users can observe step progress, token counts, and streamed cards in real time.
- Generating cards for an individual document from
- Document Metadata & Provenance:
- Single-document generation jobs track
documentIds,sourceIds, anddocumentTitledirectly within job metadata. - Job titles dynamically reflect target document names (e.g.,
Synthesize flashcards: "Chapter 1: Overview").
- Single-document generation jobs track
- Reactive Completion & Badge Refresh:
- Client components subscribe to task completion events through
taskStore.onJobCompleted(listener). - When a generation task finishes in the background worker pool,
SourceDocumentInspectordetects that documents in the current source were updated and automatically refreshes card counts without requiring a manual browser refresh.
- Client components subscribe to task completion events through
11. Responsive Layout & Text Overflow Hardening Standards β
To ensure a seamless user experience across diverse desktop displays, laptops, and mobile screens, Flashcard Master adheres to strict responsive layout and text overflow invariants across all user interfaces:
Fluid Viewports (320px ββΆ 4K) βββΆ Auto-Clamped Grids & Drawers βββΆ Independent Scroll Containers- Dynamic Grid Columns:
- Card grids (e.g.,
QuestionExplorer.svelte) utilizerepeat(auto-fill, minmax(min(100%, 360px), 1fr))rather than fixed minimum pixel widths. On screens narrower than 360px, cards scale fluidly down to 100% of the viewport width without causing horizontal spill or clipping.
- Card grids (e.g.,
- Unbroken Token & Word-Break Safety:
- Technical strings such as long URLs, composite IDs, and source locators enforce
min-width: 0,overflow-wrap: break-word, andword-break: break-word. Flex and grid child items are given explicitmin-width: 0constraints so the browser allows elements to shrink below their internal content size.
- Technical strings such as long URLs, composite IDs, and source locators enforce
- Collapsible Quote Grounding:
- In
QuestionExplorer.svelte, verbatim source quotes exceeding 180 characters are clamped to 3 lines (-webkit-line-clamp: 3) with a dedicated "βΌ Show more" / "β² Show less" button. This keeps card geometry consistent while ensuring complete citations remain fully accessible on demand.
- In
- Preformatted Text & Table Containers:
- In markdown reader views and raw content inspectors (e.g.,
DocumentPreviewModal.svelte), all<pre>,<code>, and<table>blocks enforcemax-width: 100%,box-sizing: border-box, and independent horizontal scrollbars (overflow-x: auto). Tables and code snippets scroll cleanly within their respective viewports rather than pushing modals beyond screen boundaries.
- In markdown reader views and raw content inspectors (e.g.,
- Viewport-Clamped Modals & Drawers:
- Slide-over drawers (
CardEditorDrawer,TaskCenterDrawer,SourceDocumentInspector) enforce fluid width clamps (max-width: min(520px - 680px, 100vw)),box-sizing: border-box, and responsive mobile padding via@media (max-width: 640px). - Document and modal dialogs constrain outer dimensions to
max-width: min(860px, 95vw)with responsive margin and padding adjustments on mobile viewports.
- Slide-over drawers (
- Document Trays & Deep Path Resiliency:
- In
GenerateStudio.svelte, document items in source tree trays use flex-shrink limits,min-width: 0on title and info containers, and viewport-aware URL truncations (max-width: min(220px, 35vw)) with full URL tooltips on hover.
- In
12. Generate Studio Target Scope Redesign & Modal Document Picker β
Flashcard Master replaces nested accordion dropdowns in Generate Studio (GenerateStudio.svelte) with prominent Source Scope Cards and a dedicated Document Picker Modal (SourceDocumentPickerModal.svelte):
Target Scope (Studio) βββΆ Source Scope Cards βββΆ [Select Documents...] βββΆ SourceDocumentPickerModal
β β β
βΌ βΌ βΌ
Select All / Clear Status Pills Search & Filter Mode
(Global Selection) (All, Partial, or None) (Apply to generateStore)- Source Scope Cards (
GenerateStudio.svelte):- Replaces nested accordion trees and scroll-trapped lists with clear, scannable cards representing each active data source.
- Displays source type badge (
EPUB,PDF,Web Article, etc.), source title, and search match badges. - Dynamically computes and displays status pills:
β All N docs selected (~X words)π― M of N docs selected (~X words)βͺ 0 of N docs selected
- Inline quick actions: checkbox toggle for whole source,
Select All, andClear. - Prominent
π Select Documents...button triggers focused modal document curation.
- Focused Document Selector Modal (
SourceDocumentPickerModal.svelte):- Dedicated full-featured modal dialog allowing users to curate documents from large catalogs (e.g. 50+ EPUB chapters or sliced PDF documents) without cluttering or stretching the generation studio form.
- Multi-token search bar with normalization, singular/plural tolerance, and stop-word filtering.
- Filter mode tabs:
All,Selected, andUnselected. - Bulk helpers:
Select All Visible,Clear Visible,Select All in Source, andClear All. - Scannable document rows with checkboxes, page coordinate badges, word count estimates, and card generation history.
- Sticky footer with live selection counters and atomic
Apply Selectionbutton that syncs directly withgenerateStore.selectedDocIdsandgenerateStore.selectedSourceIds.
- Responsive Fluid Design:
- Adapts to mobile devices (
@media (max-width: 640px)) with stacked controls, full viewport bounds (100vw/100vh), and touch-friendly targets.
- Adapts to mobile devices (
13. Deck Operations, Partial Slicing & Selective Export Engine β
Flashcard Master provides advanced deck lifecycle and granular scoping operations:
Question Explorer βββΆ Clone Deck βββΆ Atomic Duplicate with (Copy) Suffix
βββΆ Split Deck βββΆ Even Partitioning across N Target Decks
βββΆ Move Cards βββΆ Reassign Card Deck IDs with Filter Persistence- Deck Lifecycle Management (
QuestionExplorer.svelte):- Clone Deck: Atomically duplicates deck metadata and cards in SQLite, creating an independent fork with an auto-incremented
(Copy)suffix. - Split Deck: Partitions a large deck (e.g. 100 cards) into $N$ smaller focused sub-decks of approximately equal size, preserving all citation links and difficulty tags.
- Selective Card Moving: Moves selected card subsets between existing decks or creates a destination deck on the fly.
- Clone Deck: Atomically duplicates deck metadata and cards in SQLite, creating an independent fork with an auto-incremented
- Scoping Filters in Export Engine (
ExportService.ts):- Supports targeted partial exports using creation date windows (
createdAfter,createdBefore), limits (limit), and optional randomization (shuffle). - Ensures study guides, printable sheets, and Anki packages can be generated for recent study intervals (e.g., "cards generated this week") without exporting entire historical libraries.
- Supports targeted partial exports using creation date windows (
14. Open-Source Foundations, In-Repo Skills & Documentation Hub β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Flashcard Master Open-Source System Architecture β
β β
β [AGPL-3.0 License] βββΆ 100% Free Local Use + SaaS Reciprocity β
β [Model Advisor] βββΆ Contextual Model Recommendation Decision Treeβ
β [Docs Hub] βββΆ VitePress + Automated GitHub Pages CI/CD β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ- Legal Invariants & Copyleft Reciprocity (AGPL-3.0):
- The entire monorepo is governed by the GNU Affero General Public License v3.0 (
LICENSE). - Guarantees 100% free use for local desktop users, researchers, and self-hosters while legally mandating that any network-accessible software modification (Section 13) must make its source code public.
- The entire monorepo is governed by the GNU Affero General Public License v3.0 (
- In-Repo Agent Skills (
.agent/skills/):- Shipped skills (e.g.,
model-advisor) provide executable decision trees for evaluating token pricing, context lengths, and local offline privacy vs. high-throughput cloud synthesis.
- Shipped skills (e.g.,
- Public Documentation Hub & GitHub Pages CI/CD:
- Authored with VitePress under
docs/, featuring client-side search, mobile responsiveness, and dark-mode styling aligned with the Web UI. - Automatically compiled and deployed on pushes to
mainvia.github/workflows/deploy-docs.yml.
- Authored with VitePress under
15. Standalone Desktop Architecture (Electron & Multi-OS Distribution) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β @flashcard-master/desktop Composition Architecture β
β β
β [Electron Main] βββΆ ~/.flashcard-master/ Unified Data Directory β
β βββΆ bootstrapDesktopServer() -> In-Process Node API β
β βββΆ Ephemeral Loopback Port (127.0.0.1:0) β
β βββΆ BrowserWindow (Dark Slate #0f172a) β
β βββΆ System Tray Minimize/Restore Controls β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββZero Backend Rewrites:
- Rather than re-architecting the web server into Electron IPC channels,
@flashcard-master/desktopdirectly bootstraps@flashcard-master/weband@flashcard-master/cli's application context in-process. - All existing REST API endpoints, Server-Sent Events (SSE) streaming task updates, and Svelte 5 UI views operate identically in desktop mode.
- Rather than re-architecting the web server into Electron IPC channels,
Unified Storage & Dynamic Port Binding:
- Desktop, Web UI, and CLI share the unified home data directory (
~/.flashcard-master/β containingdata.sqlite,media/, andlocal-files/, overridable in CLI/Web via--data-dir), keeping user data unified while reservingapp.getPath('userData')solely for Electron runtime/window cache. - The server binds dynamically to port
0(an available ephemeral loopback port) to prevent collisions with any existing CLI servers running on port3000.
- Desktop, Web UI, and CLI share the unified home data directory (
Security & Native UX:
- Enforces safe Electron defaults:
contextIsolation: true,sandbox: true, andnodeIntegration: false. - Implements single-instance application locking (
app.requestSingleInstanceLock()) to prevent multiple desktop instances from conflicting over WAL database locks. - Provides custom dark slate window background (
#0f172a), taskbar/dock icon integration, and system tray background minimize/restore.
- Enforces safe Electron defaults:
Multi-OS Release CI/CD Pipeline:
- Configured with
electron-builderto produce standalone installers across all major operating systems: Windows (.exeNSIS installer + portable), macOS (.dmgUniversal/arm64), and Linux (.AppImage+.deb). - Automated by
.github/workflows/release-desktop.yml, which triggers on tag push (v*) to build and attach signed release binaries to GitHub Releases.
- Configured with