# realzachi/pg-jev architecture

> Architecture diagram of the GitHub repository realzachi/pg-jev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/realzachi/pg-jev
- Repository: https://github.com/realzachi/pg-jev

## Overview

jev is a PostgreSQL extension for filtering, ranking, and classifying table rows with plain-language questions. A SQL query invokes its functions; on a cache miss, jev reads rows ahead, batches questions, and sends requests to a Jev-compatible API. Returned probabilities support boolean predicates, ranking, and choice classification, and answers are cached per backend session. The README documents this runtime flow and configuration, but no implementation excerpts were supplied, so the graph uses the extension SQL path and cites only documented relationships.

Main entry points: [`sql/jev--0.2.1.sql`](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql) (Answer cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["SQL interface"]
  node_jev_predicate["jev predicate<br/>[jev--0.2.1.sql]"]
  node_jev_probability["jev probability<br/>[jev--0.2.1.sql]"]
  node_jev_choice["jev choice<br/>[jev--0.2.1.sql]"]
  node_jev_score["jev score<br/>[jev--0.2.1.sql]"]
end

subgraph group_evaluation["Row evaluation"]
  node_read_ahead["Row read-ahead<br/>[jev--0.2.1.sql]"]
  node_batching["Question batching<br/>[jev--0.2.1.sql]"]
  node_probabilities["Row probabilities<br/>[jev--0.2.1.sql]"]
end

subgraph group_connections["API connections"]
  node_connection_pool["HTTPS connection pool<br/>[jev--0.2.1.sql]"]
  node_settings["Runtime settings<br/>[jev--0.2.1.sql]"]
end

subgraph group_session["Session state"]
  node_answer_cache["Answer cache<br/>[jev--0.2.1.sql]"]
  node_cache_clear["Cache clear<br/>[jev--0.2.1.sql]"]
end

node_sql_client(("SQL query"))
node_postgres[("PostgreSQL")]
node_jev_api{{"Jev-compatible API"}}

node_sql_client -->|"submits query"| node_postgres
node_postgres -->|"invokes"| node_jev_predicate
node_postgres -->|"invokes"| node_jev_probability
node_postgres -->|"invokes"| node_jev_choice
node_postgres -->|"invokes"| node_jev_score
node_jev_predicate -->|"starts on miss"| node_read_ahead
node_read_ahead -->|"supplies rows"| node_batching
node_batching -->|"dispatches requests"| node_connection_pool
node_connection_pool -->|"sends HTTPS"| node_jev_api
node_jev_api -->|"returns answers"| node_probabilities
node_probabilities -->|"caches answers"| node_answer_cache
node_answer_cache -->|"serves cached answers"| node_jev_predicate
node_answer_cache -->|"serves cached answers"| node_jev_probability
node_answer_cache -.->|"serves cached answers"| node_jev_choice
node_answer_cache -.->|"serves cached answers"| node_jev_score
node_cache_clear -->|"clears"| node_answer_cache
node_settings -.->|"configures"| node_connection_pool
node_settings -->|"selects endpoint"| node_jev_api

click node_jev_predicate "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_jev_probability "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_jev_choice "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_jev_score "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_read_ahead "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_batching "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_probabilities "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_answer_cache "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_cache_clear "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_connection_pool "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"
click node_settings "https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_jev_predicate,node_jev_probability,node_jev_choice,node_jev_score toneBlue
class node_read_ahead,node_batching,node_probabilities,node_postgres toneAmber
class node_connection_pool,node_settings,node_jev_api toneMint
class node_answer_cache,node_cache_clear toneRose
class node_sql_client toneIndigo
```

## Components

### SQL interface

- [jev predicate](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [jev probability](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [jev choice](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [jev score](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`

### Row evaluation

- [Row read-ahead](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [Question batching](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [Row probabilities](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`

### API connections

- [HTTPS connection pool](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [Runtime settings](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`

### Session state

- [Answer cache](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`
- [Cache clear](https://github.com/realzachi/pg-jev/blob/master/sql/jev--0.2.1.sql): `sql/jev--0.2.1.sql`

### Other components

- **SQL query**
- **PostgreSQL**
- **Jev-compatible API**

## Connections

- SQL query → PostgreSQL: submits query (evidence: `README.md`)
- PostgreSQL → jev predicate: invokes (evidence: `README.md`)
- PostgreSQL → jev probability: invokes (evidence: `README.md`)
- PostgreSQL → jev choice: invokes (evidence: `README.md`)
- PostgreSQL → jev score: invokes (evidence: `README.md`)
- jev predicate → Row read-ahead: starts on miss (evidence: `README.md`)
- Row read-ahead → Question batching: supplies rows (evidence: `README.md`)
- Question batching → HTTPS connection pool: dispatches requests (evidence: `README.md`)
- HTTPS connection pool → Jev-compatible API: sends HTTPS (evidence: `README.md`)
- Jev-compatible API → Row probabilities: returns answers (evidence: `README.md`)
- Row probabilities → Answer cache: caches answers (evidence: `README.md`)
- Answer cache → jev predicate: serves cached answers (evidence: `README.md`)
- Answer cache → jev probability: serves cached answers (evidence: `README.md`)
- Answer cache → jev choice: serves cached answers
- Answer cache → jev score: serves cached answers
- Cache clear → Answer cache: clears (evidence: `README.md`)
- Runtime settings → HTTPS connection pool: configures
- Runtime settings → Jev-compatible API: selects endpoint (evidence: `README.md`)
