utopia - Moses Yebei

The Problem Enterprises that need a trustworthy, auditable knowledge base struggle with static graph stores that lose the when of a fact. When policies change or data is corrected, there is no built‑in history, making compliance reviews and “what‑if” simulations costly and error‑prone.

What This Does Utopia implements a bitemporal knowledge graph where every assertion is versioned in time and governed by an immutable ontology. Core logic lives in the Rust crates under crates/:

utopia-core (crates/utopia-core/src/lib.rs) defines shared models, error handling and configuration.
utopia-store (crates/utopia-store/src/) provides the persistence layer (PostgreSQL via db.rs) and enforces ontology constraints.
utopia-reason (crates/utopia-reason/src/lib.rs) houses the reasoning engine that evaluates axioms and resolves conflicts.
utopia-server (crates/utopia-server/src/main.rs) boots an Actix‑Web HTTP API and ties the store, reasoner, and ingestion pipelines together.

A lightweight React front‑end in web/ (built with pnpm) offers UI for ontology editing, alert monitoring and query exploration.

How It Is Wired

Startup – cargo run --bin utopia-server (or the Docker image) executes crates/utopia-server/src/main.rs.
Configuration – main.rs loads dotenv::from_path(".env.example") and builds a Config (from crates/utopia-core/src/config.rs).
Web server – Actix registers routes from src/api/*.rs (e.g., admin_routes.rs, graph_routes.rs). Each route handler receives an AppState that contains a Store (from utopia-store::db::Pool) and a Reasoner (from utopia-reason).
Request flow – A request to /api/graph calls graph_routes::get_graph, which invokes utopia-store::graph::Graph::load to fetch the current snapshot, then passes the data to utopia-reason::engine::evaluate for temporal reasoning. Results are serialized to JSON and returned.
Ingestion – utopia-ingest provides parsers (parsers.rs, ontology_rdf.rs) and a chunker (chunker.rs). The server’s /api/ingest endpoint streams RDF/Turtle files into utopia-ingest::run, which writes new facts via utopia-store::extraction_drops::store_extraction.
Reasoning loop – After each ingestion, utopia-reason::derive::apply_axioms runs across the new data, updating derived facts and emitting alerts (utopia-server/src/alerting.rs).
Persistence – All writes go through utopia-store::db::execute which runs the migration scripts in migrations/ (e.g., 0001_core.sql, 0015_what_it_did_not_just_what_it_said.sql).

The most “blast‑radius” component is utopia-server/src/main.rs because it wires every crate together; changes to the AppState or route registration ripple through the whole API surface.

How To Use It

# 1. Clone (preserves the exact URL the client asked for)
git clone https://github.com/moses-y/utopia.git
cd utopia

# 2. Build the Rust workspace
cargo build --workspace          # builds all crates, including server

# 3. Optional: run the UI
pnpm install                     # installs React deps in ./web
pnpm --filter web build          # produces static assets (served by server)

# 4. Prepare the database (PostgreSQL required)
docker compose -f docker-compose.yml up -d db   # starts a DB container
# apply migrations (run once)
cargo run -p utopia-server -- migrate

# 5. Start the service (local dev)
cargo run -p utopia-server
# or via Docker (image built from docker/Dockerfile)
docker compose up --build

Configuration lives in .env.example; copy it to .env and adjust DATABASE_URL, HOST, PORT as needed before step 4.

Real‑World Use A compliance team can ingest quarterly policy documents (RDF/Turtle) via POST /api/ingest. The system timestamps each fact, runs the reasoning engine to detect conflicts, and stores an immutable audit trail. When auditors request “why was decision X made on 2023‑07‑15?”, the API can reconstruct the exact ontology state at that timestamp and present the chain of derived facts that led to the decision.

Code Health & Issues

Low – No CI failures detected; GitHub Actions workflow ci.yml runs cargo test --workspace and pnpm lint.
Low – License file present (LICENSE Apache‑2.0).
Low – Test coverage moderate: 21 test files across core and store crates.
Low – Secrets not committed (environment variables loaded from .env.example).
Low – Documentation present (docs/, README.md, README.zh-CN.md).

Static analysis found no structural red flags; the repository includes lockfiles (Cargo.lock), CI scripts, and a LICENSE, satisfying baseline SDLC hygiene.

The Bottom Line Utopia delivers a Rust‑centric, bitemporal knowledge platform with a clear separation between core models, storage, reasoning and HTTP API. It is well‑structured, container‑ready, and includes a modest test suite. The codebase is suitable for teams that need an auditable, time‑aware ontology engine and are comfortable with Rust and Docker; it may be overkill for simple graph use‑cases.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

249 files

Rust108
TSX30
Markdown27
SQL18
TypeScript13
JSON12

ReactDocker

Module dependencies

The 10 most depended-upon modules of 50, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_web_src_i18n_index["index"] n1_web_src_api["api"] n2_web_src_ui_index["index"] n3_web_src_kb["kb"] n4_web_src_toast["toast"] n5_web_src_useTitle["useTitle"] n6_web_src_pages_UserMenu["UserMenu"] n7_web_src_pages_ServerDown["ServerDown"] n8_web_src_ui_popoverFlip["popoverFlip"] n9_web_src_pages_SourcesRail["SourcesRail"] n1_web_src_api --> n0_web_src_i18n_index n3_web_src_kb --> n1_web_src_api n7_web_src_pages_ServerDown --> n0_web_src_i18n_index n7_web_src_pages_ServerDown --> n2_web_src_ui_index n7_web_src_pages_ServerDown --> n5_web_src_useTitle n9_web_src_pages_SourcesRail --> n1_web_src_api n9_web_src_pages_SourcesRail --> n0_web_src_i18n_index n9_web_src_pages_SourcesRail --> n2_web_src_ui_index n6_web_src_pages_UserMenu --> n1_web_src_api n6_web_src_pages_UserMenu --> n8_web_src_ui_popoverFlip n6_web_src_pages_UserMenu --> n0_web_src_i18n_index n2_web_src_ui_index --> n0_web_src_i18n_index

Dependencies

60 declared dependencies, none a major version behind. Resolved 0 of 60 against the registry.

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, Swatinem/rust-cache@v2, pnpm/action-setup@v4, docker/setup-buildx-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh13 occurrences

tokio@1 CVE-2021-45710 (high) +7 more; futures-util@0.3 CVE-2020-35908 (medium) +1 more; sqlx@0.8 GHSA-xmrp-424f-vfpx (medium) +1 more; jsonwebtoken@10 CVE-2026-25537 (medium)

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/star-history.yml

git push

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Enable Dependabot or Renovatemedium

10 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium3 occurrences

docker/Dockerfile

node:20-slim, rust:1-slim-bookworm, debian:bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

docker/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.