Fix installed data path and refresh user documentation

Author: rhamenator

BrassLedger.Infrastructure.Tests/WorkspaceInitializationTests.cs

@@ -52,6 +52,27 @@ public async Task InitializeBrassLedgerAsync_CreatesSqliteDatabaseInAppData()
         Assert.True(File.Exists(databasePath));
     }
 
+    [Fact]
+    public async Task InitializeBrassLedgerAsync_UsesConfiguredDataRootWhenProvided()
+    {
+        var configuredDataRoot = Path.Combine(_contentRootPath, "CustomDataRoot");
+        var configuration = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                ["Storage:DataRoot"] = configuredDataRoot
+            })
+            .Build();
+
+        var serviceCollection = new ServiceCollection();
+        serviceCollection.AddBrassLedgerInfrastructure(configuration, _contentRootPath, seedSampleData: true);
+
+        using var services = serviceCollection.BuildServiceProvider();
+        await services.InitializeBrassLedgerAsync();
+
+        Assert.True(File.Exists(Path.Combine(configuredDataRoot, "brassledger.db")));
+        Assert.True(Directory.Exists(Path.Combine(configuredDataRoot, "keys")));
+    }
+
     [Fact]
     public async Task InitializeBrassLedgerAsync_SeedsAuthenticationCredentials()
     {

BrassLedger.Infrastructure/Persistence/ServiceCollectionExtensions.cs

@@ -23,7 +23,7 @@ public static IServiceCollection AddBrassLedgerInfrastructure(
         string contentRootPath,
         bool seedSampleData = false)
     {
-        var dataDirectory = BuildDataDirectory(contentRootPath);
+        var dataDirectory = BuildDataDirectory(configuration, contentRootPath);
         var keysDirectory = Path.Combine(dataDirectory, "keys");
         Directory.CreateDirectory(keysDirectory);
 
@@ -84,11 +84,64 @@ private static BootstrapOptions BuildBootstrapOptions(IConfiguration configurati
         return options;
     }
 
-    private static string BuildDataDirectory(string contentRootPath)
+    private static string BuildDataDirectory(IConfiguration configuration, string contentRootPath)
     {
-        var dataDirectory = Path.Combine(contentRootPath, "App_Data");
-        Directory.CreateDirectory(dataDirectory);
-        return dataDirectory;
+        var configuredDataRoot =
+            configuration["Storage:DataRoot"]
+            ?? configuration["BrassLedger:DataRoot"];
+
+        if (!string.IsNullOrWhiteSpace(configuredDataRoot))
+        {
+            var explicitDataDirectory = Path.GetFullPath(Environment.ExpandEnvironmentVariables(configuredDataRoot));
+            Directory.CreateDirectory(explicitDataDirectory);
+            return explicitDataDirectory;
+        }
+
+        var contentRootDataDirectory = Path.Combine(contentRootPath, "App_Data");
+        if (TryEnsureWritableDirectory(contentRootDataDirectory))
+        {
+            return contentRootDataDirectory;
+        }
+
+        var localApplicationDataRoot = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+        if (string.IsNullOrWhiteSpace(localApplicationDataRoot))
+        {
+            localApplicationDataRoot = Path.GetTempPath();
+        }
+
+        var fallbackDataDirectory = Path.Combine(localApplicationDataRoot, "BrassLedger", "App_Data");
+        Directory.CreateDirectory(fallbackDataDirectory);
+        return fallbackDataDirectory;
+    }
+
+    private static bool TryEnsureWritableDirectory(string directoryPath)
+    {
+        try
+        {
+            Directory.CreateDirectory(directoryPath);
+
+            var probeFilePath = Path.Combine(directoryPath, $".write-test-{Guid.NewGuid():N}.tmp");
+            using var probeStream = new FileStream(
+                probeFilePath,
+                FileMode.CreateNew,
+                FileAccess.Write,
+                FileShare.None,
+                bufferSize: 1,
+                options: FileOptions.DeleteOnClose);
+
+            probeStream.WriteByte(0);
+            probeStream.Flush();
+
+            return true;
+        }
+        catch (UnauthorizedAccessException)
+        {
+            return false;
+        }
+        catch (IOException)
+        {
+            return false;
+        }
     }
 
     private static string BuildDefaultSqliteConnectionString(string dataDirectory)

BrassLedger.Web/Components/Pages/HelpAdministration.razor

@@ -29,7 +29,7 @@
         <article class="panel">
             <h2>Data and source control</h2>
             <ul class="feature-list">
-                <li>Local fallback data in <code>App_Data</code> stays out of Git.</li>
+                <li>Local application data and fallback SQLite storage stay out of Git.</li>
                 <li>Source-controlled static assets belong under <code>BrassLedger.Web/wwwroot</code>.</li>
                 <li>Publish output under <code>artifacts</code> is disposable and should be regenerated when needed.</li>
                 <li>Package builds as releases rather than committing generated files to the main repository.</li>

BrassLedger.Web/Components/Pages/Publish.razor

@@ -49,7 +49,7 @@
                 <li>Windows produces an `.exe` plus supporting publish output.</li>
                 <li>Linux and macOS builds publish platform-native executables rather than `.exe` files.</li>
                 <li>The UI stays the same across platforms because it is rendered by ASP.NET Core and opened in a browser.</li>
-                <li>Without a PostgreSQL connection string, the app boots on a local SQLite database in `App_Data`.</li>
+                <li>Without a PostgreSQL connection string, the app boots on a local SQLite database in a writable application data directory.</li>
                 <li>A desktop shell can be added later if you want a packaged window around this web app.</li>
             </ul>
         </article>

README.md

@@ -1,31 +1,99 @@
 # BrassLedger
 
-This repository contains a compileable cross-platform .NET application shell an open-source accounting platform.
+BrassLedger is an open-source cross-platform accounting and business management system for organizations that need general ledger, receivables, payables, payroll, projects, reporting, tax workflows, and printable business forms in one application.
+
+The current public prerelease is `v0.1.0-pre.1`.
 
 License: `GPL-3.0-only`. See [LICENSE](LICENSE).
 
-Projects:
+## Why BrassLedger
+
+BrassLedger is intended for teams that want a modern, open-source financial operations platform without locking their business into a proprietary desktop stack. The application is built to support daily accounting work, period close, payroll review, operational documents, tax-facing output, labels, checks, and other fixed-layout business forms.
+
+The current end-user application is `BrassLedger.Web`, delivered as a cross-platform .NET application with installers for Windows, macOS, and Linux.
+
+## What the application includes
+
+- General ledger workspaces for journal activity, balances, and month-end review
+- Receivables support for customer invoices, statements, balances, and cash application
+- Payables support for vendor bills, approvals, due-date review, and disbursement preparation
+- Operations workspaces for inventory, order flow, purchasing, fulfillment, and operational forms
+- Payroll support for employee records, pay processing, liability review, and year-end forms
+- Project and job tracking for cost visibility and work-in-progress review
+- Reporting support for financial statements, checks, paychecks, labels, shipment forms, and management output
+- Tax workspaces for federal, state, and employer-specific tax profile review
+
+## Download and quick start
+
+- Quick start and installation: [docs/quick-start.md](docs/quick-start.md)
+- Current prerelease downloads: [GitHub Releases](https://github.com/rhamenator/BrassLedger/releases)
+
+Current prerelease installers are available for:
+
+- Windows `x64`
+- macOS Intel
+- macOS Apple silicon
+- Linux `amd64`
+
+## How to use BrassLedger
+
+Start with these guides:
+
+- Main user guide: [docs/user-guide.md](docs/user-guide.md)
+- Reporting, checks, labels, forms, and print output: [docs/reporting-guide.md](docs/reporting-guide.md)
+- Administration, publishing, and support practices: [docs/administration-guide.md](docs/administration-guide.md)
 
-- `BrassLedger.Domain`: core business concepts and legacy inventory records
-- `BrassLedger.Application`: product catalog contracts and planning models
-- `BrassLedger.Infrastructure`: concrete catalog and platform service implementations
-- `BrassLedger.Api`: JSON endpoints for assessment and source inventories
-- `BrassLedger.Web`: primary end-user web application shell
+Module-by-module usage links:
 
-The current user-facing application is `BrassLedger.Web`.
+- Overview and daily review: [docs/user-guide.md#overview](docs/user-guide.md#overview)
+- General ledger: [docs/user-guide.md#ledger](docs/user-guide.md#ledger)
+- Receivables: [docs/user-guide.md#receivables](docs/user-guide.md#receivables)
+- Payables: [docs/user-guide.md#payables](docs/user-guide.md#payables)
+- Operations: [docs/user-guide.md#operations](docs/user-guide.md#operations)
+- Payroll: [docs/user-guide.md#payroll](docs/user-guide.md#payroll)
+- Projects: [docs/user-guide.md#projects](docs/user-guide.md#projects)
+- Reporting and forms: [docs/user-guide.md#reporting-and-forms](docs/user-guide.md#reporting-and-forms)
+- Taxes: [docs/user-guide.md#taxes](docs/user-guide.md#taxes)
+- Publish workspace: [docs/user-guide.md#publish](docs/user-guide.md#publish)
+- Month-end review: [docs/user-guide.md#month-end-review](docs/user-guide.md#month-end-review)
+- Security and data handling: [docs/user-guide.md#security-and-data-handling](docs/user-guide.md#security-and-data-handling)
 
-Why this shape:
+Specialized documentation:
 
-- it publishes as a Windows `.exe`
-- it can also be published for Linux and macOS
-- it keeps the UI cross-platform without locking the product into Windows-only desktop technology
+- Financial statements: [docs/reporting-guide.md#financial-statements](docs/reporting-guide.md#financial-statements)
+- Receivables output: [docs/reporting-guide.md#receivables-output](docs/reporting-guide.md#receivables-output)
+- Payables output: [docs/reporting-guide.md#payables-output](docs/reporting-guide.md#payables-output)
+- Payroll and year-end output: [docs/reporting-guide.md#payroll-and-year-end-output](docs/reporting-guide.md#payroll-and-year-end-output)
+- Tax-facing output: [docs/reporting-guide.md#tax-facing-output](docs/reporting-guide.md#tax-facing-output)
+- Operations documents and labels: [docs/reporting-guide.md#operations-documents-and-labels](docs/reporting-guide.md#operations-documents-and-labels)
+- Administrative data handling: [docs/administration-guide.md#data-handling](docs/administration-guide.md#data-handling)
+- Administrative publishing guidance: [docs/administration-guide.md#publishing](docs/administration-guide.md#publishing)
 
-Helpful commands:
+## Security baseline
+
+The current application includes:
+
+- authenticated access before accounting data loads in the web app or API
+- password hashing through ASP.NET Core Identity primitives
+- protection of sensitive fields at rest with ASP.NET Core Data Protection
+- persisted application key material under `App_Data\keys`
+- security headers in the web application and API
+- bootstrap administrator requirements for first non-development startup
+
+Before live production use, administrators should still review operational backup, recovery, secrets management, access control, and deployment procedures.
+
+## Build, test, and publish
+
+Helpful maintainer commands:
 
 ```powershell
 dotnet build .\BrassLedger.slnx
 ```
 
+```powershell
+dotnet test .\BrassLedger.slnx -nr:false
+```
+
 ```powershell
 .\publish-brassledger.ps1 -Runtime win-x64
 ```
@@ -50,36 +118,19 @@ dotnet build .\BrassLedger.slnx
 .\run-ui-tests.ps1 -UpdateBaselines
 ```
 
-See `docs/publish-guide.md` for platform-specific publish commands.
-UI visual baselines live in `BrassLedger.Web.E2E.Tests\Snapshots` so they can be reviewed and committed with the test suite.
-The Playwright matrix auto-detects Microsoft Edge on Windows and will include it in browser-based test runs when available.
-Firefox is also supported in the local Playwright browser matrix when installed.
-
-Current prerelease:
-
-- The current consumer-facing prerelease is `v0.1.0-pre.1`.
-- Release assets are published for Windows, macOS Intel, macOS Apple silicon, and Linux.
-- GitHub Actions workflow `.github/workflows/release-installers.yml` builds the unsigned installers and attaches them to tagged prereleases.
-- Installer signing is intentionally disabled for now and can be added later once certificate material is available.
-
-Current security baseline:
-
-- authenticated access is required before accounting data loads in the web app or API
-- password hashes use ASP.NET Core Identity hashing
-- sensitive fields are protected at rest with ASP.NET Core Data Protection
-- Data Protection keys are persisted under `App_Data\keys`
-- security headers are applied to both the web app and API
-- a first non-development startup requires `Bootstrap:AdminPassword` so the system creates a real administrator account instead of demo users
+Additional maintainer documentation:
 
-Bootstrap configuration:
+- Platform-specific publish notes: [docs/publish-guide.md](docs/publish-guide.md)
 
-- development starts with sample data automatically
-- non-development first run requires `Bootstrap:AdminPassword`
-- optional bootstrap settings include `Bootstrap:CompanyName`, `Bootstrap:LegalName`, `Bootstrap:AdminUserName`, `Bootstrap:AdminDisplayName`, and `Bootstrap:AdminEmail`
+Release automation is handled by `.github/workflows/release-installers.yml`, which builds installer assets for Windows, macOS Intel, macOS Apple silicon, and Linux and attaches them to tagged prereleases and releases.
 
-Help and operator guidance:
+## Repository layout
 
-- In-app help pages live under `BrassLedger.Web/Components/Pages/Help*.razor`.
-- Written guides live in `docs/user-guide.md`, `docs/reporting-guide.md`, and `docs/administration-guide.md`.
-- Source-controlled web assets belong under `BrassLedger.Web/wwwroot`; generated publish output stays under `artifacts` and remains ignored by Git.
+- `BrassLedger.Domain`: core business entities
+- `BrassLedger.Application`: application-facing contracts and models
+- `BrassLedger.Infrastructure`: authentication, persistence, security, and service implementations
+- `BrassLedger.Api`: API endpoints
+- `BrassLedger.Web`: end-user application
+- `docs`: installation, usage, reporting, administration, and publishing guides
 
+Source-controlled web assets belong under `BrassLedger.Web/wwwroot`. Generated publish output stays under `artifacts` and remains ignored by Git.

docs/administration-guide.md

@@ -25,7 +25,8 @@ Before using live confidential books in production, plan for more:
 Use these rules consistently:
 
 - the database is the source of truth for accounting data
-- `App_Data` is local environment data and should stay out of Git
+- local SQLite data and key material belong in a writable application data directory and should stay out of Git
+- `Storage:DataRoot` can be set explicitly if you need to control where local application data is stored
 - `BrassLedger.Web/wwwroot` is the source location for committed static assets
 - `artifacts` is a publish output folder and should be disposable
 
@@ -55,7 +56,7 @@ Ignore:
 - `artifacts`
 - `bin`
 - `obj`
-- `App_Data`
+- local application data directories such as `App_Data`
 - local IDE state
 
 ## Support checklist

docs/quick-start.md

@@ -0,0 +1,76 @@
+# BrassLedger Quick Start
+
+This guide helps first-time users install BrassLedger, sign in, and start exploring the main work areas.
+
+## Download an installer
+
+Get the installer that matches your operating system from the current prerelease on GitHub Releases:
+
+- Windows: `BrassLedger-setup-win-x64.exe`
+- macOS Intel: `BrassLedger-<version>-osx-x64.pkg`
+- macOS Apple silicon: `BrassLedger-<version>-osx-arm64.pkg`
+- Linux: `brassledger_<version>_amd64.deb`
+
+## Install BrassLedger
+
+### Windows
+
+1. Download `BrassLedger-setup-win-x64.exe`.
+2. Run the installer.
+3. Keep the default install directory unless you have a deployment reason to change it.
+4. Start BrassLedger from the Start menu or desktop shortcut.
+
+### macOS
+
+1. Download the `.pkg` for your Mac architecture.
+2. Open the package.
+3. Follow the installer prompts.
+4. Start BrassLedger from Applications.
+
+### Linux
+
+1. Download the `.deb` package.
+2. Install it with your package manager or:
+
+```bash
+sudo dpkg -i brassledger_<version>_amd64.deb
+```
+
+3. Start BrassLedger from your desktop launcher or by running `brassledger`.
+
+## First launch
+
+BrassLedger runs as a local web application. On first launch:
+
+1. Open the sign-in page.
+2. Sign in with the administrator account created during setup.
+3. Confirm the company, tax identifier, base currency, and fiscal settings are correct.
+4. Review the dashboard totals before entering live work.
+
+## Initial setup notes
+
+For a brand-new non-development installation, the deployer must provide:
+
+- `Bootstrap:AdminPassword`
+- optionally `Bootstrap:CompanyName`
+- optionally `Bootstrap:LegalName`
+- optionally `Bootstrap:AdminUserName`
+- optionally `Bootstrap:AdminDisplayName`
+- optionally `Bootstrap:AdminEmail`
+
+## First-day walkthrough
+
+1. Review `Overview`.
+2. Confirm the chart of accounts in `Ledger`.
+3. Review open customer and invoice activity in `Receivables`.
+4. Review vendor balances and due items in `Payables`.
+5. Review inventory and order flow in `Operations`.
+6. Review employee and payroll setup in `Payroll`.
+7. Review jobs in `Projects`.
+8. Review output options in `Reporting` and `Taxes`.
+
+## Next guides
+
+- Main operator guide: [user-guide.md](user-guide.md)
+- Reporting, checks, forms, and labels: [reporting-guide.md](reporting-guide.md)
+- Administration guidance: [administration-guide.md](administration-guide.md)

docs/user-guide.md

@@ -178,7 +178,7 @@ Current expectations:
 
 - authenticated access is required before users can load accounting data
 - confidential data should live in the database, not copied publish folders
-- local fallback data under `App_Data` should not be committed to Git
+- local fallback data directories should not be committed to Git
 - static site assets should come from `BrassLedger.Web/wwwroot`
 - published output under `artifacts` should be treated as disposable packaging