Metadata-Version: 2.4
Name: tuladb-dashboard
Version: 0.0.1rc0
Summary: TulaDB operations dashboard: FastAPI backend and React frontend
Author: TulaDB
License-Expression: LicenseRef-TulaDB-Source-Available
Project-URL: Homepage, https://tuladb.com
Project-URL: Repository, https://github.com/TulaDB/tuladb-dashboard
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: tuladb-sdk
Provides-Extra: lake
Requires-Dist: duckdb==1.5.6; extra == "lake"
Requires-Dist: numpy>=1.26; extra == "lake"
Requires-Dist: google-auth>=2.30; extra == "lake"
Requires-Dist: requests>=2.31; extra == "lake"
Requires-Dist: boto3>=1.34; extra == "lake"
Requires-Dist: botocore[crt]; extra == "lake"
Dynamic: license-file

# TulaDB Dashboard

Dashboard/demo UI for TulaDB developer preview.

The dashboard helps reviewers and operators inspect accounts, balances, transfers, reservations, rejected records, route configuration, and runtime health.

## Repository boundary

- Backend/API facade: `dashboard/app.py`.
- Frontend: `dashboard/frontend`.
- SDK dependency: install from `../tuladb-sdk/python` for local development.
- Ledger registry data lives in the engine. `dashboard/data/ledger_instances.json`
  is only a local display-name sidecar and should not be committed unless
  intentionally seeded.

## Deploying

The release images are `tuladb-dashboard-backend` and
`tuladb-dashboard-frontend` (ghcr.io). The frontend serves HTTP on 80; in prod
the session cookie is `Secure`, so terminate TLS in front of it or mount a
certificate and set `TULADB_TLS_CERT_FILE`/`TULADB_TLS_KEY_FILE` to have it
listen on 443 itself. See [docs/security.md](docs/security.md).

## Offline install

Each release also publishes an offline bundle -- the dashboard as a wheel with
the built frontend, a hashed wheelhouse for Linux x86_64 and aarch64
(Python 3.12), the DuckDB extensions and an installer that needs no network
-- at `https://downloads.tuladb.com/dashboard/<version>/`. See
[docs/offline-install.md](docs/offline-install.md).

## Run locally

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --require-hashes -r dashboard/requirements.lock   # or requirements-lake.lock
python -m pip install -e ../tuladb-sdk/python
uvicorn dashboard.app:app --host 127.0.0.1 --port 8000
```

Frontend:

```bash
cd dashboard/frontend
npm install
npm run dev
```

## Lake (optional)

The **Lake** screen reads the Iceberg mirror written by `tuladb-iceberg-exporter`
through a sandboxed DuckDB worker: a table browser, a read-only SQL terminal,
and the exporter's watermark saying how fresh the lake is. It reads GCP BigLake or AWS S3 Tables. Install
`dashboard/requirements-lake.txt` and set `TULADB_LAKE_CATALOG_TYPE` (plus the
catalog settings). See [docs/lake-query.md](docs/lake-query.md).

## Transaction identity rule

Transaction detail pages must use `transfer_id`.

- `transfer_id` is the canonical exact transaction identity.
- `txn_id` is a client/business reference and may not be globally unique by itself.
- Searching by `txn_id` may return multiple records.
- Detail routes should be shaped like `/transfers/{transfer_id}`.

## Validation

```bash
python3 -m py_compile dashboard/app.py
cd dashboard/frontend
npm install
npm run build
```

## Status

Developer preview. Before production use, add authentication/RBAC, deployment hardening, audit identity, and environment-specific secrets handling.

## Quality gate

Run `bash scripts/quality_gate.sh` to validate backend syntax, frontend build, and source ignore rules.
