# riznykst/fen-triadic-synthesis architecture

> Architecture diagram of the GitHub repository riznykst/fen-triadic-synthesis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/riznykst/fen-triadic-synthesis
- Repository: https://github.com/riznykst/fen-triadic-synthesis

## Overview

FEN is a federated validation node for community-governed linguistic knowledge. Its principal workflow receives extracted entity candidates, forwards them for community governance, records the resulting decision as RDF provenance, and exposes that record through status and export APIs. A separate scaffold stage assists contributors with structuring knowledge; quadratic voting and delegation support community judgment. The graph preserves documented Kafka, ontology, PID, and web-interface capabilities. Some subsystem links rely on README descriptions because their implementation was not excerpted; those limits are reflected in the evidence paths.

Main entry points: [`services/validation_consumer/main.py`](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/main.py) (Validation Consumer), [`services/validation_consumer/sparql_updater.py`](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/sparql_updater.py) (SPARQL Updater), [`mock_fen_api/main.py`](https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/main.py) (Mock FEN API), [`services/fen_bridge/webhook.py`](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/webhook.py) (Decision Webhook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contribution["Contribution &amp; Scaffold"]
  node_scaffold["Agentic Scaffold<br/>[scaffold.py]"]
  node_llm["LLM Provider<br/>[llm.py]"]
  node_ontology["FEN Ontology<br/>[gfen_ontology.py]"]
end

subgraph group_governance["Community Governance"]
  node_mock_api["Mock FEN API<br/>[main.py]"]
  node_qv["Quadratic Voting<br/>[qv_voting.py]"]
  node_delegation["Vote Delegation<br/>[delegation.py]"]
end

subgraph group_federation["Federation Pipeline"]
  node_fen_client["FEN Client<br/>[fen_client.py]"]
  node_outbound["Candidate Bridge<br/>[outbound.py]"]
  node_webhook["Decision Webhook<br/>[webhook.py]"]
  node_contracts["Event Contracts<br/>[messages.py]"]
  node_consumer["Validation Consumer<br/>[main.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_kafka_io["Kafka I/O<br/>[kafka_io.py]"]
end

subgraph group_records["Registry &amp; Status"]
  node_updater["SPARQL Updater<br/>[sparql_updater.py]"]
  node_graph_uris["Graph URI Scheme<br/>[graph_uris.py]"]
  node_pid["PID Scheme<br/>[pid.py]"]
  node_rdf_store[("RDF Store")]
  node_status_api["Status &amp; Export API<br/>[main.py]"]
  node_web_ui["Portal &amp; Widget"]
end

node_contributor(("Contributor"))
node_extractor["Entity Extractor"]
node_fen_system["FEN Governance"]
node_kafka["Kafka"]

node_contributor -->|"requests structuring"| node_scaffold
node_scaffold -->|"requests completion"| node_llm
node_scaffold -->|"uses vocabulary"| node_ontology
node_contributor -->|"submits candidates"| node_mock_api
node_mock_api -->|"supports voting"| node_qv
node_mock_api -->|"supports delegation"| node_delegation
node_mock_api -.->|"stands in for"| node_fen_system
node_extractor -->|"emits candidates"| node_outbound
node_outbound -->|"forwards batches"| node_fen_client
node_fen_client -->|"posts candidates"| node_fen_system
node_fen_system -->|"sends decisions"| node_webhook
node_webhook -->|"publishes decisions"| node_kafka_io
node_kafka_io -.->|"writes messages"| node_kafka
node_webhook -->|"validates decision"| node_contracts
node_consumer -->|"consumes decisions"| node_kafka_io
node_consumer -->|"validates payload"| node_contracts
node_consumer -->|"builds update"| node_updater
node_consumer -->|"publishes confirmation"| node_kafka_io
node_updater -->|"uses predicates"| node_ontology
node_updater -->|"resolves annotation"| node_graph_uris
node_updater -->|"creates record PIDs"| node_pid
node_updater -->|"updates provenance"| node_rdf_store
node_status_api -->|"queries provenance"| node_rdf_store
node_web_ui -->|"displays status"| node_status_api
node_webhook -->|"records metrics"| node_metrics
node_consumer -.->|"records metrics"| node_metrics

click node_scaffold "https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/scaffold.py"
click node_llm "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/llm.py"
click node_ontology "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/gfen_ontology.py"
click node_mock_api "https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/main.py"
click node_qv "https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/qv_voting.py"
click node_delegation "https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/delegation.py"
click node_fen_client "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/fen_client.py"
click node_outbound "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/outbound.py"
click node_webhook "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/webhook.py"
click node_contracts "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/messages.py"
click node_consumer "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/main.py"
click node_updater "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/sparql_updater.py"
click node_graph_uris "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/graph_uris.py"
click node_pid "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/pid.py"
click node_status_api "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/status_api/main.py"
click node_web_ui "https://github.com/riznykst/fen-triadic-synthesis/tree/main/web"
click node_metrics "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/metrics.py"
click node_kafka_io "https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/kafka_io.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_scaffold,node_llm,node_ontology toneBlue
class node_mock_api,node_qv,node_delegation toneAmber
class node_fen_client,node_outbound,node_webhook,node_contracts,node_consumer,node_metrics,node_kafka_io toneMint
class node_updater,node_graph_uris,node_pid,node_rdf_store,node_status_api,node_web_ui toneRose
class node_contributor,node_extractor,node_fen_system,node_kafka toneIndigo
```

## Components

### Contribution & Scaffold

- [Agentic Scaffold](https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/scaffold.py): `mock_fen_api/scaffold.py`
- [LLM Provider](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/llm.py): `services/common/llm.py`
- [FEN Ontology](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/gfen_ontology.py): `services/common/gfen_ontology.py`

### Community Governance

- [Mock FEN API](https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/main.py): `mock_fen_api/main.py`
- [Quadratic Voting](https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/qv_voting.py): `mock_fen_api/qv_voting.py`
- [Vote Delegation](https://github.com/riznykst/fen-triadic-synthesis/blob/main/mock_fen_api/delegation.py): `mock_fen_api/delegation.py`

### Federation Pipeline

- [FEN Client](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/fen_client.py): `services/fen_bridge/fen_client.py`
- [Candidate Bridge](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/outbound.py): `services/fen_bridge/outbound.py`
- [Decision Webhook](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/fen_bridge/webhook.py): `services/fen_bridge/webhook.py`
- [Event Contracts](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/messages.py): `services/common/messages.py`
- [Validation Consumer](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/main.py): `services/validation_consumer/main.py`
- [Metrics](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/metrics.py): `services/common/metrics.py`
- [Kafka I/O](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/kafka_io.py): `services/common/kafka_io.py`

### Registry & Status

- [SPARQL Updater](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/validation_consumer/sparql_updater.py): `services/validation_consumer/sparql_updater.py`
- [Graph URI Scheme](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/graph_uris.py): `services/common/graph_uris.py`
- [PID Scheme](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/common/pid.py): `services/common/pid.py`
- **RDF Store**
- [Status & Export API](https://github.com/riznykst/fen-triadic-synthesis/blob/main/services/status_api/main.py): `services/status_api/main.py`
- [Portal & Widget](https://github.com/riznykst/fen-triadic-synthesis/tree/main/web): `web`

### Other components

- **Contributor**
- **Entity Extractor**
- **FEN Governance**
- **Kafka**

## Connections

- Contributor → Agentic Scaffold: requests structuring
- Agentic Scaffold → LLM Provider: requests completion (evidence: `mock_fen_api/scaffold.py`)
- Agentic Scaffold → FEN Ontology: uses vocabulary (evidence: `mock_fen_api/scaffold.py`)
- Contributor → Mock FEN API: submits candidates
- Mock FEN API → Quadratic Voting: supports voting (evidence: `mock_fen_api/main.py`)
- Mock FEN API → Vote Delegation: supports delegation (evidence: `mock_fen_api/main.py`)
- Mock FEN API → FEN Governance: stands in for (evidence: `mock_fen_api/main.py`)
- Entity Extractor → Candidate Bridge: emits candidates
- Candidate Bridge → FEN Client: forwards batches (evidence: `services/fen_bridge/outbound.py`)
- FEN Client → FEN Governance: posts candidates (evidence: `services/fen_bridge/fen_client.py`)
- FEN Governance → Decision Webhook: sends decisions
- Decision Webhook → Kafka I/O: publishes decisions (evidence: `services/fen_bridge/webhook.py`)
- Kafka I/O → Kafka: writes messages
- Decision Webhook → Event Contracts: validates decision (evidence: `services/fen_bridge/webhook.py`)
- Validation Consumer → Kafka I/O: consumes decisions (evidence: `services/validation_consumer/main.py`)
- Validation Consumer → Event Contracts: validates payload (evidence: `services/validation_consumer/main.py`)
- Validation Consumer → SPARQL Updater: builds update (evidence: `services/validation_consumer/main.py`)
- Validation Consumer → Kafka I/O: publishes confirmation (evidence: `services/validation_consumer/main.py`)
- SPARQL Updater → FEN Ontology: uses predicates (evidence: `services/validation_consumer/sparql_updater.py`)
- SPARQL Updater → Graph URI Scheme: resolves annotation (evidence: `services/validation_consumer/sparql_updater.py`)
- SPARQL Updater → PID Scheme: creates record PIDs (evidence: `services/validation_consumer/sparql_updater.py`)
- SPARQL Updater → RDF Store: updates provenance (evidence: `services/validation_consumer/sparql_updater.py`)
- Status & Export API → RDF Store: queries provenance (evidence: `services/status_api/main.py`)
- Portal & Widget → Status & Export API: displays status
- Decision Webhook → Metrics: records metrics (evidence: `services/fen_bridge/webhook.py`)
- Validation Consumer → Metrics: records metrics (evidence: `services/validation_consumer/main.py`)
