Skip to main content

Architecture Overview

This page is the shortest route to the system-wide mental model. Read it first if you need to understand how the backend, query runtime, and frontend surfaces connect before diving into any single subsystem.

Backend​

  • HTTP API (runtime/server.jl): task lifecycle, snapshot query, node/source inspection, filesystem helpers.
  • Task Orchestrator (pipeline.jl): runs analysis asynchronously and persists task/snapshot state.
  • DepAtlasSource (da_source.jl): JuliaSyntax-first frontend that extracts syntax facts, lowers them into typed structure and call facts, and feeds the graph builder.
  • JET Views (jet.jl, runtime/jet_views.jl): optional compile-time analysis surfaces exposed through cached on-demand views from selected method nodes.
  • Graph Query (graph_query.jl): layer projection, filtering, pagination, reachability, and query-time node appearance semantics.
  • Store (core/store.jl): in-memory state plus JSON persistence under the platform-specific DependencyAtlas state directory.

Frontend​

  • React app with task controls, graph explorer, detail panes, and export actions
  • static docs frontend for architecture, guides, and examples

Runtime Surfaces

Runtime
HTTP API

Task lifecycle, query endpoints, source inspection, and frontend-facing payloads.

Backend
Analysis Pipeline

JuliaSyntax facts, lowering, graph construction, on-demand JET analysis, and snapshot creation.

Backend
Engine Integrations

How DepAtlasSource forms the default path, with JET available as an optional on-demand layer.

Runtime
Frontend and Store

How the web app, docs site, query runtime, and platform-specific persistence fit together.

Data Model​

  • Node(kind=file|module|method)
  • Edge(kind=include|import|define|call_inferred|call_possible|call_dynamic)
  • confidence(exact|inferred|possible|dynamic)
  • overload_style(none|safe|piracy_like) carried in metadata where relevant

Current Backend Flow

01

Syntax Facts

JuliaSyntax extracts raw source facts from project files.

02

Lowering

Ownership, body ranges, bindings, and calls are lowered into typed structure and call facts.

03

Base Graph

Typed structure facts build canonical file/module/method identity and define edges.

04

Evidence

Typed call facts define the base layer, while JET remains an optional on-demand layer.

05

Query

Projection, pagination, reachability, and node appearance are computed at query time.

Main Design Principle​

The backend does not treat parsing, ownership, and call extraction as one mixed pass. The stable seam is:

  • syntax facts
  • lowering to typed structure and call facts
  • graph construction and query/runtime behavior

That split is what makes the current architecture maintainable.

Why this matters

If you are changing parsing or ownership logic, you are working on the JuliaSyntax frontend side of the seam. If you are changing graph shape after snapshots exist, you are probably working on the query/runtime side instead.

Current State​

DepAtlasSource is the default fact source for the main graph. JET is available as a separate on-demand view. Query and reachability semantics live on the runtime side, where node_appearance explains why nodes are present in a result.