Architecture Overview

Relevant Source Files

PALEE (Personal Active Learning & Evaluation Engine) is structured as a layered system with a strict downward dependency flow, designed to bridge deterministic learning algorithms with flexible AI-powered tutoring. The architecture prioritizes the Obsidian vault as the single source of truth, ensuring that all learning data remains human-readable, versionable, and portable planning/palee_cli_spec.md

System Layers

The codebase is organized into five import-reachable groups — cli, application, validation, engine, and storage — plus the shared types.ts/index.ts contract and the optional ai boundary. Dependencies point downward; the runtime layers are described below.

1. Storage Layer

The storage layer manages all interactions with the filesystem. It treats the Obsidian vault as the authoritative database, using Markdown frontmatter to store topic metadata src/storage/frontmatter.ts

Atomic Writes: Ensures file integrity by writing to temporary files before renaming src/storage/atomic-write.ts
File Locking: Prevents concurrent modification conflicts using a heartbeat-based locking mechanism src/storage/lock.ts
Vault Walker: Discovers and indexes topics while respecting boundary constraints (e.g., ignoring .git, node_modules) src/storage/vault-walker.ts

2. Engine Core

A pure-function library that contains the business logic for learning. It is decoupled from I/O to ensure testability and determinism planning/palee_cli_spec.md

SM-2 Algorithm: Calculates next review dates and ease factors based on recall quality src/engine/sm2.ts
Dependency Graph: Manages a Directed Acyclic Graph (DAG) of topics, ensuring prerequisites are mastered before recommending advanced topics src/engine/dependency.ts
Mastery Logic: Derives overall topic mastery from conceptual, practical, debug, and feynman scores src/types.ts

3. Application & Validation

The application layer holds pure use-cases that coordinate storage and engine contracts without touching Commander or process state. getNextTopics() powers next and dashboard; plan uses findPrerequisiteBlocked() and partitionDue() alongside the engine's getReadyTopics(). buildReviewUpdate() and buildAssessmentUpdate() translate user input into frontmatter updates, and summarizeMastery() powers progress reporting.

The validation layer is the audit framework behind palee validate: collectVault(), runRules(), and the rules/ registry produce structured ValidationError records and optional repairs.

4. Tool Interface & CLI

The entry point for users and external agents. It coordinates the application and validation layers, which in turn depend on storage and engine.

CLI Interface: Commands like palee next, palee plan, and palee reviewbin/palee.ts
Session Manager: Handles the lifecycle of a study session, including "hot memory" persistence in .palee/hot.mdsrc/storage/memory.ts
AI Module (Optional): Provides Feynman testing and tutoring, constrained by a "Human-in-the-loop" contract where the user must confirm any state changes planning/palee_cli_spec.md

Data Flow: Natural Language to Code Entities

The following diagram illustrates how high-level user actions translate into specific code entities and data structures within the PALEE ecosystem.

Diagram: Entity Mapping

Sources:src/types.ts src/engine/sm2.ts planning/palee_cli_spec.md

The File-Safety Contract

PALEE implements a strict file-safety contract to ensure that automated updates never corrupt user notes. The system uses a Concrete Syntax Tree (CST) parser to modify only specific palee_* keys while preserving all other Markdown content, comments, and formatting planning/palee_cli_spec.md

Diagram: Atomic Write & OCC Flow

Sources:src/storage/atomic-write.ts src/storage/lock.ts planning/palee_cli_spec.md README.md

Key Design Principles

Principle	Implementation in Code
Deterministic Core	The SM-2 and dependency-graph engine modules are side-effect free and operate on plain objects src/engine/sm2.ts src/engine/dependency.ts
Separation of Concerns	CLI commands in `src/cli/` never call `fs` directly; they use `src/storage/` abstractions bin/palee.ts
Vault as Source of Truth	No external database is required. The `FileCache` is strictly for performance and can be deleted at any time src/storage/cache.ts
Human Oversight	AI-proposed scores must be confirmed by the user before `record_assessment` is invoked planning/palee_cli_spec.md

Sources:planning/palee_cli_spec.md README.md planning/invariants.md

Architecture Overview ​

System Layers ​

1. Storage Layer ​

2. Engine Core ​

3. Application & Validation ​

4. Tool Interface & CLI ​

Data Flow: Natural Language to Code Entities ​

The File-Safety Contract ​

Key Design Principles ​