aeo_graph_explorer/
lib.rs

1//! # aeo-graph-explorer
2//!
3//! HTTP graph-query service over AEO Protocol crawls.
4//!
5//! ## The fifth layer of the AEO Reference Stack
6//!
7//! ```text
8//! 1. SDKs       aeo-sdk-python / -typescript / -rust / -go / -swift
9//! 2. CLI        aeo-cli
10//! 3. Crawler    aeo-crawler                 produces JSONL
11//! 4. Validator  aeo-validator-service       always-on validation + drift
12//! 5. Explorer   aeo-graph-explorer-rs       <- this repo
13//! ```
14//!
15//! ## What it does
16//!
17//! `aeo-crawler` BFS-walks an AEO graph from a seed URL and dumps one node
18//! per JSON line. That's a great pipeline output and a terrible query
19//! interface. This crate ingests the JSONL into a typed petgraph + an
20//! `axum` HTTP layer, so callers can ask:
21//!
22//! - `GET /nodes` — list every entity in the graph.
23//! - `GET /nodes/{id}` — fetch one entity's full AEO doc.
24//! - `GET /nodes/{id}/neighbors` — declared peers + reverse references.
25//! - `GET /shortest-path?from=X&to=Y` — does a citation chain connect them?
26//! - `GET /find-by-claim?predicate=...&value=...` — pull entities whose
27//!   claims match a predicate/value pair.
28//! - `POST /ingest` — load a JSONL document and rebuild the graph atomically.
29//!
30//! ## Design
31//!
32//! - Graph is `petgraph::Graph<AeoNode, EdgeKind>`; cheap to walk, cheap to
33//!   serialize. Edge kinds (`DeclaresPeer`, `CitesAuthority`) are typed so
34//!   future endpoints can answer "what authorities does X chain through?"
35//!   without re-walking.
36//! - The whole graph lives behind a `tokio::sync::RwLock` so an `/ingest`
37//!   atomically replaces it. Read paths take a snapshot and never block
38//!   each other.
39//! - No database. Crawls are small (thousands of nodes, not millions) and
40//!   the right tool for "give me a queryable view of a recent crawl" is an
41//!   in-memory graph.
42//!
43//! ## Composes with
44//!
45//! - **[aeo-crawler](https://github.com/mizcausevic-dev/aeo-crawler)** —
46//!   produces the JSONL this service ingests.
47//! - **[aeo-validator-service](https://github.com/mizcausevic-dev/aeo-validator-service)**
48//!   — call `POST /watches` for every node returned by `/nodes` to set up
49//!   drift tracking across the whole graph.
50//! - **[incident-correlation-rs](https://github.com/mizcausevic-dev/incident-correlation-rs)**
51//!   — when an incident lands, ask `/find-by-claim` for everyone declaring
52//!   the affected entity, then seed the correlator with the result.
53
54#![warn(missing_docs)]
55#![warn(rust_2018_idioms)]
56#![warn(clippy::pedantic)]
57#![allow(clippy::module_name_repetitions)]
58#![allow(clippy::missing_errors_doc)]
59#![allow(clippy::missing_panics_doc)]
60#![allow(clippy::must_use_candidate)]
61#![allow(clippy::doc_markdown)]
62
63pub mod app;
64pub mod error;
65pub mod graph;
66pub mod model;
67pub mod query;
68
69/// Optional audit-stream-py producer. Gated behind the `audit-stream`
70/// Cargo feature (on by default for the binary service).
71#[cfg(feature = "audit-stream")]
72pub mod audit_stream;
73
74pub use app::{build_router, AppState};
75pub use error::GraphError;
76pub use graph::{AeoGraph, EdgeKind};
77pub use model::{AeoClaim, AeoEntity, AeoNode};
78pub use query::{
79    find_by_claim, neighbors, shortest_path, ClaimMatch, NeighborView, PathHop, PathResult,
80};
aeo_graph_explorer/lib.rs

aeo_graph_explorer/
lib.rs
