Data Flows
==========

This section details the key data flows within VulnerabilityHub, utilizing sequence diagrams to illustrate interactions between components.

Scan Upload Process
~~~~~~~~~~~~~~~~~~~

.. mermaid::

    sequenceDiagram
        participant User
        participant FE as Frontend
        participant API as Backend API
        participant Parser as XML Parser
        participant DB as Database
        
        User->>FE: Uploads XML Report
        FE->>API: POST /scans/upload
        API->>Parser: Parse XML Content
        Parser-->>API: Extraction (Hosts, Vulns)
        API->>DB: Transactional Save
        DB-->>API: Success
        API->>User: 200 OK (Upload Queued/Done)
        
        par Notifications
            API->>DB: Identify Contact Persons
            API->>User: Send Email Notification
        end

Contact Person Import
~~~~~~~~~~~~~~~~~~~~~

.. mermaid::

    sequenceDiagram
        participant Admin
        participant API as Backend API
        participant Importer as Import Service
        participant DB as Database
        
        Admin->>API: Trigger Import (CSV/DB)
        API->>Importer: Load Data
        Importer->>DB: Fetch Existing Contacts
        Importer->>Importer: Diff & Conflict Detection
        
        alt Conflicts Found
            Importer-->>API: Return Conflicts
            API-->>Admin: Request Resolution
        else No Conflicts
            Importer->>DB: Apply Changes (Create/Update/Delete)
            Importer->>DB: Log Audit Events
            API-->>Admin: Success
        end

Dispute Resolution Flow
~~~~~~~~~~~~~~~~~~~~~~~

When a user challenges the assignment of a report or finding.

.. mermaid::

    sequenceDiagram
        participant User
        participant API as Backend API
        participant DB as Database
        participant Admin
        
        User->>API: POST /disputes
        Note over User,API: Reason: "Not my IP"
        API->>DB: Create Dispute Record
        API-->>User: 200 OK
        
        Note over Admin: Review Process
        Admin->>API: GET /disputes
        Admin->>API: POST /disputes/{id}/resolve
        
        alt Resolved (Reassigned)
            API->>DB: Updates IP Ownership
            API->>DB: Closes Dispute
            API->>User: Email (Resolution)
        else Ignored
            API->>DB: Closes Dispute (Ignored)
        end

Report Access via Magic Link
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

How external contact persons access restricted reports without a full user account.

.. mermaid::

    sequenceDiagram
        participant CP as Contact Person
        participant API as Backend API
        participant DB as Database
        
        CP->>API: GET /reports/view/{token}
        API->>DB: Validate Token & Expiry
        
        alt Valid Token
            API->>DB: Log Access (IP, User Agent)
            API->>DB: Fetch Report Content
            API-->>CP: Visual Report (HTML/PDF)
        else Invalid/Expired
            API-->>CP: 403 Forbidden
        end

Vulnerability Prediction Flow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

How future vulnerability trends are calculated.

.. mermaid::

    sequenceDiagram
        participant Job as Scheduler
        participant Service as Prediction Service
        participant DB as Database
        participant Prophet as ML Engine
        
        Job->>Service: Trigger Analysis
        Service->>DB: Fetch Historical Data (vulnerability_time_series)
        DB-->>Service: Time Series Data
        Service->>Prophet: Fit Model & Predict
        Prophet-->>Service: Forecast Data
        Service->>DB: Store Predictions
        
        Note over DB: Grafana reads from here

Authentication Flow
~~~~~~~~~~~~~~~~~~~

User login process.

.. mermaid::

    sequenceDiagram
        participant User
        participant Frontend
        participant API as Backend API
        participant DB as Database
        
        User->>Frontend: Enter Credentials
        Frontend->>API: POST /auth/login
        API->>DB: Verify Username & Password Hash
        
        alt Valid
            DB-->>API: User Data
            API->>API: Generate Access Token (JWT)
            API-->>Frontend: Token + User Info
            Frontend->>Frontend: Store Token
        else Invalid
            API-->>Frontend: 401 Unauthorized
        end