# t3rmixs/gptmatrix architecture

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

- Interactive diagram: https://gitdiagram.com/t3rmixs/gptmatrix
- Repository: https://github.com/t3rmixs/gptmatrix

## Overview

Security Lab Assistant is a Flask web app for managing scan records, running real Nmap scans through chat, and answering cybersecurity questions. The main workflow routes dashboard and AJAX requests into scan-record services for CRUD, filtering, sorting, and report export; chat requests are routed to Nmap execution, optional Groq responses, or local knowledge. Scan records persist in SQLite. The README also documents the browser UI and AJAX updates; the templates and JavaScript were not excerpted, so their runtime links are not detailed here.

Main entry points: [`app.py`](https://github.com/t3rmixs/gptmatrix/blob/main/app.py) (Flask routes), [`services/chat_service.py`](https://github.com/t3rmixs/gptmatrix/blob/main/services/chat_service.py) (Chat routing), [`services/scan_service.py`](https://github.com/t3rmixs/gptmatrix/blob/main/services/scan_service.py) (Record operations), [`templates/index.html`](https://github.com/t3rmixs/gptmatrix/blob/main/templates/index.html) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_flask["Flask routes<br/>[app.py]"]
  node_dashboard["Dashboard UI<br/>[index.html]"]
  node_styles["Terminal styling<br/>[style.css]"]
end

subgraph group_domain["Scan management"]
  node_record["Scan record model<br/>[target.py]"]
  node_validation["Validation errors<br/>[exceptions.py]"]
  node_scan_service["Record operations<br/>[scan_service.py]"]
  node_report["Text report export<br/>[scan_service.py]"]
end

subgraph group_chat["Chat and scanning"]
  node_chat_agent["Chat routing<br/>[chat_service.py]"]
  node_scanner["Nmap execution<br/>[scanner.py]"]
  node_groq["Groq API"]
  node_knowledge["Local knowledge<br/>[chat_service.py]"]
end

subgraph group_storage["Persistence"]
  node_db[("SQLite scan logs<br/>[database.py]")]
end

node_user(("User"))
node_nmap["Nmap binary"]
node_browser(("Browser"))

node_user -->|"uses"| node_browser
node_browser -->|"requests"| node_flask
node_flask -->|"renders"| node_dashboard
node_dashboard -.->|"styled by"| node_styles
node_flask -->|"calls"| node_scan_service
node_scan_service -->|"reads and writes"| node_db
node_flask -->|"routes chat"| node_chat_agent
node_chat_agent -->|"runs scans"| node_scanner
node_scanner -->|"executes"| node_nmap
node_chat_agent -->|"saves results"| node_scan_service
node_chat_agent -->|"requests answers"| node_groq
node_chat_agent -->|"matches locally"| node_knowledge
node_scan_service -->|"generates"| node_report
node_flask -->|"serves download"| node_report
node_record -->|"raises"| node_validation

click node_flask "https://github.com/t3rmixs/gptmatrix/blob/main/app.py"
click node_dashboard "https://github.com/t3rmixs/gptmatrix/blob/main/templates/index.html"
click node_styles "https://github.com/t3rmixs/gptmatrix/blob/main/static/css/style.css"
click node_record "https://github.com/t3rmixs/gptmatrix/blob/main/models/target.py"
click node_validation "https://github.com/t3rmixs/gptmatrix/blob/main/models/exceptions.py"
click node_scan_service "https://github.com/t3rmixs/gptmatrix/blob/main/services/scan_service.py"
click node_report "https://github.com/t3rmixs/gptmatrix/blob/main/services/scan_service.py"
click node_db "https://github.com/t3rmixs/gptmatrix/blob/main/repository/database.py"
click node_chat_agent "https://github.com/t3rmixs/gptmatrix/blob/main/services/chat_service.py"
click node_scanner "https://github.com/t3rmixs/gptmatrix/blob/main/services/scanner.py"
click node_knowledge "https://github.com/t3rmixs/gptmatrix/blob/main/services/chat_service.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_flask,node_dashboard,node_styles,node_user,node_browser toneBlue
class node_record,node_validation,node_scan_service,node_report toneAmber
class node_chat_agent,node_scanner,node_groq,node_knowledge toneMint
class node_db toneRose
class node_nmap toneIndigo
```

## Components

### Web interface

- [Flask routes](https://github.com/t3rmixs/gptmatrix/blob/main/app.py): `app.py`
- [Dashboard UI](https://github.com/t3rmixs/gptmatrix/blob/main/templates/index.html): `templates/index.html`
- [Terminal styling](https://github.com/t3rmixs/gptmatrix/blob/main/static/css/style.css): `static/css/style.css`

### Scan management

- [Scan record model](https://github.com/t3rmixs/gptmatrix/blob/main/models/target.py): `models/target.py`
- [Validation errors](https://github.com/t3rmixs/gptmatrix/blob/main/models/exceptions.py): `models/exceptions.py`
- [Record operations](https://github.com/t3rmixs/gptmatrix/blob/main/services/scan_service.py): `services/scan_service.py`
- [Text report export](https://github.com/t3rmixs/gptmatrix/blob/main/services/scan_service.py): `services/scan_service.py`

### Chat and scanning

- [Chat routing](https://github.com/t3rmixs/gptmatrix/blob/main/services/chat_service.py): `services/chat_service.py`
- [Nmap execution](https://github.com/t3rmixs/gptmatrix/blob/main/services/scanner.py): `services/scanner.py`
- **Groq API**
- [Local knowledge](https://github.com/t3rmixs/gptmatrix/blob/main/services/chat_service.py): `services/chat_service.py`

### Persistence

- [SQLite scan logs](https://github.com/t3rmixs/gptmatrix/blob/main/repository/database.py): `repository/database.py`

### Other components

- **User**
- **Nmap binary**
- **Browser**

## Connections

- User → Browser: uses (evidence: `README.md`)
- Browser → Flask routes: requests (evidence: `README.md`)
- Flask routes → Dashboard UI: renders (evidence: `app.py`)
- Dashboard UI → Terminal styling: styled by
- Flask routes → Record operations: calls (evidence: `app.py`)
- Record operations → SQLite scan logs: reads and writes (evidence: `services/scan_service.py`)
- Flask routes → Chat routing: routes chat (evidence: `app.py`)
- Chat routing → Nmap execution: runs scans (evidence: `services/chat_service.py`)
- Nmap execution → Nmap binary: executes (evidence: `services/scanner.py`)
- Chat routing → Record operations: saves results (evidence: `services/chat_service.py`)
- Chat routing → Groq API: requests answers (evidence: `services/chat_service.py`)
- Chat routing → Local knowledge: matches locally (evidence: `services/chat_service.py`)
- Record operations → Text report export: generates (evidence: `services/scan_service.py`)
- Flask routes → Text report export: serves download (evidence: `app.py`)
- Scan record model → Validation errors: raises (evidence: `models/target.py`)