# giggsoinc/aryx architecture

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

- Interactive diagram: https://gitdiagram.com/giggsoinc/aryx
- Repository: https://github.com/giggsoinc/aryx

## Overview

Aryx builds a persistent, provenance-aware context graph from enterprise data and serves that context to applications and AI agents. The main user journey is to connect sources, review discovered structure, build and resolve the graph, then query it through Ask, REST, or MCP. The graph preserves README-documented stages and capabilities; source excerpts additionally show API-to-orchestrator and orchestrator-to-stage wiring. Several feature implementations were not sampled, so those relationships rely on README evidence rather than inspected implementation details.

Main entry points: [`src/aryx/pipeline/orchestrate.py`](https://github.com/giggsoinc/aryx/blob/main/src/aryx/pipeline/orchestrate.py) (Pipeline Orchestrator), [`src/aryx/store/postgres_store.py`](https://github.com/giggsoinc/aryx/blob/main/src/aryx/store/postgres_store.py) (Postgres System), [`src/aryx/api`](https://github.com/giggsoinc/aryx/tree/main/src/aryx/api) (Ingest APIs), [`src/aryx/discover.py`](https://github.com/giggsoinc/aryx/blob/main/src/aryx/discover.py) (Structure Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Connect and Ingest"]
  node_ingest_api["Ingest APIs"]
  node_connectors["Source Connectors"]
  node_dataset_ingest["Dataset Ingestion<br/>[ingest.py]"]
  node_orchestrator["Pipeline Orchestrator<br/>[orchestrate.py]"]
end

subgraph group_model["Discover and Resolve"]
  node_discovery["Structure Discovery<br/>[discover.py]"]
  node_ontology["Ontology Modeling"]
  node_resolution["Entity Resolution"]
  node_review["Human Review"]
end

subgraph group_graph["Graph and Governance"]
  node_postgres[("Postgres System<br/>[postgres_store.py]")]
  node_entity_store["Entity and Provenance Store<br/>[entity_store.py]"]
  node_graph_reads["Graph Retrieval<br/>[retrieve.py]"]
  node_graph_evolution["Graph Evolution<br/>[changes.py]"]
end

subgraph group_serve["Agent Interfaces"]
  node_ask["Grounded Ask<br/>[ask_api.py]"]
  node_rest["REST APIs"]
  node_mcp["MCP Tools"]
end

subgraph group_web["Web Experience"]
  node_web_ui["Web UI"]
  node_web_api["Web API Client<br/>[api.ts]"]
end

node_user(("Workspace User"))
node_sources[("Enterprise Sources")]
node_agent(("AI Agent"))

node_user -->|"starts workspace"| node_web_ui
node_web_ui -.->|"requests services"| node_web_api
node_sources -->|"provides data"| node_connectors
node_user -->|"submits sources"| node_ingest_api
node_ingest_api -->|"starts ingestion"| node_orchestrator
node_ingest_api -->|"registers datasets"| node_dataset_ingest
node_connectors -->|"supplies records"| node_discovery
node_orchestrator -->|"runs discovery"| node_discovery
node_orchestrator -->|"runs resolution"| node_resolution
node_discovery -->|"proposes structure"| node_ontology
node_resolution -->|"persists entities"| node_entity_store
node_user -->|"reviews matches"| node_review
node_review -->|"adjudicates identity"| node_resolution
node_orchestrator -->|"writes graph entities"| node_entity_store
node_entity_store -->|"persists records"| node_postgres
node_postgres -->|"serves live graph"| node_graph_reads
node_orchestrator -->|"projects changes"| node_graph_evolution
node_graph_reads -->|"grounds answers"| node_ask
node_postgres -->|"backs APIs"| node_rest
node_postgres -->|"supplies context"| node_mcp
node_ask -->|"returns cited answers"| node_agent
node_rest -->|"serves context"| node_agent
node_mcp -->|"exposes tools"| node_agent

click node_ingest_api "https://github.com/giggsoinc/aryx/tree/main/src/aryx/api"
click node_connectors "https://github.com/giggsoinc/aryx/tree/main/src/aryx/connectors"
click node_dataset_ingest "https://github.com/giggsoinc/aryx/blob/main/src/aryx/dataset/ingest.py"
click node_orchestrator "https://github.com/giggsoinc/aryx/blob/main/src/aryx/pipeline/orchestrate.py"
click node_discovery "https://github.com/giggsoinc/aryx/blob/main/src/aryx/discover.py"
click node_ontology "https://github.com/giggsoinc/aryx/tree/main/src/aryx/ontology"
click node_resolution "https://github.com/giggsoinc/aryx/tree/main/src/aryx/resolution"
click node_review "https://github.com/giggsoinc/aryx/blob/main/src/aryx/api/adjudication_api.py"
click node_postgres "https://github.com/giggsoinc/aryx/blob/main/src/aryx/store/postgres_store.py"
click node_entity_store "https://github.com/giggsoinc/aryx/blob/main/src/aryx/store/entity_store.py"
click node_graph_reads "https://github.com/giggsoinc/aryx/blob/main/src/aryx/graph/retrieve.py"
click node_graph_evolution "https://github.com/giggsoinc/aryx/blob/main/src/aryx/graph/changes.py"
click node_ask "https://github.com/giggsoinc/aryx/blob/main/src/aryx/api/ask_api.py"
click node_rest "https://github.com/giggsoinc/aryx/tree/main/src/aryx/api"
click node_mcp "https://github.com/giggsoinc/aryx/tree/main/src/aryx/mcp"
click node_web_ui "https://github.com/giggsoinc/aryx/tree/main/apps/web/app"
click node_web_api "https://github.com/giggsoinc/aryx/blob/main/apps/web/lib/api.ts"

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_ingest_api,node_connectors,node_dataset_ingest,node_orchestrator,node_user toneBlue
class node_discovery,node_ontology,node_resolution,node_review,node_sources toneAmber
class node_postgres,node_entity_store,node_graph_reads,node_graph_evolution toneMint
class node_ask,node_rest,node_mcp toneRose
class node_web_ui,node_web_api,node_agent toneIndigo
```

## Components

### Connect and Ingest

- [Ingest APIs](https://github.com/giggsoinc/aryx/tree/main/src/aryx/api): `src/aryx/api`
- [Source Connectors](https://github.com/giggsoinc/aryx/tree/main/src/aryx/connectors): `src/aryx/connectors`
- [Dataset Ingestion](https://github.com/giggsoinc/aryx/blob/main/src/aryx/dataset/ingest.py): `src/aryx/dataset/ingest.py`
- [Pipeline Orchestrator](https://github.com/giggsoinc/aryx/blob/main/src/aryx/pipeline/orchestrate.py): `src/aryx/pipeline/orchestrate.py`

### Discover and Resolve

- [Structure Discovery](https://github.com/giggsoinc/aryx/blob/main/src/aryx/discover.py): `src/aryx/discover.py`
- [Ontology Modeling](https://github.com/giggsoinc/aryx/tree/main/src/aryx/ontology): `src/aryx/ontology`
- [Entity Resolution](https://github.com/giggsoinc/aryx/tree/main/src/aryx/resolution): `src/aryx/resolution`
- [Human Review](https://github.com/giggsoinc/aryx/blob/main/src/aryx/api/adjudication_api.py): `src/aryx/api/adjudication_api.py`

### Graph and Governance

- [Postgres System](https://github.com/giggsoinc/aryx/blob/main/src/aryx/store/postgres_store.py): `src/aryx/store/postgres_store.py`
- [Entity and Provenance Store](https://github.com/giggsoinc/aryx/blob/main/src/aryx/store/entity_store.py): `src/aryx/store/entity_store.py`
- [Graph Retrieval](https://github.com/giggsoinc/aryx/blob/main/src/aryx/graph/retrieve.py): `src/aryx/graph/retrieve.py`
- [Graph Evolution](https://github.com/giggsoinc/aryx/blob/main/src/aryx/graph/changes.py): `src/aryx/graph/changes.py`

### Agent Interfaces

- [Grounded Ask](https://github.com/giggsoinc/aryx/blob/main/src/aryx/api/ask_api.py): `src/aryx/api/ask_api.py`
- [REST APIs](https://github.com/giggsoinc/aryx/tree/main/src/aryx/api): `src/aryx/api`
- [MCP Tools](https://github.com/giggsoinc/aryx/tree/main/src/aryx/mcp): `src/aryx/mcp`

### Web Experience

- [Web UI](https://github.com/giggsoinc/aryx/tree/main/apps/web/app): `apps/web/app`
- [Web API Client](https://github.com/giggsoinc/aryx/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### Other components

- **Workspace User**
- **Enterprise Sources**
- **AI Agent**

## Connections

- Workspace User → Web UI: starts workspace (evidence: `README.md`)
- Web UI → Web API Client: requests services
- Enterprise Sources → Source Connectors: provides data (evidence: `README.md`)
- Workspace User → Ingest APIs: submits sources (evidence: `README.md`)
- Ingest APIs → Pipeline Orchestrator: starts ingestion (evidence: `src/aryx/api/admin_api.py`)
- Ingest APIs → Dataset Ingestion: registers datasets (evidence: `src/aryx/api/file_ingest_api.py`)
- Source Connectors → Structure Discovery: supplies records (evidence: `src/aryx/pipeline/orchestrate.py`)
- Pipeline Orchestrator → Structure Discovery: runs discovery (evidence: `src/aryx/pipeline/orchestrate.py`)
- Pipeline Orchestrator → Entity Resolution: runs resolution (evidence: `src/aryx/pipeline/orchestrate.py`)
- Structure Discovery → Ontology Modeling: proposes structure (evidence: `README.md`)
- Entity Resolution → Entity and Provenance Store: persists entities (evidence: `src/aryx/store/entity_store.py`)
- Workspace User → Human Review: reviews matches (evidence: `README.md`)
- Human Review → Entity Resolution: adjudicates identity (evidence: `README.md`)
- Pipeline Orchestrator → Entity and Provenance Store: writes graph entities (evidence: `src/aryx/pipeline/orchestrate.py`)
- Entity and Provenance Store → Postgres System: persists records (evidence: `src/aryx/store/entity_store.py`)
- Postgres System → Graph Retrieval: serves live graph (evidence: `README.md`)
- Pipeline Orchestrator → Graph Evolution: projects changes (evidence: `src/aryx/pipeline/orchestrate.py`)
- Graph Retrieval → Grounded Ask: grounds answers (evidence: `README.md`)
- Postgres System → REST APIs: backs APIs (evidence: `README.md`)
- Postgres System → MCP Tools: supplies context (evidence: `README.md`)
- Grounded Ask → AI Agent: returns cited answers (evidence: `README.md`)
- REST APIs → AI Agent: serves context (evidence: `README.md`)
- MCP Tools → AI Agent: exposes tools (evidence: `README.md`)