# alkhrzmy/si-foren architecture

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

- Interactive diagram: https://gitdiagram.com/alkhrzmy/si-foren
- Repository: https://github.com/alkhrzmy/si-foren

## Overview

SI-FOREN is a procurement-market intelligence application for investigating vendors and presenting tender conversion, bidding-price, incumbent, co-bidding, and strategic-advisory results. A user submits a query through the Gradio app; the supervisor coordinates validation and deterministic SQL/graph analysis, assembles a dossier, and the app renders the results. The README documents broader dashboard capabilities; sampled excerpts confirm the analysis tools and some rendering paths, but not every UI or advisory call detail, so uncertain wiring is omitted.

Main entry points: [`src/agents/supervisor.py`](https://github.com/alkhrzmy/si-foren/blob/main/src/agents/supervisor.py) (Investigation Supervisor), [`app.py`](https://github.com/alkhrzmy/si-foren/blob/main/app.py) (Gradio Dashboard), [`src/tools/sql_duckdb.py`](https://github.com/alkhrzmy/si-foren/blob/main/src/tools/sql_duckdb.py) (DuckDB Analytics), [`src/llm_client.py`](https://github.com/alkhrzmy/si-foren/blob/main/src/llm_client.py) (LLM Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_app["Gradio Dashboard<br/>[app.py]"]
end

subgraph group_orchestration["Investigation Orchestration"]
  node_supervisor["Investigation Supervisor<br/>[supervisor.py]"]
  node_gatekeeper["Query Gatekeeper<br/>[llm_gatekeeper.py]"]
  node_state["Investigation Dossier<br/>[state.py]"]
end

subgraph group_analytics["Procurement Analytics"]
  node_sql["DuckDB Analytics<br/>[sql_duckdb.py]"]
  node_graph["Co-Bidding Network<br/>[graph_network.py]"]
end

subgraph group_advisory["Strategic Advisory"]
  node_llm["LLM Client<br/>[llm_client.py]"]
  node_hf["Hugging Face Inference"]
  node_proxy["Local LLM Proxy"]
end

subgraph group_data["Local Data"]
  node_paket[("Tender Packages<br/>[paket.parquet]")]
  node_peserta[("Tender Participants<br/>[peserta.parquet]")]
  node_pemenang[("Tender Winners<br/>[pemenang.parquet]")]
  node_gexf[("Co-Bid Graph Data")]
end

node_user(("Analyst"))

node_user -->|"submits query"| node_app
node_app -->|"starts investigation"| node_supervisor
node_supervisor -->|"validates query"| node_gatekeeper
node_gatekeeper -->|"classifies intent"| node_llm
node_llm -->|"requests inference"| node_hf
node_llm -.->|"fallback inference"| node_proxy
node_supervisor -->|"queries vendor data"| node_sql
node_supervisor -->|"retrieves partners"| node_graph
node_sql -->|"reads"| node_paket
node_sql -->|"reads"| node_peserta
node_sql -->|"reads"| node_pemenang
node_graph -->|"loads graph"| node_gexf
node_supervisor -->|"requests advisory"| node_llm
node_supervisor -->|"assembles dossier"| node_state
node_supervisor -->|"returns dossier"| node_app
node_app -->|"queries partner links"| node_sql
node_app -->|"renders network"| node_graph
node_app -->|"displays analysis"| node_user

click node_app "https://github.com/alkhrzmy/si-foren/blob/main/app.py"
click node_supervisor "https://github.com/alkhrzmy/si-foren/blob/main/src/agents/supervisor.py"
click node_gatekeeper "https://github.com/alkhrzmy/si-foren/blob/main/src/guardrails/llm_gatekeeper.py"
click node_state "https://github.com/alkhrzmy/si-foren/blob/main/src/state.py"
click node_sql "https://github.com/alkhrzmy/si-foren/blob/main/src/tools/sql_duckdb.py"
click node_graph "https://github.com/alkhrzmy/si-foren/blob/main/src/tools/graph_network.py"
click node_llm "https://github.com/alkhrzmy/si-foren/blob/main/src/llm_client.py"
click node_paket "https://github.com/alkhrzmy/si-foren/blob/main/data/paket.parquet"
click node_peserta "https://github.com/alkhrzmy/si-foren/blob/main/data/peserta.parquet"
click node_pemenang "https://github.com/alkhrzmy/si-foren/blob/main/data/pemenang.parquet"
click node_gexf "https://github.com/alkhrzmy/si-foren/blob/main/data/vendor_cobid_graph.gexf"

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_app toneBlue
class node_supervisor,node_gatekeeper,node_state toneAmber
class node_sql,node_graph toneMint
class node_llm,node_hf,node_proxy toneRose
class node_paket,node_peserta,node_pemenang,node_gexf,node_user toneIndigo
```

## Components

### User Interface

- [Gradio Dashboard](https://github.com/alkhrzmy/si-foren/blob/main/app.py): `app.py`

### Investigation Orchestration

- [Investigation Supervisor](https://github.com/alkhrzmy/si-foren/blob/main/src/agents/supervisor.py): `src/agents/supervisor.py`
- [Query Gatekeeper](https://github.com/alkhrzmy/si-foren/blob/main/src/guardrails/llm_gatekeeper.py): `src/guardrails/llm_gatekeeper.py`
- [Investigation Dossier](https://github.com/alkhrzmy/si-foren/blob/main/src/state.py): `src/state.py`

### Procurement Analytics

- [DuckDB Analytics](https://github.com/alkhrzmy/si-foren/blob/main/src/tools/sql_duckdb.py): `src/tools/sql_duckdb.py`
- [Co-Bidding Network](https://github.com/alkhrzmy/si-foren/blob/main/src/tools/graph_network.py): `src/tools/graph_network.py`

### Strategic Advisory

- [LLM Client](https://github.com/alkhrzmy/si-foren/blob/main/src/llm_client.py): `src/llm_client.py`
- **Hugging Face Inference**
- **Local LLM Proxy**

### Local Data

- [Tender Packages](https://github.com/alkhrzmy/si-foren/blob/main/data/paket.parquet): `data/paket.parquet`
- [Tender Participants](https://github.com/alkhrzmy/si-foren/blob/main/data/peserta.parquet): `data/peserta.parquet`
- [Tender Winners](https://github.com/alkhrzmy/si-foren/blob/main/data/pemenang.parquet): `data/pemenang.parquet`
- [Co-Bid Graph Data](https://github.com/alkhrzmy/si-foren/blob/main/data/vendor_cobid_graph.gexf): `data/vendor_cobid_graph.gexf`

### Other components

- **Analyst**

## Connections

- Analyst → Gradio Dashboard: submits query
- Gradio Dashboard → Investigation Supervisor: starts investigation
- Investigation Supervisor → Query Gatekeeper: validates query
- Query Gatekeeper → LLM Client: classifies intent
- LLM Client → Hugging Face Inference: requests inference
- LLM Client → Local LLM Proxy: fallback inference
- Investigation Supervisor → DuckDB Analytics: queries vendor data
- Investigation Supervisor → Co-Bidding Network: retrieves partners
- DuckDB Analytics → Tender Packages: reads
- DuckDB Analytics → Tender Participants: reads
- DuckDB Analytics → Tender Winners: reads
- Co-Bidding Network → Co-Bid Graph Data: loads graph
- Investigation Supervisor → LLM Client: requests advisory
- Investigation Supervisor → Investigation Dossier: assembles dossier
- Investigation Supervisor → Gradio Dashboard: returns dossier
- Gradio Dashboard → DuckDB Analytics: queries partner links
- Gradio Dashboard → Co-Bidding Network: renders network
- Gradio Dashboard → Analyst: displays analysis