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

108
README.md
View File

@ -5,8 +5,9 @@ A structured journaling system with encrypted monthly vaults, a Tauri desktop ap
## Repository Layout ## Repository Layout
``` ```
journal/ backend/ Monorepo root
├── Journal.Core/ .NET class library — all business logic and services ├── 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.Sidecar/ Console app — stdin/stdout JSON protocol (Tauri sidecar bridge + CLI)
├── Journal.WebGateway/ ASP.NET Core app — HTTP wrapper for browser/web mode ├── Journal.WebGateway/ ASP.NET Core app — HTTP wrapper for browser/web mode
├── Journal.SmokeTests/ Integration tests (~80 tests, no test framework dependency) ├── Journal.SmokeTests/ Integration tests (~80 tests, no test framework dependency)
@ -14,9 +15,12 @@ journal/
│ ├── src/ SvelteKit frontend source │ ├── src/ SvelteKit frontend source
│ ├── src-tauri/ Rust Tauri shell (sidecar process manager) │ ├── src-tauri/ Rust Tauri shell (sidecar process manager)
│ └── static/ Static assets │ └── static/ Static assets
├── scripts/ PowerShell dev, build, publish, and cache helpers ├── Journal.DevTool/ Pre-built SDT orchestrator (sdt.exe) + Python scripts
├── docs/ Internal design docs ├── Directory.Build.props Shared .NET build properties (TFM, nullable, etc.)
└── journal/ Runtime data directories (vault/) ├── 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 ## Deployment Modes
@ -52,19 +56,12 @@ All three modes share the same `Journal.Core` service layer and command protocol
### Option A — Tauri Desktop App ### Option A — Tauri Desktop App
Build the sidecar, then the Tauri app: Install dependencies and build:
```powershell ```powershell
cd Journal.App npm install # from repo root (workspaces)
npm install dotnet publish Journal.Sidecar/Journal.Sidecar.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true
npm run tauri build npm run tauri build -w Journal.App
```
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
``` ```
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. 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: Build the web UI bundle, then publish the gateway with web assets embedded:
```powershell ```powershell
.\scripts\publish-app.ps1 -Target web npm run build -w Journal.App
.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64 dotnet publish Journal.WebGateway/Journal.WebGateway.csproj -c Release -r win-x64
``` ```
Run the gateway: Run the gateway:
```powershell ```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`. 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 ### Option C — Sidecar / CLI only
```powershell ```powershell
cd Journal.Core
dotnet build dotnet build
# Run in stdin/stdout protocol mode # Run in stdin/stdout protocol mode
@ -116,6 +112,7 @@ dotnet run --project Journal.Sidecar -- search "your query" --tag stress --start
| Project | Type | Purpose | | Project | Type | Purpose |
|---------|------|---------| |---------|------|---------|
| `Journal.Core` | Class library | Domain models, services, repositories, DTOs — all business logic | | `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.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.WebGateway` | ASP.NET Core | HTTP API wrapper; serves built SvelteKit UI from `wwwroot` |
| `Journal.SmokeTests` | Console app | ~80 integration tests (no xunit/nunit) | | `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 ### 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 ### Architecture
@ -153,12 +150,8 @@ Services live under `Journal.Core/Services/` in domain-specific subdirectories,
### Build ### Build
```powershell ```powershell
# Build all projects # Build all .NET projects via the solution
dotnet build 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 ### Run Smoke Tests
@ -169,9 +162,12 @@ dotnet run --project Journal.SmokeTests
### Dependencies ### 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.Core` — `Microsoft.Data.Sqlite.Core`, `SQLitePCLRaw.bundle_e_sqlcipher`, `Microsoft.Extensions.DependencyInjection.Abstractions`
- `Journal.Sidecar` — `Microsoft.Extensions.DependencyInjection` + references `Journal.Core` - `Journal.AI` — `LLamaSharp`, `LLamaSharp.Backend.Cpu` + references `Journal.Core`
- `Journal.WebGateway` — `Microsoft.NET.Sdk.Web` + 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` - `Journal.SmokeTests` — references `Journal.Core`
### Encryption ### Encryption
@ -227,8 +223,6 @@ If no dist is found, `/` returns a JSON status message instead of the UI.
```powershell ```powershell
dotnet run --project Journal.WebGateway 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 ### Dev Setup
```powershell ```powershell
cd Journal.App npm install # from repo root (workspaces)
npm install npm run dev -w Journal.App # SvelteKit dev server at http://localhost:1420
npm run dev # SvelteKit dev server at http://localhost:1420 npm run tauri dev -w Journal.App # Tauri dev mode (opens desktop window)
npm run tauri dev # Tauri dev mode (opens desktop window)
``` ```
### Publishing ### Publishing
```powershell ```powershell
# Web bundle only (for WebGateway) # Web bundle only (for WebGateway)
.\scripts\publish-app.ps1 -Target web npm run build -w Journal.App
# Output: Journal.App/build/ # Output: Journal.App/build/
# Tauri raw exe (no installer) # 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 # Output: Journal.App/src-tauri/target/release/journalapp.exe
# Tauri with NSIS installer # 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) ### 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 ```powershell
dotnet publish Journal.Sidecar/Journal.Sidecar.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true 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` 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 ```powershell
# Step 1: build web assets # 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) # Step 2: publish gateway
.\scripts\publish-webgateway.ps1 -Configuration Release -Runtime win-x64 dotnet publish Journal.WebGateway/Journal.WebGateway.csproj -c Release -r win-x64
# Output: output\webgateway\ (with output\webgateway\wwwroot\ from Journal.App\build)
``` ```
--- ---
@ -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 | | Script | Purpose |
|--------|---------| |--------|---------|
| `dev-shell.ps1` | Dot-source to configure current shell with repo-local env vars | | `build.py` | Orchestrated project builds |
| `dotnet-min.ps1` | `dotnet` wrapper with resilient NuGet defaults | | `publish-sidecar.py` | Publish `Journal.Sidecar` single-file exe |
| `pip-min.ps1` | `pip` wrapper with repo-local cache and Windows compat mapping | | `publish-app.py` | Build web bundle or Tauri desktop app |
| `publish-app.ps1` | Build web bundle or Tauri desktop app | | `publish-webgateway.py` | Publish `Journal.WebGateway` with web assets |
| `publish-sidecar.ps1` | Publish `Journal.Sidecar` single-file exe to `output/` | | `publish-output.py` | Stage full output bundle |
| `publish-webgateway.ps1` | Publish `Journal.WebGateway` with optional web assets | | `run-webgateway.py` | Run `Journal.WebGateway` with controlled env |
| `run-webgateway.ps1` | Run `Journal.WebGateway` with controlled env and project root | | `migration-gate.py` | End-to-end build + smoke + parity check gate |
| `migration-gate.ps1` | End-to-end build + smoke + parity + API check gate | | `pip-min.py` | `pip` wrapper with repo-local cache |
| `nuget-export-cache.ps1` | Export NuGet cache to zip for offline/transfer use | | `dotnet-min.py` | `dotnet` wrapper with resilient NuGet defaults |
| `nuget-import-cache.ps1` | Import NuGet cache zip and validate restore |
--- ---
@ -530,5 +515,4 @@ Quick reference:
- Journal content and templates persist in SQLCipher (`entry_documents`) under the vault DB directory. - 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. - 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. - On Windows + Tauri, the sidecar process is spawned with `CREATE_NO_WINDOW` to suppress the console window.