journal/README.md

Project_Journal

A structured journaling system with encrypted monthly vaults, desktop UI, CLI tools, and optional AI-assisted analysis.

Support Matrix

• Python: 3.14
• Platforms: Windows and Linux (first-class), macOS (best effort)
• Default profile: CPU
• Optional profiles: GPU, optional NLP backend

Dependency Profiles

• requirements_base.txt: shared Journal runtime dependencies
• requirements_cpu_only.txt: base + CPU AI stack
• requirements_gpu.txt: base + GPU AI stack
• requirements_nlp_optional.txt: optional spaCy backend (auto-fallback if unavailable)

Quickstart

Linux (CPU default)

cd Project_Journal
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt

Linux (GPU optional)

cd Project_Journal
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements_gpu.txt

Windows PowerShell (CPU default)

cd Project_Journal
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt

On Windows + Python 3.14, pywebview is intentionally skipped due upstream pythonnet build compatibility. run_desktop.py will auto-fallback to opening the app in your system browser.

Optional NLP backend (spaCy)

python -m pip install -r requirements_nlp_optional.txt
python -m spacy download en_core_web_sm

If spaCy is missing or unsupported, Journal now auto-falls back to built-in NLP heuristics. On current Python 3.14 environments, this optional install may be skipped due upstream spaCy compatibility.

Running

Desktop App

python ./journal/run_desktop.py

CLI

python -m journal.cli.main --help
python -m journal.cli.main vault load
python -m journal.cli.main search "your query"

NLP Backend Control

Set JOURNAL_NLP_BACKEND to choose behavior:

• auto (default): use spaCy when available, else fallback
• spacy: require spaCy backend and fail clearly if unavailable
• fallback: always use fallback heuristics

Examples:

export JOURNAL_NLP_BACKEND=fallback
python ./journal/run_desktop.py

$env:JOURNAL_NLP_BACKEND = "spacy"
python .\journal\run_desktop.py

Installer Script

Use the Linux helper script:

./installreqs.sh
./installreqs.sh --gpu
./installreqs.sh --with-nlp

C# Backend

The backend/ directory contains a .NET 10 implementation that provides the same journal functionality as the Python layer, with encrypted vault support and an identical JSON command protocol.

Projects

• Journal.Core — shared library: domain models, services, repositories, DTOs
• Journal.Api — minimal ASP.NET Core web API (/api/command POST endpoint)
• Journal.Sidecar — console app (stdin/stdout JSON protocol or CLI with vault and search subcommands)
• Journal.SmokeTests — 70+ integration tests (no test framework dependency)

Architecture

Entry (thin command dispatcher)
  ├── Fragments/    IFragmentService → FragmentService → IFragmentRepository (SQLCipher)
  ├── Entries/      IEntryFileService, IEntrySearchService, JournalParser, HtmlSanitizer
  ├── Vault/        IVaultStorageService → VaultStorageService → IVaultCryptoService
  ├── Database/     IJournalDatabaseService (SQLCipher schema/key derivation)
  │                 IDatabaseSessionService (encrypted connection lifecycle after auth)
  ├── Ai/           IAiService → PythonSidecarAiService | DisabledAiService
  ├── Speech/       ISpeechBridgeService → PythonSidecarSpeechService | DisabledSpeechBridgeService
  ├── Sidecar/      PythonSidecarClient (shared Python process I/O), SidecarCli
  ├── Logging/      CommandLogger, LogRedactor
  └── Config/       IJournalConfigService → JournalConfigService

Services are organized under Journal.Core/Services/ in domain-specific subdirectories, each with its own namespace (e.g. Journal.Core.Services.Ai).

Build & Run

cd backend
dotnet build

Run the API server:

dotnet run --project Journal.Api

Run the sidecar (stdin/stdout mode):

dotnet run --project Journal.Sidecar

Sidecar CLI commands:

dotnet run --project Journal.Sidecar -- vault load --password <value>
dotnet run --project Journal.Sidecar -- vault save --password <value>
dotnet run --project Journal.Sidecar -- search "your query" --tag stress --start-date 2026-02-01

Run smoke tests:

dotnet run --project Journal.SmokeTests

Environment Variables

• JOURNAL_PROJECT_ROOT — override project root detection
• JOURNAL_DATA_DIR / JOURNAL_VAULT_DIR — override data/vault paths
• JOURNAL_AI_PROVIDER — none (default) or python-sidecar
• JOURNAL_PYTHON_EXE — Python executable path (default: python)
• JOURNAL_LOG_LEVEL — trace, debug, information, warning (default), error, critical

Encryption

• Vault: AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600k iterations)
• Database: SQLCipher with PBKDF2-derived key
• Standalone fragments are stored in the encrypted SQLCipher database (requires auth via vault.load_all or db.hydrate_workspace)
• DatabaseSessionService holds the encryption password in memory after first authentication
• Wire format matches the Python implementation for cross-language parity

Notes

• Decrypted journal data in journal/data is cleared on graceful shutdown.
• Vault save/load commands remain unchanged.