Add a project overview document project

docs/project-overview.md

@@ -0,0 +1,82 @@
+## About the Project
+
+Chase-rs is a Rust implementation of the chase algorithm for reasoning over rules and facts.
+It is designed for database-theory style workloads such as:
+
+- query answering under tuple-generating dependencies
+- materializing implied facts from rules
+- working with existential rules that create fresh labeled nulls
+
+The project focuses on correctness first, while still keeping the codebase small, fast, and idiomatic.
+
+## Main Features
+
+- Core chase engine for deriving implied facts from rules and an initial instance
+- Restricted-chase style active-trigger checks for existential rules
+- Automatic generation of labeled nulls for existential variables
+- Fluent `RuleBuilder` API for constructing rules in Rust
+- Configurable step limit through `chase_with_config`
+- Interactive frontend options:
+    - REPL
+    - script runner
+    - local GUI
+- Querying and explanation support in the frontend session layer
+- Example scripts and Geolog examples for transitive closure, existential rules, and joins
+
+---
+
+## Quickstart
+
+### 1. Run the example script
+
+```bash
+cargo run -- script examples/scripts/ancestor.chase
+```
+
+This loads a few `Parent` facts, applies ancestor rules, runs the chase, and prints the derived answers.
+
+### 2. Open the REPL
+
+```bash
+cargo run -- repl
+```
+
+In the REPL you can add facts, add rules, run the chase, query results, and ask for explanations.
+
+### 3. Open the GUI
+
+```bash
+cargo run -- gui
+```
+
+This starts a local web UI at [http://127.0.0.1:7878](http://127.0.0.1:7878) where you can type the same commands as in the REPL.
+
+---
+
+### Glossary of Important Terms
+
+- **Atom**: A predicate applied to one or more terms, for example `Parent(alice, bob)`.
+- **Fact**: A ground atom, meaning an atom with no variables. Facts are the input database state.
+- **Instance**: The set of facts currently known to the chase engine.
+- **Rule / TGD**: A tuple-generating dependency of the form `body -> head` that derives new facts when its body matches.
+- **Chase**: The process of repeatedly applying rules until no new facts can be derived or a configured step limit is reached.
+- **Materialization**: The fully derived instance produced by running the chase.
+- **Existential Rule**: A rule whose head contains variables that do not appear in the body. These variables represent values that must be invented.
+- **Labeled Null**: A fresh invented value used to satisfy an existential variable during the chase.
+- **Restricted Chase**: The chase variant used by default in this project. It avoids redundant applications by checking whether a trigger is still
+  active.
+- **Trigger**: A particular match of a rule body against the current instance.
+- **Active Trigger**: A trigger that still requires the rule to fire because its head is not already satisfied.
+- **Query**: A conjunctive pattern used to ask for matching facts after, or sometimes before, materialization.
+- **Explanation**: A derivation trace that shows why a query answer is present.
+- **Termination**: Whether the chase finished normally or stopped because it reached the configured step bound.
+
+### Example Terms
+
+- `Parent`, `Ancestor`, and `WorksIn` are example predicates used in the scripts.
+- `?X`, `?Y`, and `?Dept` are variables in the frontend command language.
+- `alice`, `bob`, and `carol` are constants.
+
+### Changelog
+
+* **April 8, 2026** -- The first version of this document was written.