1092d34c39
- Add k8s/ manifests (StatefulSet, kustomize, PDB, ServiceMonitor) + docs/runbooks/kubernetes.md - Add tidal-server/src/openapi.rs (utoipa OpenAPI spec) and wire into router - Add docs/guides/ (build-a-feed-app, embeddings, server-deployment) + foryou_feed example - Consolidate tidal/docker/ into root docker/ (single canonical home) - Update API.md, QUICKSTART.md, README.md, CLAUDE.md, check-docs.sh accordingly
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# tidaldb crate
|
||
|
||
This is the **`tidaldb` engine crate** — the embeddable database at `tidal/` within the
|
||
standalone tidalDB workspace. It is one crate among workspace siblings (`tidal-net/`,
|
||
`tidal-server/`, `tidalctl/`); it does **not** carry its own copy of the project docs.
|
||
|
||
## Canonical docs live at the workspace root — not here
|
||
|
||
There is exactly one documentation home: the repository root and `docs/`. Do **not**
|
||
re-create a `tidal/docs/`, `tidal/ai-lookup/`, `tidal/site/`, or `tidal/README.md`
|
||
— those were a stale mirror and were consolidated away. Read and edit the canonical files:
|
||
|
||
| For… | Read |
|
||
|------|------|
|
||
| Project instructions, structure, agents, skills, rules | [`../CLAUDE.md`](../CLAUDE.md) |
|
||
| Vision / use cases / sequences / architecture | [`../VISION.md`](../VISION.md), [`../USE_CASES.md`](../USE_CASES.md), [`../SEQUENCE.md`](../SEQUENCE.md), [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
|
||
| API / quickstart / coding standards / lessons | [`../API.md`](../API.md), [`../QUICKSTART.md`](../QUICKSTART.md), [`../CODING_GUIDELINES.md`](../CODING_GUIDELINES.md), [`../thoughts.md`](../thoughts.md) |
|
||
| Component specs (00–14), research, planning, ops, runbooks | [`../docs/`](../docs/) |
|
||
| Domain concept reference | [`../ai-lookup/index.md`](../ai-lookup/index.md) |
|
||
| Milestone history + known gaps | [`../CHANGELOG.md`](../CHANGELOG.md) |
|
||
|
||
## Crate-local layout (`tidal/src/`, flat module layout)
|
||
|
||
| Module | Responsibility |
|
||
|--------|----------------|
|
||
| `cohort/` | Cohort-scoped signal aggregation |
|
||
| `db/` | Top-level `TidalDb` + builder |
|
||
| `entities/` | Item / User / Creator entity model |
|
||
| `load/` | Bulk load / ingest paths |
|
||
| `query/` | Query parser, planner, executor (RETRIEVE/SEARCH/SUGGEST) |
|
||
| `ranking/` | Profile engine, signal scoring, diversity enforcement |
|
||
| `replication/` | WAL-stream replication for cluster mode |
|
||
| `schema/` | Schema builder, validation, signal/profile defs |
|
||
| `session/` | Session + agent context, policies |
|
||
| `signals/` | Signal types, decay, velocity, windowed aggregation |
|
||
| `storage/` | Entity store, signal ledger, inverted index, HNSW |
|
||
| `testing/` | Shared test harness + fixtures |
|
||
| `text/` | Tantivy full-text indexing |
|
||
| `wal/` | Write-ahead log + crash recovery |
|
||
|
||
`benches/`, `examples/` (quickstart, foryou_feed, axum_embedding, actix_embedding,
|
||
cli_embedding), and `tests/` (integration + crash-property) round out the crate.
|
||
Container images live at the workspace root under [`../docker/`](../docker/)
|
||
(`standalone` / `cluster` / `deploy`), not per-crate — build them from the repo
|
||
root so `COPY . .` sees the whole workspace.
|
||
|
||
## Build & test (workspace-aware)
|
||
|
||
Run cargo from the **workspace root**, targeting this crate with `-p tidaldb`
|
||
(equivalently `--manifest-path tidal/Cargo.toml`):
|
||
|
||
```bash
|
||
cargo test -p tidaldb # unit + integration
|
||
cargo clippy -p tidaldb -D warnings
|
||
cargo fmt
|
||
```
|
||
|
||
**Tests must be fast.** Slow or hanging tests are bugs — fix the root cause, never leave them hanging.
|