Fulfillment Hub: A Guided CSharpDB Sample

Most database samples are too small to teach much. A todo list can show inserts and queries, but it does not show what happens when a real application needs forms, reports, imports, exports, operational procedures, search, and semi-structured event data.

samples/fulfillment-hub is designed to be the opposite. It gives you a small warehouse and order-fulfillment system with one working database and enough moving parts to see how CSharpDB features fit together.

What the Sample Creates

Running the sample creates a fresh fulfillment-hub-demo.db database. The seeder loads more than SQL schema; it also stores the metadata-driven parts that Admin can run later.

• Relational tables for customers, products, inventory, orders, purchase orders, shipments, returns, carriers, suppliers, and audit events.
• Views such as order_fulfillment_board, low_stock_watch, purchase_order_receiving_board, and shipment_manifest_report_source.
• Stored procedures for allocation, receiving, shipment creation, returns, and operational stats.
• Admin forms for order work, purchase-order receiving, and return intake.
• Admin reports for the open order queue, low-stock watch, and shipment manifest.
• Stored pipeline packages for CSV import, JSON import, and low-stock export.
• Typed collections for scanner sessions and webhook archives.
• A full-text index over operational playbooks.

Step 1: Run the Seeder

From the repository root, run the sample project:

dotnet run --project samples\fulfillment-hub\FulfillmentHubSample.csproj

Each run deletes and recreates the demo database in the build output folder:

samples\fulfillment-hub\bin\Debug\net10.0\fulfillment-hub-demo.db

The console output should show counts for forms, reports, procedures, saved queries, stored pipelines, pipeline runs, collections, and the full-text index. It also prints a few query results so you know the database was seeded successfully.

Step 2: Start Admin Against the Sample

CSharpDB Admin reads its local database from ConnectionStrings:CSharpDB. The easiest way to point Admin at the sample is to set the connection string for this terminal session and then run the Admin project.

$sampleDb = (Resolve-Path .\samples\fulfillment-hub\bin\Debug\net10.0\fulfillment-hub-demo.db).Path
$env:ConnectionStrings__CSharpDB = "Data Source=$sampleDb"
$env:CSharpDB__Transport = "direct"

dotnet run --project src\CSharpDB.Admin\CSharpDB.Admin.csproj

The development launch profile uses these URLs:

• https://localhost:61816
• http://localhost:61817

If those ports are already busy, run without the launch profile and choose a local URL:

dotnet run --no-launch-profile --project src\CSharpDB.Admin\CSharpDB.Admin.csproj -- --urls http://127.0.0.1:6190

Step 3: Confirm You Opened the Right Database

When Admin opens, check the title bar and Object Explorer. You should see the Fulfillment Hub database path and a populated object tree.

The useful signal is not just that tables exist. You should also see:

• Forms with Order Workbench, Purchase Order Receiving, and Return Intake.
• Reports with Low Stock Watch, Open Order Queue, and Shipment Manifest.
• Views with operational read models such as order_fulfillment_board and low_stock_watch.
• Procedures with AllocateOrder, ReceivePurchaseOrder, CreateShipment, RecordReturn, and RefreshOperationalStats.

Step 4: Start With the Order Board

Open a query tab in Admin and run the main operational queue:

SELECT order_number, customer_name, warehouse_code, order_status, required_ship_date
FROM order_fulfillment_board
WHERE order_status IN ('released', 'allocated', 'picking')
ORDER BY required_ship_date, priority_code DESC, order_number;

This is the first lesson in the sample: CSharpDB features are not isolated demos. The same order workflow is visible through a view, a saved query, a form, a report, and stored procedures.

Step 5: Use the Forms

Open Forms in the Object Explorer and start with Order Workbench. This form is bound to the orders table and includes child data for order lines.

Then open Purchase Order Receiving. That form is tied to the purchase-order model and helps you inspect the same receiving data that the procedure updates.

Finally, open Return Intake. It shows how reverse logistics can live beside outbound fulfillment without becoming a separate system.

Step 6: Run Operational Procedures

Procedures let you package multi-statement operational work. You can run them from SQL tabs with EXEC commands.

EXEC RefreshOperationalStats;

EXEC ReceivePurchaseOrder purchaseOrderId=9001;

EXEC AllocateOrder orderId=7005;

EXEC CreateShipment orderId=7001, shipmentId=8101, shipmentNumber='SHP-8101', carrierId=2;

After each procedure, rerun the related view. This is where the sample starts to feel like a small operations system: receiving changes inventory, allocation changes order state, and shipment creation produces report-ready data.

Step 7: Open the Reports

The sample ships with three Admin reports. They are intentionally tied to the same operational story:

• Open Order Queue shows the work waiting on the floor.
• Low Stock Watch shows shortage pressure by warehouse and SKU.
• Shipment Manifest shows shipment-ready output from a report-shaped view.

Run CreateShipment, then open the shipment report. That connects the procedural workflow to the reporting surface.

Step 8: Inspect Pipelines

The seeder stores and runs three pipeline packages:

• supplier-receipts-import imports CSV receiving data.
• marketplace-orders-import imports JSON marketplace orders.
• low-stock-export exports the low-stock view to CSV.

In Admin, open the pipeline area and inspect the stored packages and run history. Then check the generated export file:

samples\fulfillment-hub\bin\Debug\net10.0\generated-output\low-stock-watch.csv

Step 9: Look at Collections and Full-Text Search

Fulfillment Hub also includes data that does not need to be forced into normal relational tables. The sample seeds two collections:

• scanner_sessions for handheld scanner state.
• webhook_archive for external event payloads.

It also creates a full-text index called fts_ops_playbooks over the ops_playbooks table. That gives the sample a place for operational runbooks next to the live data.

The sample project demonstrates the full-text query through the engine API:

await using var db = await Database.OpenAsync("samples/fulfillment-hub/bin/Debug/net10.0/fulfillment-hub-demo.db");
var hits = await db.SearchAsync("fts_ops_playbooks", "partial receipt");

How to Learn From the Sample

The best way to use Fulfillment Hub is to treat it like a live system, not a collection of files.

1. Run the seeder.
2. Open the generated database in Admin.
3. Run one query against a view.
4. Open the matching form or report.
5. Run a procedure that changes the workflow.
6. Reopen the view, form, and report to see what changed.

That loop is the point of the sample. It shows how CSharpDB can hold the transactional model, the operational read models, the metadata-driven UI, the reporting layer, the integration pipelines, and supporting document-style data in one local database.