docs: describe the database as an external service

The docs still documented the in-repo database service that was removed in
c785f9c: src/database/, ./build/smartbotic-database, database.json, and its
WAL/snapshot settings. systemd/README.md also referenced a smartbotic-database
user unit that no longer exists (the daemon ships as a system service with the
upstream package).

Updates the architecture sections, service lists, port tables and run
instructions, documents the database_address and database_project settings
with their env overrides, and replaces the stale camelCase webserver.json
example with the real snake_case config.

CLAUDE.md

@@ -35,34 +35,56 @@ npm run lint     # ESLint
 
 ## Running Services
 
-Services must start in order due to dependencies:
+The database is **not** built from this repo - it is the standalone upstream
+`smartbotic-database` daemon, installed from the SmartBotics APT repository and
+managed as a system service. Start it first, then the in-repo services:
 
 ```bash
-# 1. Database service first (gRPC port 9010)
-./build/smartbotic-database
+# 1. Upstream database daemon (gRPC port 9004)
+sudo systemctl start smartbotic-database
 
-# 2. WebServer (HTTP port 8090, gRPC port 9002)
+# 2. WebServer (HTTP port 8090, gRPC port 9012)
 ./build/smartbotic-webserver
 
 # 3. Runner(s) (gRPC port 9011)
 ./build/smartbotic-runner
 
-# Or use systemd
+# Or use systemd for the in-repo services
 systemctl --user start smartbotic.target
 journalctl --user -u smartbotic-* -f
 ```
 
+Both the database address and the project namespace are configurable everywhere,
+via `config/webserver.json` and `config/runner.json`:
+
+| Key | Default | Env override |
+| --- | --- | --- |
+| `database_address` | `localhost:9004` | `DATABASE_ADDRESS` |
+| `database_project` | `smartbotic-automation` | `DATABASE_PROJECT` |
+
+One `smartbotic-database` instance is shared by several projects. `database_project`
+is the multi-tenant namespace (upstream client >= 2.3): the client transparently
+sends every collection as `<project>:<collection>`, so our data stays isolated from
+other services on the same daemon. Never set it to `default` - that is the shared
+back-compat namespace where projects collide.
+
 ## Architecture
 
-### Three Microservices
+### Two In-Repo Services + External Database
 
-1. **Database Service** (src/database/) - gRPC storage server with in-memory store, WAL persistence, and snapshots
-2. **WebServer Service** (src/webserver/) - HTTP REST API, WebSocket for real-time updates, JWT auth, runner registry
-3. **Runner Service** (src/runner/) - Workflow execution engine with QuickJS for JavaScript node evaluation
+1. **WebServer Service** (src/webserver/) - HTTP REST API, WebSocket for real-time updates, JWT auth, runner registry
+2. **Runner Service** (src/runner/) - Workflow execution engine with QuickJS for JavaScript node evaluation
+
+Both persist through the external **smartbotic-database** daemon (upstream repo:
+`ssh://git@git.smartbotics.ai:10022/fszontagh/smartbotic-database.git`), consumed
+as the `libsmartbotic-db-client-dev` APT package. `cmake/FindPackages.cmake` locates
+it via `find_package(smartbotic-db-client CONFIG REQUIRED)` → target `smartbotic::db-client`.
+`lib/storage/storage_client.{hpp,cpp}` is a thin PIMPL adapter over
+`smartbotic::database::Client`, so callers never touch the upstream API directly.
 
 ### Data Flow
 ```
-WebUI (React) → HTTP/WebSocket → WebServer → gRPC → Database
+WebUI (React) → HTTP/WebSocket → WebServer → gRPC → smartbotic-database (external)
                                      ↓
                               gRPC → Runner(s) → executes workflows
 ```
@@ -117,9 +139,11 @@ Runners automatically receive node updates via gRPC streaming - no restart requi
 ### Configuration
 
 Services load JSON configs from `config/` directory:
-- `database.json` - Storage settings, WAL/snapshot intervals
-- `webserver.json` - HTTP port, JWT settings, runner load balancing
-- `runner.json` - Runner ID, max concurrent executions, hot reload settings
+- `webserver.json` - HTTP port, JWT settings, runner load balancing, `database_address`
+- `runner.json` - Runner ID, max concurrent executions, hot reload settings, `database_address`
+
+The database daemon has its own config at `/etc/smartbotic-database/config.json`,
+owned by the upstream package - not by this repo.
 
 Environment variables can override config values using `${VAR_NAME:default}` syntax.
 

README.md

@@ -37,17 +37,20 @@ SmartBotic consists of three microservices:
      ↓       ↓
 ┌─────────┐ ┌──────────┐
 │Database │ │ Runner(s)│  Workflow Execution
-│(Pt 9010)│ │(Pt 9011) │  QuickJS Engine
-└─────────┘ └──────────┘
+│(Pt 9004)│ │(Pt 9011) │  QuickJS Engine
+│ external│ └──────────┘
+└─────────┘
 ```
 
 ### Services
 
-1. **Database Service** (`src/database/`)
-   - In-memory key-value storage with gRPC API
-   - Write-Ahead Log (WAL) for durability
-   - Periodic snapshots for recovery
-   - Prefix-based queries and watch support
+1. **Database** (external - *not built from this repo*)
+   - The standalone `smartbotic-database` daemon, developed at
+     `ssh://git@git.smartbotics.ai:10022/fszontagh/smartbotic-database.git`
+   - Installed from the SmartBotics APT repository as `smartbotic-database`;
+     this repo links against its `libsmartbotic-db-client-dev` package
+   - Document store with gRPC API, WAL durability, snapshots, and encryption
+   - Configured independently at `/etc/smartbotic-database/config.json`
 
 2. **WebServer Service** (`src/webserver/`)
    - HTTP REST API for workflows, nodes, and executions
@@ -105,7 +108,6 @@ make -j$(nproc)
 ```
 
 Binaries will be created in the `build/` directory:
-- `smartbotic-database`
 - `smartbotic-webserver`
 - `smartbotic-runner`
 
@@ -136,8 +138,8 @@ Services must be started in order due to dependencies:
 ### Manual Start
 
 ```bash
-# 1. Start Database service (must be first)
-./build/smartbotic-database
+# 1. Start the external database daemon (must be first)
+sudo systemctl start smartbotic-database
 
 # 2. Start WebServer (depends on Database)
 ./build/smartbotic-webserver
@@ -169,7 +171,7 @@ Unit files are provided in the `systemd/` directory.
 - **WebUI Dev Server**: 3000
 - **WebServer HTTP API**: 8090
 - **WebServer gRPC**: 9002
-- **Database gRPC**: 9010
+- **Database gRPC**: 9004 (external daemon)
 - **Runner gRPC**: 9011
 
 ### Default Credentials
@@ -183,22 +185,49 @@ Unit files are provided in the `systemd/` directory.
 
 Services load JSON configuration files from the `config/` directory:
 
-- `database.json` - Storage settings, WAL/snapshot intervals
-- `webserver.json` - HTTP port, JWT settings, CORS, runner load balancing
-- `runner.json` - Runner ID, max concurrent executions, node hot reload
+- `webserver.json` - HTTP port, JWT settings, CORS, runner load balancing, `database_address`
+- `runner.json` - Runner ID, max concurrent executions, node hot reload, `database_address`
+
+The database daemon is configured separately at `/etc/smartbotic-database/config.json`,
+which is owned by the upstream `smartbotic-database` package.
 
 Configuration supports environment variable substitution using `${VAR_NAME:default}` syntax.
 
+### Database connection
+
+Both service configs expose the same two database settings, so the host, port and
+namespace are configurable everywhere without editing a file:
+
+| Key | Default | Env override | Purpose |
+| --- | --- | --- | --- |
+| `database_address` | `localhost:9004` | `DATABASE_ADDRESS` | Host and port of the `smartbotic-database` daemon |
+| `database_project` | `smartbotic-automation` | `DATABASE_PROJECT` | Multi-tenant namespace within that daemon |
+
+A single `smartbotic-database` instance is designed to serve **multiple projects**.
+`database_project` selects which namespace this deployment owns - the client sends
+every collection as `<project>:<collection>`, so two projects sharing one daemon
+never see each other's collections. Leave it at `smartbotic-automation` unless you
+are running more than one independent SmartBotic deployment against the same
+database, in which case give each one a distinct value.
+
+> Do not set `database_project` to `default`: that is the shared back-compat
+> namespace, where unrelated projects would collide.
+
 ### Example: `config/webserver.json`
 
 ```json
 {
-  "httpPort": 8090,
-  "grpcPort": 9002,
-  "databaseAddress": "localhost:9010",
-  "jwtSecret": "${JWT_SECRET:your-secret-key-change-in-production}",
-  "jwtExpiration": 3600,
-  "staticFilesPath": "./webui/dist"
+  "http_port": 8090,
+  "node_sync_port": 9012,
+  "credential_service_port": 9013,
+  "static_files_path": "${WEBUI_PATH:./webui/dist}",
+  "database_address": "${DATABASE_ADDRESS:localhost:9004}",
+  "database_project": "${DATABASE_PROJECT:smartbotic-automation}",
+  "auth": {
+    "jwt_secret": "${JWT_SECRET:dev-secret-change-in-production}",
+    "access_token_lifetime_sec": 900,
+    "refresh_token_lifetime_sec": 604800
+  }
 }
 ```
 
@@ -397,7 +426,8 @@ Follow conventional commits:
 
 ### Services won't start
 
-- Ensure ports 8090, 9002, 9010, 9011 are available
+- Ensure ports 8090, 9011, 9012, 9013 are available, and that the external
+  database daemon is reachable on 9004 (`systemctl status smartbotic-database`)
 - Start services in order: Database → WebServer → Runner
 - Check logs for detailed error messages
 

systemd/README.md

@@ -29,7 +29,6 @@ systemctl --user start smartbotic.target
 ### Start individual services
 
 ```bash
-systemctl --user start smartbotic-database
 systemctl --user start smartbotic-webserver
 systemctl --user start smartbotic-runner
 ```
@@ -45,7 +44,6 @@ systemctl --user stop smartbotic.target
 ```bash
 systemctl --user stop smartbotic-runner
 systemctl --user stop smartbotic-webserver
-systemctl --user stop smartbotic-database
 ```
 
 ### Restart services
@@ -58,7 +56,6 @@ systemctl --user restart smartbotic-runner
 ### Check status
 
 ```bash
-systemctl --user status smartbotic-database
 systemctl --user status smartbotic-webserver
 systemctl --user status smartbotic-runner
 ```
@@ -91,16 +88,18 @@ systemctl --user disable smartbotic.target
 ## Service Dependencies
 
 ```
-smartbotic-database
+smartbotic-database   (system service, external package)
        ↓
-smartbotic-webserver
+smartbotic-webserver  (--user)
        ↓
-smartbotic-runner
+smartbotic-runner     (--user)
 ```
 
 The services have proper dependency ordering:
-- `smartbotic-database` must start first
-- `smartbotic-webserver` depends on database and starts after it
+- `smartbotic-database` must be running first. It is **not** a user unit from this
+  repo - it ships with the upstream `smartbotic-database` package as a system
+  service: `sudo systemctl start smartbotic-database`
+- `smartbotic-webserver` depends on the database and starts after it
 - `smartbotic-runner` depends on webserver and starts after it
 
 ## Environment Variables
@@ -124,7 +123,7 @@ Environment=RUNNER_ID=my-runner
 If services fail to start, check the logs:
 
 ```bash
-journalctl --user -u smartbotic-database -e
+sudo journalctl -u smartbotic-database -e
 journalctl --user -u smartbotic-webserver -e
 journalctl --user -u smartbotic-runner -e
 ```