# felix-ayi/togocyber-ia architecture

> Architecture diagram of the GitHub repository felix-ayi/togocyber-ia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/felix-ayi/togocyber-ia
- Repository: https://github.com/felix-ayi/togocyber-ia

## Overview

TogoCyber AI is a research prototype for network-threat and phishing/smishing detection, with explanations, an optional AI prevention assistant, and a Streamlit dashboard backed by a FastAPI service. The user workflow is to submit network features or a message in the dashboard, call the API, run the relevant detector, and display its prediction and explanation; prediction metadata can be viewed in history. Training and evaluation are meaningful supporting capabilities in the ML modules. Arrows reflect README statements and shown imports/calls; unsampled route internals and several subsystem links are left unspecified.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/router.py) (V1 routes), [`backend/app/repositories/history_repository.py`](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/repositories/history_repository.py) (History repository), [`ml/common/utils.py`](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/utils.py) (Model artifacts and registry), [`frontend/app.py`](https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/app.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Streamlit app<br/>[app.py]"]
  node_analysis_views["Analysis views"]
  node_history_view["History view<br/>[history.py]"]
  node_legal_views["Trust and legal pages"]
  node_api_client["HTTP client<br/>[api_client.py]"]
  node_result_card["Result display<br/>[result_card.py]"]
end

subgraph group_api["API and history"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_router["V1 routes<br/>[router.py]"]
  node_network_route["Network endpoint<br/>[network.py]"]
  node_phishing_route["Phishing endpoint<br/>[phishing.py]"]
  node_assistant_route["Assistant endpoint<br/>[assistant.py]"]
  node_history_route["History endpoint<br/>[history.py]"]
  node_history_service["History service<br/>[history_service.py]"]
  node_history_repo["History repository"]
  node_history_db[("SQLite history<br/>[database_models.py]")]
end

subgraph group_detection["Threat detection"]
  node_network_service["Network analysis<br/>[network_service.py]"]
  node_phishing_service["Phishing analysis"]
  node_network_model["Network prediction and XAI"]
  node_phishing_model["Text prediction and XAI"]
  node_feature_contract["Network feature contract<br/>[preprocessing.py]"]
end

subgraph group_assistant["Prevention assistant"]
  node_assistant_service["Assistant service"]
  node_assistant_context["Prompt context<br/>[context.py]"]
  node_llm_client["OpenAI client<br/>[llm_client.py]"]
end

subgraph group_ml["ML development"]
  node_network_training["Network training<br/>[train.py]"]
  node_phishing_training["Phishing training<br/>[train.py]"]
  node_metrics["Model metrics<br/>[metrics.py]"]
  node_artifacts[("Model artifacts and registry<br/>[utils.py]")]
end

node_user(("Dashboard user"))
node_openai["OpenAI API"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"dispatches views"| node_analysis_views
node_dashboard -->|"dispatches views"| node_legal_views
node_analysis_views -->|"requests analyses"| node_api_client
node_analysis_views -->|"renders results"| node_result_card
node_history_view -->|"requests history"| node_api_client
node_api_client -->|"HTTP requests"| node_api_app
node_api_app -->|"mounts routes"| node_api_router
node_api_router -->|"routes to"| node_network_route
node_api_router -->|"routes to"| node_phishing_route
node_api_router -->|"routes to"| node_assistant_route
node_api_router -->|"routes to"| node_history_route
node_network_route -->|"delegates to"| node_network_service
node_phishing_route -->|"delegates to"| node_phishing_service
node_network_service -->|"predicts and explains"| node_network_model
node_phishing_service -->|"predicts and explains"| node_phishing_model
node_network_model -->|"uses schema"| node_feature_contract
node_network_service -->|"records metadata"| node_history_repo
node_phishing_service -->|"records metadata"| node_history_repo
node_history_route -->|"delegates to"| node_history_service
node_history_service -->|"reads history"| node_history_repo
node_history_repo -->|"reads and writes"| node_history_db
node_assistant_route -->|"delegates to"| node_assistant_service
node_assistant_service -->|"builds messages"| node_assistant_context
node_assistant_service -->|"requests completion"| node_llm_client
node_llm_client -->|"HTTPS completion"| node_openai
node_network_training -->|"computes metrics"| node_metrics
node_phishing_training -->|"computes metrics"| node_metrics
node_network_training -->|"saves model"| node_artifacts
node_phishing_training -->|"saves model"| node_artifacts
node_network_model -->|"loads model"| node_artifacts
node_phishing_model -->|"loads model"| node_artifacts

click node_dashboard "https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/app.py"
click node_analysis_views "https://github.com/felix-ayi/togocyber-ia/tree/main/frontend/views"
click node_history_view "https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/views/history.py"
click node_legal_views "https://github.com/felix-ayi/togocyber-ia/tree/main/frontend/views"
click node_api_client "https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/services/api_client.py"
click node_result_card "https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/components/result_card.py"
click node_api_app "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/main.py"
click node_api_router "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/router.py"
click node_network_route "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/network.py"
click node_phishing_route "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/phishing.py"
click node_assistant_route "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/assistant.py"
click node_history_route "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/history.py"
click node_network_service "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/network_service.py"
click node_phishing_service "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/phishing_service.py"
click node_network_model "https://github.com/felix-ayi/togocyber-ia/tree/main/ml/network"
click node_phishing_model "https://github.com/felix-ayi/togocyber-ia/tree/main/ml/phishing"
click node_feature_contract "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/preprocessing.py"
click node_history_service "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/history_service.py"
click node_history_repo "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/repositories/history_repository.py"
click node_history_db "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/models/database_models.py"
click node_assistant_service "https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/assistant_service.py"
click node_assistant_context "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/assistant/context.py"
click node_llm_client "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/assistant/llm_client.py"
click node_network_training "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/network/train.py"
click node_phishing_training "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/phishing/train.py"
click node_metrics "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/metrics.py"
click node_artifacts "https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/utils.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_dashboard,node_analysis_views,node_history_view,node_legal_views,node_api_client,node_result_card,node_user toneBlue
class node_api_app,node_api_router,node_network_route,node_phishing_route,node_assistant_route,node_history_route,node_history_service,node_history_repo,node_history_db toneAmber
class node_network_service,node_phishing_service,node_network_model,node_phishing_model,node_feature_contract,node_openai toneMint
class node_assistant_service,node_assistant_context,node_llm_client toneRose
class node_network_training,node_phishing_training,node_metrics,node_artifacts toneIndigo
```

## Components

### Dashboard

- [Streamlit app](https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/app.py): `frontend/app.py`
- [Analysis views](https://github.com/felix-ayi/togocyber-ia/tree/main/frontend/views): `frontend/views`
- [History view](https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/views/history.py): `frontend/views/history.py`
- [Trust and legal pages](https://github.com/felix-ayi/togocyber-ia/tree/main/frontend/views): `frontend/views`
- [HTTP client](https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/services/api_client.py): `frontend/services/api_client.py`
- [Result display](https://github.com/felix-ayi/togocyber-ia/blob/main/frontend/components/result_card.py): `frontend/components/result_card.py`

### API and history

- [FastAPI app](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/main.py): `backend/app/main.py`
- [V1 routes](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Network endpoint](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/network.py): `backend/app/api/v1/routes/network.py`
- [Phishing endpoint](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/phishing.py): `backend/app/api/v1/routes/phishing.py`
- [Assistant endpoint](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/assistant.py): `backend/app/api/v1/routes/assistant.py`
- [History endpoint](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/api/v1/routes/history.py): `backend/app/api/v1/routes/history.py`
- [History service](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/history_service.py): `backend/app/services/history_service.py`
- [History repository](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/repositories/history_repository.py): `backend/app/repositories/history_repository.py`
- [SQLite history](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/models/database_models.py): `backend/app/models/database_models.py`

### Threat detection

- [Network analysis](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/network_service.py): `backend/app/services/network_service.py`
- [Phishing analysis](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/phishing_service.py): `backend/app/services/phishing_service.py`
- [Network prediction and XAI](https://github.com/felix-ayi/togocyber-ia/tree/main/ml/network): `ml/network`
- [Text prediction and XAI](https://github.com/felix-ayi/togocyber-ia/tree/main/ml/phishing): `ml/phishing`
- [Network feature contract](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/preprocessing.py): `ml/common/preprocessing.py`

### Prevention assistant

- [Assistant service](https://github.com/felix-ayi/togocyber-ia/blob/main/backend/app/services/assistant_service.py): `backend/app/services/assistant_service.py`
- [Prompt context](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/assistant/context.py): `ml/assistant/context.py`
- [OpenAI client](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/assistant/llm_client.py): `ml/assistant/llm_client.py`

### ML development

- [Network training](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/network/train.py): `ml/network/train.py`
- [Phishing training](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/phishing/train.py): `ml/phishing/train.py`
- [Model metrics](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/metrics.py): `ml/common/metrics.py`
- [Model artifacts and registry](https://github.com/felix-ayi/togocyber-ia/blob/main/ml/common/utils.py): `ml/common/utils.py`

### Other components

- **Dashboard user**
- **OpenAI API**

## Connections

- Dashboard user → Streamlit app: uses
- Streamlit app → Analysis views: dispatches views (evidence: `frontend/app.py`)
- Streamlit app → Trust and legal pages: dispatches views (evidence: `frontend/app.py`)
- Analysis views → HTTP client: requests analyses (evidence: `frontend/views/home.py`)
- Analysis views → Result display: renders results (evidence: `frontend/views/home.py`)
- History view → HTTP client: requests history
- HTTP client → FastAPI app: HTTP requests (evidence: `frontend/services/api_client.py`)
- FastAPI app → V1 routes: mounts routes (evidence: `backend/app/main.py`)
- V1 routes → Network endpoint: routes to (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Phishing endpoint: routes to (evidence: `backend/app/api/v1/router.py`)
- V1 routes → Assistant endpoint: routes to (evidence: `backend/app/api/v1/router.py`)
- V1 routes → History endpoint: routes to (evidence: `backend/app/api/v1/router.py`)
- Network endpoint → Network analysis: delegates to (evidence: `backend/app/services/network_service.py`)
- Phishing endpoint → Phishing analysis: delegates to (evidence: `backend/app/services/phishing_service.py`)
- Network analysis → Network prediction and XAI: predicts and explains (evidence: `backend/app/services/network_service.py`)
- Phishing analysis → Text prediction and XAI: predicts and explains (evidence: `backend/app/services/phishing_service.py`)
- Network prediction and XAI → Network feature contract: uses schema (evidence: `ml/network/predict.py`)
- Network analysis → History repository: records metadata (evidence: `backend/app/services/network_service.py`)
- Phishing analysis → History repository: records metadata (evidence: `backend/app/services/phishing_service.py`)
- History endpoint → History service: delegates to (evidence: `backend/app/api/v1/routes/history.py`)
- History service → History repository: reads history
- History repository → SQLite history: reads and writes (evidence: `backend/app/repositories/history_repository.py`)
- Assistant endpoint → Assistant service: delegates to (evidence: `backend/app/api/v1/routes/assistant.py`)
- Assistant service → Prompt context: builds messages (evidence: `backend/app/services/assistant_service.py`)
- Assistant service → OpenAI client: requests completion (evidence: `backend/app/services/assistant_service.py`)
- OpenAI client → OpenAI API: HTTPS completion (evidence: `ml/assistant/llm_client.py`)
- Network training → Model metrics: computes metrics (evidence: `ml/network/train.py`)
- Phishing training → Model metrics: computes metrics (evidence: `ml/phishing/train.py`)
- Network training → Model artifacts and registry: saves model (evidence: `ml/network/train.py`)
- Phishing training → Model artifacts and registry: saves model (evidence: `ml/phishing/train.py`)
- Network prediction and XAI → Model artifacts and registry: loads model (evidence: `ml/network/predict.py`)
- Text prediction and XAI → Model artifacts and registry: loads model (evidence: `ml/phishing/predict.py`)
