Architecture
============

This document describes the architecture and components of VulnerabilityHub.

System Overview
---------------

VulnerabilityHub follows a modern three-tier architecture, designed for scalability and maintainability. It separates the presentation layer (Frontend) from the business logic (Backend API) and data persistence (Database).

.. mermaid::

    graph TD
        User[User / Admin] -->|HTTPS| Frontend["Frontend SPA<br/>(Vue 3 + Vuetify)"]
        Frontend -->|REST API| Backend["Backend API<br/>(FastAPI)"]
        
        subgraph Data Layer
            DB[("MariaDB<br/>Database")]
        end
        
        subgraph External Services
            SMTP[SMTP Server]
            ExtDB["External CMDB<br/>(Optional)"]
            LDAP["LDAP / AD<br/>(Future/Optional)"]
            ClamAV[ClamAV Scanner]
        end
        
        subgraph Observability
            Grafana[Grafana]
            Prometheus[Prometheus]
        end

        Backend -->|SQLAlchemy| DB
        Backend -->|SMTP| SMTP
        Backend -->|Import| ExtDB
        Backend -->|Auth| LDAP
        Backend -->|Scan| ClamAV
        
        Prometheus -->|Scrape Metrics| Backend
        Grafana -->|Query| DB
        Grafana -->|Query| Prometheus

Core Components
---------------

1. Frontend (Vue 3)
~~~~~~~~~~~~~~~~~~~

The frontend is a Single Page Application (SPA) built with Vue 3 and TypeScript.

- **Framework**: Vue 3 (Composition API)
- **UI Library**: Vuetify 3 (Material Design)
- **State Management**: Pinia
- **Routing**: Vue Router
- **Networking**: Axios

It handles user authentication, scan management, interactive dashboards, and administration interfaces.

2. Backend (FastAPI)
~~~~~~~~~~~~~~~~~~~~

The backend is a high-performance, async REST API built with Python 3.9+ and FastAPI.

- **API Framework**: FastAPI
- **ORM**: SQLAlchemy (Sync/Async patterns)
- **Validation**: Pydantic v2
- **ML Engine**: Facebook Prophet (for vulnerability forecasting)
- **Security**: OAuth2/JWT flavor for auth, Role-Based Access Control (RBAC).

**Key Responsibilities**:
- XML Parsing (Greenbone/OpenVAS reports)
- Business Logic (Disputes, Notifications, Imports)
- Background Tasks (Email sending, File processing)
- Audit Logging (Comprehensive tracking of actions)
- **Virus Scanning**: Integrated with **ClamAV** to scan all uploaded files.

3. Database (MariaDB)
~~~~~~~~~~~~~~~~~~~~~

The relational database serves as the single source of truth.

- **Core Data**: Scans, Hosts, Vulnerabilities, Results.
- **Identity**: Users, Contact Persons, Permissions.
- **Audit**: `audit_logs`, `access_logs`.
- **Time Series**: Materialized views for efficient analytics.

4. Monitoring (Grafana + Prometheus)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- **Grafana**: Visualizes vulnerability trends and system metrics directly from the DB and via Prometheus.
- **Prometheus**: Scrapes application metrics (endpoint latency, error rates) exposed by `prometheus-fastapi-instrumentator`.

Data Flows
----------

For detailed diagrams of system interactions (Scan Upload, Dispute Resolution, etc.), please refer to :doc:`data_flows`.

Security Architecture
---------------------

- **Audit Logging**: Every critical action (create/update/delete, file access) is logged to the `audit_logs` table. See :doc:`audit_logging`.
- **Input Validation**: Strict typing with Pydantic prevents injection and data corruption.
- **Authentication**: Stateless JWT tokens with distinction between "User" (interactive) and "Contact Person" (magic link) contexts.
    - *Future Plan*: LDAP/AD integration for simplified user management.
- **Network Isolation**: Database and internal services are not exposed publicly in production environments.