Architecture Overview
Relevant Source Files
PALEE (Personal Active Learning & Evaluation Engine) is structured as a three-layer system 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#20-31
System Layers
The codebase is organized into three distinct layers with a strict downward dependency flow.
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#1-10
- Atomic Writes: Ensures file integrity by writing to temporary files before renaming src/storage/atomic-write.ts#1-15
- File Locking: Prevents concurrent modification conflicts using a heartbeat-based locking mechanism src/storage/lock.ts#1-20
- Vault Walker: Discovers and indexes topics while respecting boundary constraints (e.g., ignoring
.git,node_modules) src/storage/vault-walker.ts#10-35
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#39-49
- SM-2 Algorithm: Calculates next review dates and ease factors based on recall quality src/engine/sm2.ts#1-10
- Dependency Graph: Manages a Directed Acyclic Graph (DAG) of topics, ensuring prerequisites are mastered before recommending advanced topics src/engine/dependency.ts#1-15
- Mastery Logic: Derives overall topic mastery from conceptual, practical, debug, and feynman scores src/types.ts#20-30
3. Tool Interface & CLI
The entry point for users and external agents. It coordinates between the Storage and Engine layers.
- CLI Interface: Commands like
palee next,palee plan, andpalee reviewbin/palee.ts#1-50 - Session Manager: Handles the lifecycle of a study session, including "hot memory" persistence in
.palee/hot.mdsrc/storage/memory.ts#1-25 - 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#107-112
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#5-60src/engine/sm2.ts#1-40planning/palee_cli_spec.md#50-64
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#32-37
Diagram: Atomic Write & OCC Flow
Sources:src/storage/atomic-write.ts#5-40src/storage/lock.ts#10-60planning/palee_cli_spec.md#83-84README.md#190-198
Key Design Principles
| Principle | Implementation in Code |
|---|---|
| Deterministic Core | The SM2 and DependencyGraph classes are side-effect free and operate on plain objects src/engine/sm2.ts#5-15src/engine/dependency.ts#10-25 |
| Separation of Concerns | CLI commands in src/cli/ never call fs directly; they use src/storage/ abstractions bin/palee.ts#10-100 |
| 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#1-20 |
| Human Oversight | AI-proposed scores must be confirmed by the user before record_assessment is invoked planning/palee_cli_spec.md#107-112 |
Sources:planning/palee_cli_spec.md#20-23README.md#183-189planning/invariants.md#1-20