# Architecture

## Tech Stack

**Language:** Rust (2021 edition)

### Key Dependencies

| Crate               | Purpose                             |
|---------------------|-------------------------------------|
| `chumsky`           | Parser combinator library           |
| `ariadne`           | Error reporting with source spans   |
| `rkyv`              | Zero-copy serialization             |
| `rustyline`         | REPL readline interface             |
| `egglog-union-find` | Union-find for congruence closure   |
| `roaring`           | Bitmap library for sparse relations |
| `indexmap`          | Order-preserving hash maps          |
| `memmap2`           | Memory-mapped file I/O              |

### Testing

- `insta` — snapshot testing
- `proptest` — property-based testing
- `tempfile` — temporary directory management

---

## System Layers

```
┌─────────────────────────────────────────────────────┐
│                    USER INTERFACE                    │
│  REPL (interactive CLI) | Batch file loading         │
├─────────────────────────────────────────────────────┤
│         PARSING LAYER (Lexer → Parser → AST)         │
├─────────────────────────────────────────────────────┤
│           ELABORATION LAYER (AST → Core IR)          │
│  Type checking, name resolution, theory/instance     │
├─────────────────────────────────────────────────────┤
│            CORE LAYER (Typed Representation)         │
│  Signature, Term, Formula, Structure                 │
├─────────────────────────────────────────────────────┤
│              STORAGE LAYER (Persistence)             │
│  Append-only store with version control              │
├─────────────────────────────────────────────────────┤
│            QUERY & SOLVER LAYER (Execution)          │
│  Chase algorithm, congruence closure, model search   │
├─────────────────────────────────────────────────────┤
│         TENSOR ALGEBRA (Axiom Checking)              │
│  Sparse tensor evaluation for axiom validation       │
└─────────────────────────────────────────────────────┘
```

---

## Directory Structure

| Path                | Purpose                                      |
|---------------------|----------------------------------------------|
| `src/bin/geolog.rs` | CLI entry point                              |
| `src/lib.rs`        | Library root                                 |
| `src/repl.rs`       | Interactive REPL state machine               |
| `src/lexer.rs`      | Tokenization                                 |
| `src/parser.rs`     | Token stream → AST                           |
| `src/ast.rs`        | Abstract syntax tree types                   |
| `src/core.rs`       | Core IR: Signature, Term, Formula, Structure |
| `src/elaborate/`    | AST → Core elaboration                       |
| `src/store/`        | Persistence layer                            |
| `src/query/`        | Chase algorithm, relational algebra          |
| `src/solver/`       | SMT-style model enumeration                  |
| `src/tensor/`       | Sparse tensor algebra                        |
| `src/cc.rs`         | Congruence closure (union-find)              |
| `examples/geolog/`  | 30+ example `.geolog` files                  |
| `tests/`            | Test files                                   |
| `docs/`             | ARCHITECTURE.md, SYNTAX.md                   |
| `proofs/`           | Lean4 formalization                          |

---

## Key Entry Points

| Entry Point | Location |
|-------------|----------|
| CLI | `src/bin/geolog.rs` |
| Parse | `src/lib.rs::parse()` |
| REPL | `src/repl.rs::ReplState::process_line()` |
| Theory elaboration | `elaborate/theory.rs::elaborate_theory()` |
| Instance elaboration | `elaborate/instance.rs::elaborate_instance_ctx()` |
| Chase | `query/chase.rs::chase_fixpoint_with_cc()` |
| Model enumeration | `solver/mod.rs::enumerate_models()` |

---

## REPL Commands

```
:list, :inspect <name>         - Introspection
:add, :assert, :retract        - Mutations
:query, :explain, :compile     - Query analysis
:chase, :solve, :extend        - Inference
:commit, :history              - Version control
:source <file>                 - Load programs
:help                          - Show help
```