# dfirvault/forensiq architecture

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

- Interactive diagram: https://gitdiagram.com/dfirvault/forensiq
- Repository: https://github.com/dfirvault/forensiq

## Overview

##### What this project is (type + purpose)
**ForensIQ** is a **Windows-only, Python/Streamlit-based DFIR log analysis application** that uses an **external LLM service (Ollama)** plus a **local vector store (ChromaDB) / embeddings stack (sentence-transformers / HuggingFace)** to accelerate and structure forensic investigations.

From the README + deps list, it’s best understood as a **single-process “desktop web app”**:
- **UI:** Streamlit web UI running locally on the analyst’s workstation
- **Core:** Python analysis pipeline (parsing, chunking, retrieval, prompting, summarization)
- **External service:** Ollama (local or remote) hosting the LLM model (e.g., `qwen-long`)
- **Storage:** local files for uploads + output artifacts; likely a local Chroma persistence dir for embeddings

##### What the file tree tells you about the architecture
Top-level:
- `ForensIQ.py` — effectively **the entire application** (UI + orchestration + pipeline) in one file.
- `ForensIQLauncher.bat` — Windows launcher wrapper (starts Streamlit).
- `ModelFile` — Ollama model definition used to create an optimized model (`ollama create qwen-long -f Modelfile`).
- `test.csv`, `test_evtx_data.csv` — sample data / fixtures.
- `LICENSE`, `README.md` — standard.

##### README-derived components & tech stack to capture
Explicit dependencies imply key sub-systems:
- **Streamlit**: UI, file uploader, user inputs (Ollama IP/model selection), results rendering
- **pandas**: CSV/tabular ingestion + transformations
- **python-evtx**: EVTX log parsing (Windows Event Logs)
- **langchain / langchain-community / langchain-ollama / langchain-huggingface**: prompt orchestration + connectors (Ollama LLM, HF embeddings)
- **sentence-transformers**: embedding model runtime
- **chromadb**: vector DB for retrieval (RAG), likely local persistent store

Runtime topology:
- Analyst runs Streamlit on Windows
- App reads user-provided files/folders
- App parses logs into structured records
- App chunks / embeds and stores in Chroma
- App retrieves relevant chunks and sends prompts to Ollama LLM
- App generates outputs: JSON/CSV + logs

##### Windows Workstation
- **Streamlit UI (ForensIQ.py)**
- **Core Orchestrator / Controller (inside ForensIQ.py)**
##### Ingestion Layer
- File uploader / folder scanner
- File type detection & queueing (CSV, EVTX, “other logs”)
##### Parsing & Normalization Layer
- EVTX parser (`python-evtx`)
- CSV parser (`pandas`)
- Normalizer (schema alignment, timestamps, fields)
##### Indexing / RAG Prep
- Chunking / document builder
- Embeddings generator (SentenceTransformers / HF)
##### Vector Store
- **ChromaDB (local)**
##### LLM Service
- **Ollama server (local or remote host)**
- Model: `qwen-long` created from `ModelFile`
##### Analysis / Reasoning
- LangChain prompt templates + chains
- Retrieval step: Chroma → context
- LLM inference: context + question → findings
##### Outputs
- JSON reports
- CSV summaries
- App logs / audit trail
- (Optional) local output directory

Also include:

**User → Streamlit UI**
- “Upload logs / select folder, set Ollama IP/model, start analysis”

**Streamlit UI → Ingestion**
- “File(s) / folder path”

**Ingestion → Parsing**
- “Raw file bytes / paths”

**Parsing → Normalization**
- “Structured events/rows”

**Normalization → Chunking/Docs**
- “Documents / event batches”

**Chunking → Embeddings**
- “Text chunks”

**Embeddings → ChromaDB**
- “Vectors + metadata (host, user, event id, timestamp…)”

**Streamlit UI (query/action) → Retrieval (ChromaDB)**
- “Search query / investigation task”

**ChromaDB → LangChain Orchestrator**
- “Top-k relevant chunks”

**LangChain Orchestrator → Ollama LLM**
- “Prompt with retrieved context”

**Ollama LLM → LangChain Orchestrator**
- “Findings / narrative / structured response”

**Orchestrator → Outputs**
- “JSON/CSV report + logs”

Additionally show the **network boundary**:
- If Ollama is remote: UI/Orchestrator → (HTTP) → Ollama Host
- If local: same-machine call

- Streamlit (UI)
- pandas (CSV)
- python-evtx (EVTX)
- LangChain (orchestration)
- sentence-transformers / HuggingFace embeddings
- ChromaDB
- Ollama + `qwen-long` model (from `ModelFile`)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: Deployment / Runtime Context (top)
%% =========================
subgraph D1["Deployment / Runtime Context"]
direction TB

U["DFIR Analyst (User)"]:::external

subgraph WS["Windows Analyst Workstation"]
direction TB

LCH["ForensIQLauncher.bat\n(Windows launcher)"]:::launcher
APP["ForensIQ Streamlit App\n(UI + Orchestrator)\n(implemented in ForensIQ.py)"]:::ui
FS[("Local Filesystem\nUploads + Outputs")]:::storage
CH[("ChromaDB\n(Local persistent vector store)")]:::storage

subgraph CFG["Runtime Configuration"]
direction TB
ENV["Env/Settings\nOLLAMA_MAX_CONTEXT\nOLLAMA_MAX_TOKENS\nGPU layers\nOllama IP + Model selection"]:::config
end

LCH -->|"starts"| APP
U -->|"upload_logs / set_params / run_analysis"| APP
APP -->|"read/write files"| FS
APP -->|"persist/load vectors"| CH
ENV -->|"controls inference + RAG settings"| APP
end

subgraph OH["Ollama Host (local or remote)"]
direction TB
OL["Ollama Service\n(LLM inference API)"]:::externalSvc
QM["Model: qwen-long"]:::model
MF["Modelfile\n(Model definition artifact)"]:::artifact
MF -->|"ollama create qwen-long -f Modelfile"| QM
QM -->|"served_by"| OL
end

APP -->|"HTTP (Ollama API)\nprompt + context"| OL
OL -->|"HTTP response\nfindings / structured text"| APP

NOTE1["Note: Implementation is consolidated in ForensIQ.py;\nmodules shown below are logical responsibilities."]:::note
end

%% =========================
%% Diagram 2: Internal Dataflow / RAG Pipeline (bottom)
%% =========================
subgraph D2["Internal Dataflow (Pipeline)"]
direction TB

INP["Input Logs\nEVTX / CSV / other logs\n(files or folders)"]:::doc

subgraph APPMOD["Logical Modules (within ForensIQ.py)"]
direction TB

UI["Streamlit UI\n(file uploader, controls, results)"]:::ui

subgraph ING["Ingestion Layer"]
direction TB
ING1["File uploader / folder scanner"]:::pipeline
ING2["File type detection + queueing\n(CSV, EVTX, other)"]:::pipeline
end

subgraph PARSE["Parsing & Normalization"]
direction TB
EVTX["EVTX Parser\n(python-evtx)"]:::pipeline
CSV["CSV Parser\n(pandas)"]:::pipeline
NORM["Normalizer\n(schema alignment, timestamps, fields)"]:::pipeline
end

subgraph RAG["Indexing / RAG Prep"]
direction TB
CHUNK["Chunking / Document builder"]:::ai
EMB["Embeddings generator\n(sentence-transformers / HuggingFace)"]:::ai
end

subgraph RET["Retrieval + Prompting"]
direction TB
VSTORE["Vector Store Adapter\n(ChromaDB integration)"]:::ai
RETR["Retriever\n(top-k relevant chunks)"]:::ai
LC["LangChain Orchestrator\n(prompt templates + chains)"]:::ai
OLL["Ollama Connector\n(LLM API client)"]:::ai
end

end

OUT["Outputs\nJSON reports / CSV summaries / audit logs"]:::doc
AUD[("Output Directory\n(Local artifacts)")]:::storage

%% Flows
INP -->|"selected_path / bytes"| ING1
UI -->|"start_analysis / options"| ING1
ING1 --> ING2
ING2 -->|"raw paths/bytes"| EVTX
ING2 -->|"raw paths/bytes"| CSV
EVTX -->|"structured events"| NORM
CSV -->|"rows / frames"| NORM
NORM -->|"documents / event batches"| CHUNK
CHUNK -->|"text chunks"| EMB
EMB -->|"vectors + metadata"| VSTORE
VSTORE -->|"persist/update"| CH

%% Interactive investigation loop
UI -->|"investigation task / follow-up question"| RETR
CH -->|"similarity search"| RETR
RETR -->|"top-k chunks"| LC
LC -->|"prompt + retrieved context"| OLL
OLL -->|"HTTP (Ollama API)"| OL
OL -->|"findings / narrative / structured response"| OLL
OLL -->|"LLM output"| LC
LC -->|"summaries / IOCs / timelines"| OUT
OUT -->|"write artifacts"| AUD
AUD -->|"open/view/download"| UI

EXT["Extensibility point:\nAdd new parser module into Parsing & Normalization"]:::note
PARSE -.->|"plugin_point"| EXT
PERSIST["Vector store persistence:\nLocal disk (Chroma) enables repeat queries"]:::note
CH -.-> PERSIST

end

%% =========================
%% Click Events (from component_mapping)
%% =========================
click APP "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click UI "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click ING1 "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click ING2 "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click EVTX "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click CSV "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click NORM "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click CHUNK "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click EMB "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click VSTORE "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click RETR "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click LC "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click OLL "https://github.com/dfirvault/forensiq/blob/main/ForensIQ.py"
click LCH "https://github.com/dfirvault/forensiq/blob/main/ForensIQLauncher.bat"
click MF "https://github.com/dfirvault/forensiq/tree/main/ModelFile"
click INP "https://github.com/dfirvault/forensiq/blob/main/test.csv"
click OUT "https://github.com/dfirvault/forensiq/blob/main/test_evtx_data.csv"
click NOTE1 "https://github.com/dfirvault/forensiq/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef external fill:#ffffff,stroke:#4b5563,stroke-width:1.5px,color:#111827;
classDef externalSvc fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#7c2d12;
classDef ui fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0b2a6f;
classDef pipeline fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#052e16;
classDef ai fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#2e1065;
classDef storage fill:#f3f4f6,stroke:#4b5563,stroke-width:2px,color:#111827;
classDef doc fill:#e5e7eb,stroke:#374151,stroke-width:2px,color:#111827;
classDef artifact fill:#fff7ed,stroke:#9a3412,stroke-width:2px,color:#7c2d12;
classDef model fill:#fed7aa,stroke:#c2410c,stroke-width:2px,color:#7c2d12;
classDef config fill:#cffafe,stroke:#0e7490,stroke-width:2px,color:#083344;
classDef launcher fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e;
classDef note fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#713f12,stroke-dasharray: 5 4;
```
