# materialczar50/semantica architecture

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

- Interactive diagram: https://gitdiagram.com/materialczar50/semantica
- Repository: https://github.com/materialczar50/semantica

## Overview

Semantica is graph-native knowledge and context infrastructure for AI systems. Its principal workflow takes enterprise data through ingestion and semantic extraction into queryable knowledge/context graphs, where ontology models, graph analytics, reasoning, and decision context support downstream applications. Provenance and audit trails make those results traceable. The Explorer provides a user-facing way to work with graphs and related capabilities; framework integrations expose Semantica to agent ecosystems. The README documents these capabilities, but sampled source is incomplete, so the graph avoids asserting detailed internal call paths.

Main entry points: [`semantica/kg/knowledge_graph.py`](https://github.com/materialczar50/semantica/blob/main/semantica/kg/knowledge_graph.py) (Knowledge Graph), [`semantica/context/context_graph.py`](https://github.com/materialczar50/semantica/blob/main/semantica/context/context_graph.py) (Context Graph), [`semantica/ingest`](https://github.com/materialczar50/semantica/tree/main/semantica/ingest) (Data Ingestion), [`semantica/parse`](https://github.com/materialczar50/semantica/tree/main/semantica/parse) (Document Parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data Preparation"]
  node_ingest["Data Ingestion"]
  node_parse["Document Parsing"]
  node_extract["Semantic Extraction"]
  node_normalize["Data Normalization"]
end

subgraph group_knowledge["Knowledge Modeling"]
  node_ontology["Ontology Management"]
  node_kg["Knowledge Graph<br/>[knowledge_graph.py]"]
  node_graphstore[("Graph Storage")]
  node_triplet[("RDF Storage")]
  node_analytics["Graph Analytics"]
end

subgraph group_context["Context and Decisions"]
  node_contextgraph["Context Graph<br/>[context_graph.py]"]
  node_memory[("Agent Memory<br/>[agent_memory.py]")]
  node_reasoning["Deterministic Reasoning<br/>[reasoner.py]"]
  node_decisions["Decision Intelligence"]
  node_vectors[("Vector Search")]
end

subgraph group_access["Access and Integrations"]
  node_explorer["Knowledge Explorer<br/>[app.py]"]
  node_explorerui["Explorer Workspaces<br/>[App.tsx]"]
  node_agents["Agent Integrations"]
  node_mcp["MCP Tools<br/>[server.py]"]
end

subgraph group_governance["Traceability"]
  node_provenance["Provenance Tracking<br/>[manager.py]"]
end

node_teams(("Data and AI Teams"))

node_teams -->|"supply data"| node_ingest
node_ingest -.->|"ingest sources"| node_parse
node_parse -.->|"extract meaning"| node_extract
node_extract -.->|"prepare entities"| node_normalize
node_normalize -->|"build graph"| node_kg
node_ontology -->|"model meaning"| node_kg
node_kg -->|"store graph"| node_graphstore
node_kg -->|"store RDF"| node_triplet
node_kg -->|"analyze graph"| node_analytics
node_kg -->|"build context"| node_contextgraph
node_contextgraph -.->|"inform agent context"| node_memory
node_contextgraph -->|"support reasoning"| node_reasoning
node_contextgraph -->|"inform decisions"| node_decisions
node_contextgraph -.->|"enable retrieval"| node_vectors
node_decisions -->|"record decision trail"| node_provenance
node_kg -->|"trace graph lineage"| node_provenance
node_teams -->|"explore knowledge"| node_explorerui
node_explorerui -.->|"access services"| node_explorer
node_agents -->|"use context"| node_contextgraph
node_mcp -.->|"expose graph tools"| node_contextgraph

click node_ingest "https://github.com/materialczar50/semantica/tree/main/semantica/ingest"
click node_parse "https://github.com/materialczar50/semantica/tree/main/semantica/parse"
click node_extract "https://github.com/materialczar50/semantica/tree/main/semantica/semantic_extract"
click node_normalize "https://github.com/materialczar50/semantica/tree/main/semantica/normalize"
click node_ontology "https://github.com/materialczar50/semantica/tree/main/semantica/ontology"
click node_kg "https://github.com/materialczar50/semantica/blob/main/semantica/kg/knowledge_graph.py"
click node_graphstore "https://github.com/materialczar50/semantica/tree/main/semantica/graph_store"
click node_triplet "https://github.com/materialczar50/semantica/tree/main/semantica/triplet_store"
click node_analytics "https://github.com/materialczar50/semantica/tree/main/semantica/kg"
click node_contextgraph "https://github.com/materialczar50/semantica/blob/main/semantica/context/context_graph.py"
click node_memory "https://github.com/materialczar50/semantica/blob/main/semantica/context/agent_memory.py"
click node_reasoning "https://github.com/materialczar50/semantica/blob/main/semantica/reasoning/reasoner.py"
click node_decisions "https://github.com/materialczar50/semantica/blob/main/semantica/context/decision_recorder.py"
click node_vectors "https://github.com/materialczar50/semantica/tree/main/semantica/vector_store"
click node_provenance "https://github.com/materialczar50/semantica/blob/main/semantica/provenance/manager.py"
click node_explorer "https://github.com/materialczar50/semantica/blob/main/semantica/explorer/app.py"
click node_explorerui "https://github.com/materialczar50/semantica/blob/main/explorer/src/App.tsx"
click node_agents "https://github.com/materialczar50/semantica/tree/main/integrations"
click node_mcp "https://github.com/materialczar50/semantica/blob/main/semantica_mcp/mcp/server.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_ingest,node_parse,node_extract,node_normalize toneBlue
class node_ontology,node_kg,node_graphstore,node_triplet,node_analytics toneAmber
class node_contextgraph,node_memory,node_reasoning,node_decisions,node_vectors toneMint
class node_explorer,node_explorerui,node_agents,node_mcp toneRose
class node_provenance,node_teams toneIndigo
```

## Components

### Data Preparation

- [Data Ingestion](https://github.com/materialczar50/semantica/tree/main/semantica/ingest): `semantica/ingest`
- [Document Parsing](https://github.com/materialczar50/semantica/tree/main/semantica/parse): `semantica/parse`
- [Semantic Extraction](https://github.com/materialczar50/semantica/tree/main/semantica/semantic_extract): `semantica/semantic_extract`
- [Data Normalization](https://github.com/materialczar50/semantica/tree/main/semantica/normalize): `semantica/normalize`

### Knowledge Modeling

- [Ontology Management](https://github.com/materialczar50/semantica/tree/main/semantica/ontology): `semantica/ontology`
- [Knowledge Graph](https://github.com/materialczar50/semantica/blob/main/semantica/kg/knowledge_graph.py): `semantica/kg/knowledge_graph.py`
- [Graph Storage](https://github.com/materialczar50/semantica/tree/main/semantica/graph_store): `semantica/graph_store`
- [RDF Storage](https://github.com/materialczar50/semantica/tree/main/semantica/triplet_store): `semantica/triplet_store`
- [Graph Analytics](https://github.com/materialczar50/semantica/tree/main/semantica/kg): `semantica/kg`

### Context and Decisions

- [Context Graph](https://github.com/materialczar50/semantica/blob/main/semantica/context/context_graph.py): `semantica/context/context_graph.py`
- [Agent Memory](https://github.com/materialczar50/semantica/blob/main/semantica/context/agent_memory.py): `semantica/context/agent_memory.py`
- [Deterministic Reasoning](https://github.com/materialczar50/semantica/blob/main/semantica/reasoning/reasoner.py): `semantica/reasoning/reasoner.py`
- [Decision Intelligence](https://github.com/materialczar50/semantica/blob/main/semantica/context/decision_recorder.py): `semantica/context/decision_recorder.py`
- [Vector Search](https://github.com/materialczar50/semantica/tree/main/semantica/vector_store): `semantica/vector_store`

### Access and Integrations

- [Knowledge Explorer](https://github.com/materialczar50/semantica/blob/main/semantica/explorer/app.py): `semantica/explorer/app.py`
- [Explorer Workspaces](https://github.com/materialczar50/semantica/blob/main/explorer/src/App.tsx): `explorer/src/App.tsx`
- [Agent Integrations](https://github.com/materialczar50/semantica/tree/main/integrations): `integrations`
- [MCP Tools](https://github.com/materialczar50/semantica/blob/main/semantica_mcp/mcp/server.py): `semantica_mcp/mcp/server.py`

### Traceability

- [Provenance Tracking](https://github.com/materialczar50/semantica/blob/main/semantica/provenance/manager.py): `semantica/provenance/manager.py`

### Other components

- **Data and AI Teams**

## Connections

- Data and AI Teams → Data Ingestion: supply data (evidence: `README.md`)
- Data Ingestion → Document Parsing: ingest sources
- Document Parsing → Semantic Extraction: extract meaning
- Semantic Extraction → Data Normalization: prepare entities
- Data Normalization → Knowledge Graph: build graph (evidence: `README.md`)
- Ontology Management → Knowledge Graph: model meaning (evidence: `README.md`)
- Knowledge Graph → Graph Storage: store graph (evidence: `README.md`)
- Knowledge Graph → RDF Storage: store RDF (evidence: `README.md`)
- Knowledge Graph → Graph Analytics: analyze graph (evidence: `README.md`)
- Knowledge Graph → Context Graph: build context (evidence: `README.md`)
- Context Graph → Agent Memory: inform agent context
- Context Graph → Deterministic Reasoning: support reasoning (evidence: `README.md`)
- Context Graph → Decision Intelligence: inform decisions (evidence: `README.md`)
- Context Graph → Vector Search: enable retrieval
- Decision Intelligence → Provenance Tracking: record decision trail (evidence: `README.md`)
- Knowledge Graph → Provenance Tracking: trace graph lineage (evidence: `README.md`)
- Data and AI Teams → Explorer Workspaces: explore knowledge (evidence: `README.md`)
- Explorer Workspaces → Knowledge Explorer: access services
- Agent Integrations → Context Graph: use context (evidence: `README.md`)
- MCP Tools → Context Graph: expose graph tools