# idkhowtocodefr/semantic-comment-analyze architecture

> Architecture diagram of the GitHub repository idkhowtocodefr/semantic-comment-analyze, 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/idkhowtocodefr/semantic-comment-analyze
- Repository: https://github.com/idkhowtocodefr/semantic-comment-analyze

## Overview

The platform analyzes customer text through a FastAPI service and offers both single-text and CSV batch workflows. Single analysis returns intent, sentiment, optional word-level explanations, and business recommendations; batch processing streams enriched CSV rows. The README also describes entity extraction and model training, though the sampled request orchestrator does not wire entity extraction into its response. The graph reflects source-supported calls and documented capabilities; unsampled details are represented only at existing source paths.

Main entry points: [`src/data/data_handler.py`](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/data/data_handler.py) (CSV streaming), [`src/engine/nlp_engine.py`](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py) (Inference orchestration), [`src/api/server.py`](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/api/server.py) (FastAPI routes), [`frontend/src/app/page.tsx`](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/app/page.tsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webapp["Web app<br/>[page.tsx]"]
  node_single["Single analysis"]
  node_batch["Batch upload"]
end

subgraph group_service["API and workflows"]
  node_api["FastAPI routes<br/>[server.py]"]
  node_csv["CSV streaming<br/>[data_handler.py]"]
end

subgraph group_analysis["Semantic analysis"]
  node_orchestrator["Inference orchestration<br/>[nlp_engine.py]"]
  node_embeddings["Text embeddings<br/>[nlp_engine.py]"]
  node_intent["Intent classifier<br/>[nlp_engine.py]"]
  node_explain["Word explanations<br/>[nlp_engine.py]"]
  node_sentiment["Sentiment analysis<br/>[nlp_engine.py]"]
  node_irony["Irony detection<br/>[nlp_engine.py]"]
  node_entities["Entity extraction<br/>[nlp_engine.py]"]
  node_evaluation["Business heuristics<br/>[evaluation.py]"]
end

subgraph group_modeling["Model training"]
  node_intenttraining["Intent training<br/>[train_intent.py]"]
  node_sentimenttraining["Sentiment fine-tuning<br/>[train_sentiment.py]"]
end

node_user(("Analyst"))
node_csvfile["CSV file"]
node_response["Analysis results"]
node_trainingdata["Training dataset<br/>[training_data.csv]"]
node_labelmap["Intent labels<br/>[label_mapping.txt]"]

node_user -->|"uses"| node_webapp
node_webapp -->|"selects view"| node_single
node_webapp -->|"selects view"| node_batch
node_single -->|"POST /api/analyze"| node_api
node_api -->|"runs inference"| node_orchestrator
node_orchestrator -->|"classifies intent"| node_intent
node_orchestrator -->|"analyzes sentiment"| node_sentiment
node_orchestrator -->|"optionally explains"| node_explain
node_sentiment -->|"adjusts sarcasm"| node_irony
node_api -->|"evaluates context"| node_evaluation
node_api -->|"returns JSON"| node_response
node_single -->|"renders results"| node_response
node_batch -->|"uploads"| node_csvfile
node_batch -->|"POST /api/batch"| node_api
node_api -->|"streams processing"| node_csv
node_csv -->|"embeds text"| node_embeddings
node_csv -->|"classifies rows"| node_intent
node_csv -->|"scores rows"| node_sentiment
node_csv -->|"evaluates rows"| node_evaluation
node_csv -->|"streams enriched CSV"| node_response
node_orchestrator -->|"embeds text"| node_embeddings
node_orchestrator -->|"extracts entities"| node_entities
node_intenttraining -->|"trains from"| node_trainingdata
node_intenttraining -.->|"uses labels"| node_labelmap
node_sentimenttraining -.->|"fine-tunes from"| node_trainingdata

click node_webapp "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/app/page.tsx"
click node_single "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/components/SingleAnalysisView.tsx"
click node_batch "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/components/BatchProcessingView.tsx"
click node_api "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/api/server.py"
click node_orchestrator "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_embeddings "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_intent "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_explain "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_sentiment "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_irony "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_entities "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py"
click node_evaluation "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/evaluation.py"
click node_csv "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/data/data_handler.py"
click node_intenttraining "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/train_intent.py"
click node_sentimenttraining "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/train_sentiment.py"
click node_trainingdata "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/data/training_data.csv"
click node_labelmap "https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/data/label_mapping.txt"

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_webapp,node_single,node_batch toneBlue
class node_api,node_csv toneAmber
class node_orchestrator,node_embeddings,node_intent,node_explain,node_sentiment,node_irony,node_entities,node_evaluation toneMint
class node_intenttraining,node_sentimenttraining toneRose
class node_user,node_csvfile,node_response toneIndigo
class node_trainingdata,node_labelmap toneTeal
```

## Components

### User experience

- [Web app](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Single analysis](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/components/SingleAnalysisView.tsx): `frontend/src/components/SingleAnalysisView.tsx`
- [Batch upload](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/frontend/src/components/BatchProcessingView.tsx): `frontend/src/components/BatchProcessingView.tsx`

### API and workflows

- [FastAPI routes](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/api/server.py): `src/api/server.py`
- [CSV streaming](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/data/data_handler.py): `src/data/data_handler.py`

### Semantic analysis

- [Inference orchestration](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Text embeddings](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Intent classifier](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Word explanations](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Sentiment analysis](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Irony detection](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Entity extraction](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/nlp_engine.py): `src/engine/nlp_engine.py`
- [Business heuristics](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/evaluation.py): `src/engine/evaluation.py`

### Model training

- [Intent training](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/train_intent.py): `src/engine/train_intent.py`
- [Sentiment fine-tuning](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/src/engine/train_sentiment.py): `src/engine/train_sentiment.py`

### Other components

- **Analyst**
- **CSV file**
- **Analysis results**
- [Training dataset](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/data/training_data.csv): `data/training_data.csv`
- [Intent labels](https://github.com/idkhowtocodefr/semantic-comment-analyze/blob/main/data/label_mapping.txt): `data/label_mapping.txt`

## Connections

- Analyst → Web app: uses
- Web app → Single analysis: selects view
- Web app → Batch upload: selects view
- Single analysis → FastAPI routes: POST /api/analyze
- FastAPI routes → Inference orchestration: runs inference
- Inference orchestration → Intent classifier: classifies intent
- Inference orchestration → Sentiment analysis: analyzes sentiment
- Inference orchestration → Word explanations: optionally explains
- Sentiment analysis → Irony detection: adjusts sarcasm
- FastAPI routes → Business heuristics: evaluates context
- FastAPI routes → Analysis results: returns JSON
- Single analysis → Analysis results: renders results
- Batch upload → CSV file: uploads
- Batch upload → FastAPI routes: POST /api/batch
- FastAPI routes → CSV streaming: streams processing
- CSV streaming → Text embeddings: embeds text
- CSV streaming → Intent classifier: classifies rows
- CSV streaming → Sentiment analysis: scores rows
- CSV streaming → Business heuristics: evaluates rows
- CSV streaming → Analysis results: streams enriched CSV
- Inference orchestration → Text embeddings: embeds text
- Inference orchestration → Entity extraction: extracts entities
- Intent training → Training dataset: trains from
- Intent training → Intent labels: uses labels
- Sentiment fine-tuning → Training dataset: fine-tunes from