From 6482382572823520672e6ef995ab5c2561572bad Mon Sep 17 00:00:00 2001 From: Jacob Schmidt Date: Mon, 2 Mar 2026 20:12:13 -0600 Subject: [PATCH] Update README to reflect monorepo structure - Rewrite repository layout with all current projects and config files - Replace broken scripts/*.ps1 references with direct dotnet/npm commands - Add Journal.AI to project table and dependency list - Document central package management (Directory.Build/Packages.props) - Update npm commands to use workspace flags (-w Journal.App) - Rename Scripts section to SDT DevTool, reference Journal.DevTool/scripts/ - Remove stale notes about WebGateway exclusion from slnx Co-Authored-By: Oz --- README.md | 124 ++++++++++++++++++++++++------------------------------ 1 file changed, 54 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index cdbaf76..926c310 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,22 @@ A structured journaling system with encrypted monthly vaults, a Tauri desktop ap ## Repository Layout ``` -journal/ -├── Journal.Core/ .NET class library — all business logic and services -├── Journal.Sidecar/ Console app — stdin/stdout JSON protocol (Tauri sidecar bridge + CLI) -├── Journal.WebGateway/ ASP.NET Core app — HTTP wrapper for browser/web mode -├── Journal.SmokeTests/ Integration tests (~80 tests, no test framework dependency) -├── Journal.App/ SvelteKit + Tauri desktop app -│ ├── src/ SvelteKit frontend source -│ ├── src-tauri/ Rust Tauri shell (sidecar process manager) -│ └── static/ Static assets -├── scripts/ PowerShell dev, build, publish, and cache helpers -├── docs/ Internal design docs -└── journal/ Runtime data directories (vault/) +backend/ Monorepo root +├── Journal.Core/ .NET class library — all business logic and services +├── Journal.AI/ .NET class library — LLM/AI integration (LLamaSharp) +├── Journal.Sidecar/ Console app — stdin/stdout JSON protocol (Tauri sidecar bridge + CLI) +├── Journal.WebGateway/ ASP.NET Core app — HTTP wrapper for browser/web mode +├── Journal.SmokeTests/ Integration tests (~80 tests, no test framework dependency) +├── Journal.App/ SvelteKit + Tauri desktop app +│ ├── src/ SvelteKit frontend source +│ ├── src-tauri/ Rust Tauri shell (sidecar process manager) +│ └── static/ Static assets +├── Journal.DevTool/ Pre-built SDT orchestrator (sdt.exe) + Python scripts +├── Directory.Build.props Shared .NET build properties (TFM, nullable, etc.) +├── Directory.Packages.props Centralized NuGet package versions +├── Journal.slnx Visual Studio solution (all .NET projects) +├── package.json npm workspace root (Journal.App) +└── devtool.json SDT workflow/toolchain configuration ``` ## Deployment Modes @@ -52,19 +56,12 @@ All three modes share the same `Journal.Core` service layer and command protocol ### Option A — Tauri Desktop App -Build the sidecar, then the Tauri app: +Install dependencies and build: ```powershell -cd Journal.App -npm install -npm run tauri build -``` - -Or via the publish scripts (recommended for clean environments): - -```powershell -.\scripts\publish-sidecar.ps1 -Configuration Release -Runtime win-x64 -.\scripts\publish-app.ps1 -Target tauri -TauriBundles none +npm install # from repo root (workspaces) +dotnet publish Journal.Sidecar/Journal.Sidecar.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true +npm run tauri build -w Journal.App ``` Tauri auto-detects `Journal.Sidecar.exe` in the repository. On first launch it walks up from the working directory to find `Journal.Sidecar/` and resolves the built executable. @@ -74,14 +71,14 @@ Tauri auto-detects `Journal.Sidecar.exe` in the repository. On first launch it w Build the web UI bundle, then publish the gateway with web assets embedded: ```powershell -.\scripts\publish-app.ps1 -Target web -.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64 +npm run build -w Journal.App +dotnet publish Journal.WebGateway/Journal.WebGateway.csproj -c Release -r win-x64 ``` Run the gateway: ```powershell -.\scripts\run-webgateway.ps1 -Urls http://0.0.0.0:5180 +dotnet run --project Journal.WebGateway ``` Open `http://localhost:5180` in your browser. The gateway automatically serves the SvelteKit build and proxies all `/api/command` calls to `Journal.Core`. @@ -95,7 +92,6 @@ Invoke-RestMethod http://127.0.0.1:5180/api/health ### Option C — Sidecar / CLI only ```powershell -cd Journal.Core dotnet build # Run in stdin/stdout protocol mode @@ -116,6 +112,7 @@ dotnet run --project Journal.Sidecar -- search "your query" --tag stress --start | Project | Type | Purpose | |---------|------|---------| | `Journal.Core` | Class library | Domain models, services, repositories, DTOs — all business logic | +| `Journal.AI` | Class library | LLM/AI integration (LLamaSharp) — references Journal.Core | | `Journal.Sidecar` | Console app | Stdin/stdout JSON protocol + vault/search CLI subcommands | | `Journal.WebGateway` | ASP.NET Core | HTTP API wrapper; serves built SvelteKit UI from `wwwroot` | | `Journal.SmokeTests` | Console app | ~80 integration tests (no xunit/nunit) | @@ -123,10 +120,10 @@ dotnet run --project Journal.Sidecar -- search "your query" --tag stress --start ### Solution File ``` -Journal.slnx (Visual Studio solution — Core + Sidecar + SmokeTests) +Journal.slnx (all .NET projects: Core, AI, Sidecar, WebGateway, SmokeTests) ``` -> `Journal.WebGateway` is not in the solution file; build/run it directly with `dotnet` or the `scripts/` wrappers. +All .NET projects share build properties via `Directory.Build.props` and NuGet versions via `Directory.Packages.props` (central package management). ### Architecture @@ -153,12 +150,8 @@ Services live under `Journal.Core/Services/` in domain-specific subdirectories, ### Build ```powershell -# Build all projects +# Build all .NET projects via the solution dotnet build - -# Or use the resilient wrapper (handles proxy/NuGet quirks): -.\scripts\dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj -.\scripts\dotnet-min.ps1 build Journal.WebGateway/Journal.WebGateway.csproj ``` ### Run Smoke Tests @@ -169,9 +162,12 @@ dotnet run --project Journal.SmokeTests ### Dependencies +NuGet package versions are managed centrally in `Directory.Packages.props`. Project-level `.csproj` files reference packages without version numbers. + - `Journal.Core` — `Microsoft.Data.Sqlite.Core`, `SQLitePCLRaw.bundle_e_sqlcipher`, `Microsoft.Extensions.DependencyInjection.Abstractions` -- `Journal.Sidecar` — `Microsoft.Extensions.DependencyInjection` + references `Journal.Core` -- `Journal.WebGateway` — `Microsoft.NET.Sdk.Web` + references `Journal.Core` +- `Journal.AI` — `LLamaSharp`, `LLamaSharp.Backend.Cpu` + references `Journal.Core` +- `Journal.Sidecar` — `Microsoft.Extensions.DependencyInjection`, `NAudio`, `Whisper.net` + references `Journal.Core`, `Journal.AI` +- `Journal.WebGateway` — `Microsoft.NET.Sdk.Web` + references `Journal.Core`, `Journal.AI` - `Journal.SmokeTests` — references `Journal.Core` ### Encryption @@ -227,8 +223,6 @@ If no dist is found, `/` returns a JSON status message instead of the UI. ```powershell dotnet run --project Journal.WebGateway -# or -.\scripts\run-webgateway.ps1 -Urls http://0.0.0.0:5180 -ProjectRoot E:\path\to\journal ``` --- @@ -287,25 +281,24 @@ The frontend uses Svelte stores as the source of truth: ### Dev Setup ```powershell -cd Journal.App -npm install -npm run dev # SvelteKit dev server at http://localhost:1420 -npm run tauri dev # Tauri dev mode (opens desktop window) +npm install # from repo root (workspaces) +npm run dev -w Journal.App # SvelteKit dev server at http://localhost:1420 +npm run tauri dev -w Journal.App # Tauri dev mode (opens desktop window) ``` ### Publishing ```powershell # Web bundle only (for WebGateway) -.\scripts\publish-app.ps1 -Target web +npm run build -w Journal.App # Output: Journal.App/build/ # Tauri raw exe (no installer) -.\scripts\publish-app.ps1 -Target tauri -TauriBundles none +npm run tauri build -w Journal.App -- -- --bundles none # Output: Journal.App/src-tauri/target/release/journalapp.exe # Tauri with NSIS installer -.\scripts\publish-app.ps1 -Target tauri -TauriBundles nsis +npm run tauri build -w Journal.App -- -- --bundles nsis ``` --- @@ -432,15 +425,9 @@ dotnet run --project Journal.Sidecar -- search "common text" --tag stress --type ### Sidecar (self-contained executable) -```powershell -.\scripts\publish-sidecar.ps1 -Configuration Release -Runtime win-x64 -# Output: output\Journal.Sidecar.exe (~70MB, all bundled) -``` - -Or raw `dotnet publish`: - ```powershell dotnet publish Journal.Sidecar/Journal.Sidecar.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true +# Output: Journal.Sidecar/bin/Release/net10.0/win-x64/publish/Journal.Sidecar.exe ``` To exclude debug symbols: add `-p:DebugType=none` @@ -455,11 +442,10 @@ dotnet publish Journal.Sidecar/Journal.Sidecar.csproj -c Release -r win-x64 -p:P ```powershell # Step 1: build web assets -.\scripts\publish-app.ps1 -Target web +npm run build -w Journal.App -# Step 2: publish gateway (copies web assets into wwwroot automatically) -.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64 -# Output: output\webgateway\ (with output\webgateway\wwwroot\ from Journal.App\build) +# Step 2: publish gateway +dotnet publish Journal.WebGateway/Journal.WebGateway.csproj -c Release -r win-x64 ``` --- @@ -505,24 +491,23 @@ The `Command`/`Entry` pattern uses dot-notation actions. To add a module: --- -## Scripts +## SDT DevTool -See [`scripts/README.md`](scripts/README.md) for the full reference and [`scripts/WORKFLOWS.md`](scripts/WORKFLOWS.md) for copy-paste command recipes. +`Journal.DevTool/` contains the pre-built SDT (Stan's Dev Tools) orchestrator and its Python build/automation scripts. See [`Journal.DevTool/README.md`](Journal.DevTool/README.md) for full documentation. -Quick reference: +Key scripts in `Journal.DevTool/scripts/`: | Script | Purpose | |--------|---------| -| `dev-shell.ps1` | Dot-source to configure current shell with repo-local env vars | -| `dotnet-min.ps1` | `dotnet` wrapper with resilient NuGet defaults | -| `pip-min.ps1` | `pip` wrapper with repo-local cache and Windows compat mapping | -| `publish-app.ps1` | Build web bundle or Tauri desktop app | -| `publish-sidecar.ps1` | Publish `Journal.Sidecar` single-file exe to `output/` | -| `publish-webgateway.ps1` | Publish `Journal.WebGateway` with optional web assets | -| `run-webgateway.ps1` | Run `Journal.WebGateway` with controlled env and project root | -| `migration-gate.ps1` | End-to-end build + smoke + parity + API check gate | -| `nuget-export-cache.ps1` | Export NuGet cache to zip for offline/transfer use | -| `nuget-import-cache.ps1` | Import NuGet cache zip and validate restore | +| `build.py` | Orchestrated project builds | +| `publish-sidecar.py` | Publish `Journal.Sidecar` single-file exe | +| `publish-app.py` | Build web bundle or Tauri desktop app | +| `publish-webgateway.py` | Publish `Journal.WebGateway` with web assets | +| `publish-output.py` | Stage full output bundle | +| `run-webgateway.py` | Run `Journal.WebGateway` with controlled env | +| `migration-gate.py` | End-to-end build + smoke + parity check gate | +| `pip-min.py` | `pip` wrapper with repo-local cache | +| `dotnet-min.py` | `dotnet` wrapper with resilient NuGet defaults | --- @@ -530,5 +515,4 @@ Quick reference: - Journal content and templates persist in SQLCipher (`entry_documents`) under the vault DB directory. - The legacy Python placeholder file `_init_vault.vault` is treated as obsolete — the C# backend ignores and removes it during vault load. -- `Journal.WebGateway` is intentionally excluded from `Journal.slnx`; it is built/run independently via `dotnet` or the scripts wrappers. - On Windows + Tauri, the sidecar process is spawned with `CREATE_NO_WINDOW` to suppress the console window.