# giuliovigano98/italian-penal-code-qa architecture

> Architecture diagram of the GitHub repository giuliovigano98/italian-penal-code-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giuliovigano98/italian-penal-code-qa
- Repository: https://github.com/giuliovigano98/italian-penal-code-qa

## Overview

This is a command-line Q&A application for answering questions about Italian penal-code PDFs. Users first run setup to extract and chunk a document, then build either a TF-IDF index or transformer embeddings; ask and interactive commands retrieve relevant chunks and pass their text to Ollama for answer generation. The graph also preserves the documented legal-text training and embedding capabilities. Transformer internals are only partially excerpted, so edges are limited to relationships visible in the excerpts or README.

Main entry points: [`main.py`](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/main.py) (CLI Commands), [`src/qa_system.py`](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py) (TF-IDF Search), [`src/transformer_trainer.py`](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py) (Transformer Embeddings), [`src/ollama_client.py`](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/ollama_client.py) (Ollama Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Workflow"]
  node_cli_entry["CLI Commands<br/>[main.py]"]
  node_answer_output["Answer Display<br/>[main.py]"]
end

subgraph group_documents["Document Processing"]
  node_pdf_processor["PDF Processor<br/>[pdf_processor.py]"]
  node_text_chunks["Text Chunks<br/>[pdf_processor.py]"]
end

subgraph group_retrieval["Retrieval Systems"]
  node_tfidf_search["TF-IDF Search<br/>[qa_system.py]"]
  node_keyword_search["Keyword Fallback<br/>[qa_system.py]"]
  node_tfidf_store[("TF-IDF Store<br/>[qa_system.py]")]
  node_transformer_system["Transformer Embeddings"]
  node_legal_cleaner["Legal Text Cleaner"]
  node_model_training["BERT Fine-Tuning"]
  node_embedding_store[("Embedding Store")]
end

subgraph group_generation["Answer Generation"]
  node_context_builder["Context Builder<br/>[qa_system.py]"]
  node_ollama_client["Ollama Client<br/>[ollama_client.py]"]
end

node_user(("User"))
node_pdf_input["Legal PDF"]
node_ollama_service{{"Ollama Service"}}

node_user -->|"runs commands"| node_cli_entry
node_pdf_input -->|"provides PDF"| node_pdf_processor
node_cli_entry -->|"processes PDF"| node_pdf_processor
node_pdf_processor -->|"extracts and chunks"| node_text_chunks
node_cli_entry -->|"builds index"| node_tfidf_search
node_text_chunks -->|"indexes chunks"| node_tfidf_search
node_tfidf_search -->|"saves and loads"| node_tfidf_store
node_cli_entry -->|"selects mode"| node_transformer_system
node_text_chunks -->|"builds embeddings"| node_transformer_system
node_transformer_system -->|"trains model"| node_model_training
node_model_training -->|"cleans legal text"| node_legal_cleaner
node_transformer_system -->|"saves and loads"| node_embedding_store
node_cli_entry -->|"searches question"| node_tfidf_search
node_tfidf_search -->|"falls back"| node_keyword_search
node_cli_entry -->|"searches question"| node_transformer_system
node_tfidf_search -->|"builds context"| node_context_builder
node_cli_entry -->|"requests answer"| node_ollama_client
node_context_builder -->|"provides context"| node_ollama_client
node_ollama_client -->|"calls generation API"| node_ollama_service
node_ollama_client -->|"requests embeddings"| node_ollama_service
node_cli_entry -->|"displays answer"| node_answer_output
node_answer_output -->|"returns answer"| node_user

click node_cli_entry "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/main.py"
click node_pdf_processor "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/pdf_processor.py"
click node_text_chunks "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/pdf_processor.py"
click node_tfidf_search "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py"
click node_keyword_search "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py"
click node_tfidf_store "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py"
click node_transformer_system "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py"
click node_legal_cleaner "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py"
click node_model_training "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py"
click node_embedding_store "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py"
click node_context_builder "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py"
click node_ollama_client "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/ollama_client.py"
click node_answer_output "https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/main.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_cli_entry,node_answer_output,node_user toneBlue
class node_pdf_processor,node_text_chunks toneAmber
class node_tfidf_search,node_keyword_search,node_tfidf_store,node_transformer_system,node_legal_cleaner,node_model_training,node_embedding_store toneMint
class node_context_builder,node_ollama_client toneRose
class node_pdf_input,node_ollama_service toneIndigo
```

## Components

### CLI Workflow

- [CLI Commands](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/main.py): `main.py`
- [Answer Display](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/main.py): `main.py`

### Document Processing

- [PDF Processor](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/pdf_processor.py): `src/pdf_processor.py`
- [Text Chunks](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/pdf_processor.py): `src/pdf_processor.py`

### Retrieval Systems

- [TF-IDF Search](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py): `src/qa_system.py`
- [Keyword Fallback](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py): `src/qa_system.py`
- [TF-IDF Store](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py): `src/qa_system.py`
- [Transformer Embeddings](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py): `src/transformer_trainer.py`
- [Legal Text Cleaner](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py): `src/transformer_trainer.py`
- [BERT Fine-Tuning](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py): `src/transformer_trainer.py`
- [Embedding Store](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/transformer_trainer.py): `src/transformer_trainer.py`

### Answer Generation

- [Context Builder](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/qa_system.py): `src/qa_system.py`
- [Ollama Client](https://github.com/giuliovigano98/italian-penal-code-qa/blob/main/src/ollama_client.py): `src/ollama_client.py`

### Other components

- **User**
- **Legal PDF**
- **Ollama Service**

## Connections

- User → CLI Commands: runs commands (evidence: `main.py`)
- Legal PDF → PDF Processor: provides PDF (evidence: `README.md`)
- CLI Commands → PDF Processor: processes PDF (evidence: `main.py`)
- PDF Processor → Text Chunks: extracts and chunks (evidence: `src/pdf_processor.py`)
- CLI Commands → TF-IDF Search: builds index (evidence: `main.py`)
- Text Chunks → TF-IDF Search: indexes chunks (evidence: `src/qa_system.py`)
- TF-IDF Search → TF-IDF Store: saves and loads (evidence: `src/qa_system.py`)
- CLI Commands → Transformer Embeddings: selects mode (evidence: `main.py`)
- Text Chunks → Transformer Embeddings: builds embeddings (evidence: `main.py`)
- Transformer Embeddings → BERT Fine-Tuning: trains model (evidence: `src/transformer_trainer.py`)
- BERT Fine-Tuning → Legal Text Cleaner: cleans legal text (evidence: `src/transformer_trainer.py`)
- Transformer Embeddings → Embedding Store: saves and loads (evidence: `src/transformer_trainer.py`)
- CLI Commands → TF-IDF Search: searches question (evidence: `main.py`)
- TF-IDF Search → Keyword Fallback: falls back (evidence: `src/qa_system.py`)
- CLI Commands → Transformer Embeddings: searches question (evidence: `main.py`)
- TF-IDF Search → Context Builder: builds context (evidence: `src/qa_system.py`)
- CLI Commands → Ollama Client: requests answer (evidence: `main.py`)
- Context Builder → Ollama Client: provides context (evidence: `src/qa_system.py`)
- Ollama Client → Ollama Service: calls generation API (evidence: `src/ollama_client.py`)
- Ollama Client → Ollama Service: requests embeddings (evidence: `src/ollama_client.py`)
- CLI Commands → Answer Display: displays answer (evidence: `main.py`)
- Answer Display → User: returns answer (evidence: `main.py`)
