J.Schmidt92/journal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README to reflect monorepo structure

Browse Source 
- 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 <oz-agent@warp.dev>
This commit is contained in:
Jacob Schmidt 2026-03-02 20:12:13 -06:00
parent 309d1ce049
commit 6482382572
1 changed files with 54 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
README.md
View File

@ -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.