diff --git a/.cursor/01-expertise-and-principles.mdc b/.cursor/01-expertise-and-principles.mdc index ed8652fa..f902bfa7 100644 --- a/.cursor/01-expertise-and-principles.mdc +++ b/.cursor/01-expertise-and-principles.mdc @@ -5,7 +5,7 @@ scope: globs: ["**/*"] --- -You are an expert in **Python, FastAPI, Jinja2, Databricks SDK, Databricks REST APIs, RDF/OWL/SPARQL/SHACL standards, graph databases**, and **knowledge graph engineering**. +You are an expert in **Python, FastAPI, Jinja2, Databricks SDK, Databricks REST APIs, RDF/OWL/SPARQL/SHACL standards, graph databases**, and **graph viewer engineering**. ### Key Principles diff --git a/.cursor/02-project-overview.mdc b/.cursor/02-project-overview.mdc index 60fc1263..62329449 100644 --- a/.cursor/02-project-overview.mdc +++ b/.cursor/02-project-overview.mdc @@ -7,13 +7,13 @@ scope: ### Project Overview -OntoBricks is a **Python FastAPI** web application designed to run as a **Databricks App**. It provides ontology management, knowledge graph engineering, and metadata governance tools on top of Databricks Unity Catalog. +OntoBricks is a **Python FastAPI** web application designed to run as a **Databricks App**. It provides ontology management, graph viewer engineering, and metadata governance tools on top of Databricks Unity Catalog. **Core Features:** - **Ontology Management:** OWL/RDFS/SHACL import/export, class/property CRUD, URI management, industry ontology imports (CDISC, FIBO, IOF). Managed by the `Ontology` domain class. - **Mapping:** Entity/relationship mapping CRUD, R2RML generation/parsing, SQL validation, LLM-assisted auto-assign. Managed by the `Mapping` domain class. -- **Digital Twin:** Knowledge graph build, sync, SPARQL query, quality checks, graph visualization, community detection. Managed by the `DigitalTwin` domain class. +- **Knowledge Graph:** Knowledge graph build, sync, SPARQL query, quality checks, graph visualization, community detection. Managed by the `DigitalTwin` domain class. - **Domain Management:** Unity Catalog save/load, version status, metadata, design layout persistence. Managed by the `Domain` domain class. - **Registry:** Dual-mode domain registry with permissions and scheduled builds. Two storage modes, picked from the Databricks App config and surfaced in the **Settings → Registry** tab: 1. **Volume-only** — everything (metadata, indexes, documents, binaries) lives in a UC Volume. diff --git a/.cursor/03-system-components-and-requirements.mdc b/.cursor/03-system-components-and-requirements.mdc index 2aec1ead..9857c06f 100644 --- a/.cursor/03-system-components-and-requirements.mdc +++ b/.cursor/03-system-components-and-requirements.mdc @@ -12,7 +12,7 @@ scope: - **Domain Classes:** Business logic lives in `back/objects/` (not in route handlers). Current classes: - `Ontology` — OWL/RDFS/SHACL operations, class/property CRUD, URI management. - `Mapping` — entity/relationship mapping CRUD, R2RML, SQL validation, auto-assign. - - `DigitalTwin` — knowledge graph build, sync, query, quality. + - `DigitalTwin` — graph viewer build, sync, query, quality. - `Domain` — UC save/load, version status, metadata, layout persistence. - **Core Infrastructure:** `back/core/` hosts shared infrastructure with no dependency on HTTP/FastAPI types: Databricks clients, triple store, graph DB, W3C parsers, reasoning engines, agents, logging, errors. - **Internal API:** Session-aware JSON endpoints in `api/routers/internal/`, delegating to domain classes. diff --git a/.cursor/04-project-structure.mdc b/.cursor/04-project-structure.mdc index 904dfb6f..69e01839 100644 --- a/.cursor/04-project-structure.mdc +++ b/.cursor/04-project-structure.mdc @@ -49,7 +49,7 @@ back/objects/ ├── domain/ <- Session-scoped UC/metadata/layout operations ├── ontology/ <- Ontology domain class ├── mapping/ <- Mapping domain class -└── digitaltwin/ <- Digital Twin domain class +└── digitaltwin/ <- Knowledge Graph domain class ``` ### Backend Core Infrastructure (`src/back/core/`) diff --git a/.cursor/07-project-conventions.mdc b/.cursor/07-project-conventions.mdc index dc37e536..9e43a38f 100644 --- a/.cursor/07-project-conventions.mdc +++ b/.cursor/07-project-conventions.mdc @@ -115,3 +115,39 @@ scope: # Bad from back.objects.registry import RegistryService ``` + +### Merge Safety (feature branch → develop) + +When merging `develop` into a long-lived feature branch (or resolving conflicts before a PR): + +1. **Feature branch is always the source of truth.** Resolve every conflict with `--ours` + unless the change from `develop` is a genuine independent improvement to a shared file. + +2. **Auto-merges are not safe.** Git can silently resolve a file with no conflict markers + while still discarding feature content (it picks one side's structure). Always verify + critical wiring files after the merge, even when git reports success. + +3. **After any merge, diff these files between the pre-merge tip and the new HEAD:** + ```bash + git diff HEAD -- \ + src/front/templates/base.html \ + src/front/templates/domain.html \ + src/front/config/menu_config.json \ + src/api/routers/internal/__init__.py \ + src/front/static/ontology/js/ontology-map.js + ``` + These are the most likely victims of silent auto-merge data loss because both branches + edit them for unrelated reasons. + +4. **Restore silently-lost files** from the pre-merge feature commit: + ```bash + git checkout -- + git add + ``` + +5. **Run the full test suite** (`pytest tests/units/ -q`) before committing the merge. + A passing suite does not guarantee the UI is intact, but a failing one always indicates + a problem. + +6. **Commit message** for the merge should list which conflict types were resolved and + which files were restored, so reviewers can audit the decision. diff --git a/.cursor/11-frontend-design.mdc b/.cursor/11-frontend-design.mdc index f473d0bc..6e793928 100644 --- a/.cursor/11-frontend-design.mdc +++ b/.cursor/11-frontend-design.mdc @@ -91,8 +91,10 @@ the entire app chrome — never duplicate or substitute any of it: | Element | Provided by `base.html` | Don't reimplement | |---------|-------------------------|-------------------| -| Navbar (top) | `