# extorc/ecoint architecture

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

- Interactive diagram: https://gitdiagram.com/extorc/ecoint
- Repository: https://github.com/extorc/ecoint

## Overview

#### Purpose and entry point
This is a Python pipeline for turning RSS content into a Neo4j knowledge graph. The likely executable entry point is `main.py`, with workflow composition centralized in `graph.py`. Runtime configuration, including service credentials and model settings, is expected in `config.py` and `.env.template`.

#### Workflow orchestration
`graph.py` defines the pipeline/control graph and the ordering of processing stages. `main.py` should initialize configuration and invoke that graph. The `nodes/` package contains independently implemented workflow stages, indicating an explicit node-based orchestration design rather than a monolithic script.

Paths: `main.py`, `graph.py`, `nodes/__init__.py`

#### RSS ingestion boundary
The ingestion stage retrieves source material from RSS feeds. It is the boundary between external feed/network data and the internal processing pipeline, and likely normalizes feed entries into a document/article representation consumed by downstream nodes.

Path: `nodes/fetch_rss.py`

#### Knowledge extraction stage
Extracted RSS text is converted into structured knowledge—such as entities, relationships, claims, or topic metadata—by the knowledge-extraction node. This is the semantic transformation boundary and may call an external LLM or NLP provider according to settings in `config.py`.

Paths: `nodes/extract_knowledge.py`, `config.py`

#### Entity embedding stage
Entities produced during extraction are embedded into vector representations, enabling semantic similarity, deduplication, or vector-indexed retrieval. Embedding is distinct from extraction, so downstream persistence can store both graph structure and semantic vectors.

Path: `nodes/embed_entities.py`

#### Graph persistence
The final storage stage writes knowledge graph records to Neo4j. It is the infrastructure boundary for database connectivity, schema/label conventions, upsert behavior, and relationship persistence. Neo4j is the material external service implied by the repository structure.

Path: `nodes/store_neo4j.py`

#### Primary data flow
Control and data should move in this order: RSS feed retrieval → knowledge extraction → entity embedding → Neo4j storage. `graph.py` coordinates stage transitions; each file under `nodes/` owns one transformation or side-effect boundary. Configuration is supplied through environment-derived values rather than hardcoded infrastructure settings.

Paths: `graph.py`, `nodes/fetch_rss.py`, `nodes/extract_knowledge.py`, `nodes/embed_entities.py`, `nodes/store_neo4j.py`

Main entry points: [`nodes/extract_knowledge.py`](https://github.com/extorc/ecoint/blob/main/nodes/extract_knowledge.py) (Extract knowledge), [`config.py`](https://github.com/extorc/ecoint/blob/main/config.py) (Runtime config), [`graph.py`](https://github.com/extorc/ecoint/blob/main/graph.py) (Pipeline graph), [`nodes/fetch_rss.py`](https://github.com/extorc/ecoint/blob/main/nodes/fetch_rss.py) (Fetch RSS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow"]
  node_main["Main entry point<br/>Python entry point<br/>[main.py]"]
  node_workflow_graph["Pipeline graph<br/>Workflow orchestration<br/>[graph.py]"]
  node_node_package["Node package<br/>[__init__.py]"]
  node_config["Runtime config<br/>Configuration<br/>[config.py]"]
end

subgraph group_stages["Pipeline stages"]
  node_fetch_rss["Fetch RSS<br/>Ingestion node<br/>[fetch_rss.py]"]
  node_extract_knowledge["Extract knowledge<br/>Semantic extraction node"]
  node_embed_entities["Embed entities<br/>Embedding node<br/>[embed_entities.py]"]
  node_store_neo4j["Store in Neo4j<br/>Persistence node<br/>[store_neo4j.py]"]
end

subgraph group_external["External services"]
  node_rss_feeds["RSS feeds<br/>External content source"]
  node_llm_nlp{{"LLM / NLP provider<br/>External AI service"}}
  node_neo4j[("Neo4j<br/>Graph database")]
end

node_main -->|"loads"| node_config
node_main -->|"invokes"| node_workflow_graph
node_node_package -.->|"provides stages"| node_workflow_graph
node_workflow_graph -->|"starts"| node_fetch_rss
node_rss_feeds -->|"feed entries"| node_fetch_rss
node_fetch_rss -->|"normalized articles"| node_extract_knowledge
node_config -.->|"model settings"| node_extract_knowledge
node_extract_knowledge -->|"extracts via"| node_llm_nlp
node_extract_knowledge -->|"entities and relations"| node_embed_entities
node_embed_entities -->|"knowledge with vectors"| node_store_neo4j
node_config -.->|"database credentials"| node_store_neo4j
node_store_neo4j -->|"upserts"| node_neo4j

click node_main "https://github.com/extorc/ecoint/blob/main/main.py"
click node_workflow_graph "https://github.com/extorc/ecoint/blob/main/graph.py"
click node_node_package "https://github.com/extorc/ecoint/blob/main/nodes/__init__.py"
click node_config "https://github.com/extorc/ecoint/blob/main/config.py"
click node_fetch_rss "https://github.com/extorc/ecoint/blob/main/nodes/fetch_rss.py"
click node_extract_knowledge "https://github.com/extorc/ecoint/blob/main/nodes/extract_knowledge.py"
click node_embed_entities "https://github.com/extorc/ecoint/blob/main/nodes/embed_entities.py"
click node_store_neo4j "https://github.com/extorc/ecoint/blob/main/nodes/store_neo4j.py"

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_main,node_workflow_graph,node_node_package,node_config toneBlue
class node_fetch_rss,node_extract_knowledge,node_embed_entities,node_store_neo4j toneAmber
class node_rss_feeds,node_llm_nlp,node_neo4j toneMint
```

## Components

### Workflow

- [Main entry point](https://github.com/extorc/ecoint/blob/main/main.py): Python entry point · Initializes runtime and starts the pipeline. · `main.py`
- [Pipeline graph](https://github.com/extorc/ecoint/blob/main/graph.py): Workflow orchestration · Defines stage ordering and transitions. · `graph.py`
- [Node package](https://github.com/extorc/ecoint/blob/main/nodes/__init__.py): Workflow node package · `nodes/__init__.py`
- [Runtime config](https://github.com/extorc/ecoint/blob/main/config.py): Configuration · Provides environment-derived credentials and model settings. · `config.py`

### Pipeline stages

- [Fetch RSS](https://github.com/extorc/ecoint/blob/main/nodes/fetch_rss.py): Ingestion node · Retrieves and normalizes feed entries. · `nodes/fetch_rss.py`
- [Extract knowledge](https://github.com/extorc/ecoint/blob/main/nodes/extract_knowledge.py): Semantic extraction node · Converts article text into structured knowledge. · `nodes/extract_knowledge.py`
- [Embed entities](https://github.com/extorc/ecoint/blob/main/nodes/embed_entities.py): Embedding node · Creates semantic vectors for extracted entities. · `nodes/embed_entities.py`
- [Store in Neo4j](https://github.com/extorc/ecoint/blob/main/nodes/store_neo4j.py): Persistence node · Upserts graph records and entity vectors. · `nodes/store_neo4j.py`

### External services

- **RSS feeds**: External content source
- **LLM / NLP provider**: External AI service
- **Neo4j**: Graph database · Stores knowledge graph structure and vectors.

## Connections

- Main entry point → Runtime config: loads
- Main entry point → Pipeline graph: invokes
- Node package → Pipeline graph: provides stages
- Pipeline graph → Fetch RSS: starts
- RSS feeds → Fetch RSS: feed entries
- Fetch RSS → Extract knowledge: normalized articles
- Runtime config → Extract knowledge: model settings
- Extract knowledge → LLM / NLP provider: extracts via
- Extract knowledge → Embed entities: entities and relations
- Embed entities → Store in Neo4j: knowledge with vectors
- Runtime config → Store in Neo4j: database credentials
- Store in Neo4j → Neo4j: upserts