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)

```bash
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)

```bash
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)

```powershell
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)

```bash
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

```bash
python ./journal/run_desktop.py
```

### CLI

```bash
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:

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

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

## Installer Script

Use the Linux helper script:

```bash
./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.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

```bash
cd backend
dotnet build
```

Run the API server:

```bash
dotnet run --project Journal.Api
```

Run the sidecar (stdin/stdout mode):

```bash
dotnet run --project Journal.Sidecar
```

Sidecar CLI commands:

```bash
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:

```bash
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.