# zysec-ai/project-zysec architecture

> Architecture diagram of the GitHub repository zysec-ai/project-zysec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zysec-ai/project-zysec
- Repository: https://github.com/zysec-ai/project-zysec

## Overview

##### Project Type and Purpose
- ZySec AI is a full-stack, Streamlit-based application that integrates an AI model specialized for cybersecurity (“ZySec 7B”). It provides a user interface combined with backend logic to deliver features such as playbook access, standards exploration, and optional AI-assisted internet research.
- Its design accounts for local or remote (GPU-based) deployments, with a special note on performance optimization (using VLLM on GPU environments).

##### Analyzing the File Structure
- The top level shows key files like app.py – the application’s entry point – along with a configuration (config.cfg) and deployment script (start.sh).
- The modules directory includes a variety of components:
- Utility modules (e.g., common_utils.py, file_utils.py, database_utils.py, message_store.py) which handle logging, file operations, and storage functions.
- Domain-specific modules (e.g., app_constants, app_logger, app_prompt, app_researcher, and several nav_* modules) that appear to encapsulate navigation and feature-specific logic.
- The presence of environment/deployment configuration (.devcontainer) further suggests an engineered approach to accommodate development and possibly containerized execution.

##### Extracting Architecture Insights from the README
- The README emphasizes AI-driven cybersecurity assistance, and highlights both local and GPU-deployed execution paths.
- Integration with external AI frameworks is signified by references to HuggingFace’s Zephyr series and deployment modes like vLLM.
- The Streamlit interface provides the frontend for user interaction, sending commands and receiving analytics and responses – hence, the separation of presentation and application logic is critical.

a. Core components:
- Frontend/UI: Represented by the Streamlit interface (invoked in app.py, accessible via the web).
- Application Server/Backend: The main application logic residing in app.py and coordinated by the modules. This layer handles business logic, logging, session utilities, and navigation (e.g., through modules/app_page_definitions.py, nav_* modules).
- AI Model Integration: The ZySec 7B model – likely interfaced using libraries or the llama-cpp-python[server] framework. Encompass both local (CPU) and remote (GPU with vLLM) deployment scenarios.
- Supporting Utilities: Include configuration management (config.cfg), logging (app_logger), file and database utilities, and other helper functions.

b. Relationships and data flows:
- From the backend, illustrate separate flows:
- One path towards the AI Model component (e.g., via the app_prompt or app_researcher modules) – showing data inputs (queries/requests) and responses (analysis).
- Another to the utility modules (like database_utils and file_utils) for data persistence, logging, and file management.
- Inter-module communications within the backend (e.g., navigation handling between different nav_* modules).

c. Architectural patterns and principles:
- Modular design: The separation of concerns is evident by splitting out business logic, utility functions, and navigation operations.
- Extensibility: The discrete modules suggest an architecture that allows for future expansion or feature enhancements with minimal disruption.
- Scalability and deployment flexibility: With pathways for both local and remote GPU deployments, the model integration component is pivotal and should be clearly isolated.

d. With relevant technologies, frameworks, or libraries:
- Frontend is implemented with Streamlit.
- The AI layer leverages the ZySec 7B model (built on HuggingFace Zephyr series) and is compatible with llama-cpp-python, and optionally vLLM for GPU deployment.
- Utility components might incorporate logging frameworks and file/database handling libraries (as referenced in modules).
- Deployment infrastructure includes container configurations (via .devcontainer) and shell-based startup controls (start.sh).

##### Final Reminders
- Do not overcomplicate: aim for a balance where each module’s role is distinct yet connected within the overall workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Streamlit Frontend"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["Application Backend / Core Modules"]:::backend
    end

    %% AI Model Service Layer
    subgraph "AI Model Service (ZySec 7B)"
        AP["App Prompt"]:::model
        AR["App Researcher"]:::model
    end

    %% Navigation Modules
    subgraph "Navigation Modules"
        NAV1["Nav About"]:::backend
        NAV2["Nav File Manager"]:::backend
        NAV3["Nav Query Docs"]:::backend
        NAV4["Nav Researcher"]:::backend
        NAV5["Nav Summarizer"]:::backend
    end

    %% Supporting Utilities & Deployment
    subgraph "Supporting Utilities & Deployment"
        UTIL1["App Logger"]:::utilities
        UTIL2["Common Utils"]:::utilities
        UTIL3["Database Utils"]:::utilities
        UTIL4["File Utils"]:::utilities
        UTIL5["Message Store"]:::utilities
        CFG["Config File"]:::utilities
        START["Start Script"]:::utilities
    end

    %% Connections
    FE -->|"user_request"| BE

    BE -->|"invoke_AI"| AP
    BE -->|"invoke_AI"| AR
    AP -->|"response"| BE
    AR -->|"response"| BE

    BE -->|"manage_navigation"| NAV1
    BE -->|"manage_navigation"| NAV2
    BE -->|"manage_navigation"| NAV3
    BE -->|"manage_navigation"| NAV4
    BE -->|"manage_navigation"| NAV5

    NAV1 -->|"return"| BE
    NAV2 -->|"return"| BE
    NAV3 -->|"return"| BE
    NAV4 -->|"return"| BE
    NAV5 -->|"return"| BE

    BE -->|"log_update"| UTIL1
    BE -->|"file_ops"| UTIL2
    BE -->|"db_ops"| UTIL3
    BE -->|"file_ops"| UTIL4
    BE -->|"store_msg"| UTIL5
    BE -->|"config"| CFG
    BE -->|"deployment"| START

    UTIL1 -->|"feedback"| BE
    UTIL2 -->|"feedback"| BE
    UTIL3 -->|"feedback"| BE
    UTIL4 -->|"feedback"| BE
    UTIL5 -->|"feedback"| BE

    %% Click Events
    click FE "https://github.com/zysec-ai/project-zysec/blob/main/app.py"
    click BE "https://github.com/zysec-ai/project-zysec/tree/main/modules/"
    click AP "https://github.com/zysec-ai/project-zysec/blob/main/modules/app_prompt.py"
    click AR "https://github.com/zysec-ai/project-zysec/blob/main/modules/app_researcher.py"
    click UTIL1 "https://github.com/zysec-ai/project-zysec/blob/main/modules/app_logger.py"
    click UTIL2 "https://github.com/zysec-ai/project-zysec/blob/main/modules/common_utils.py"
    click UTIL3 "https://github.com/zysec-ai/project-zysec/blob/main/modules/database_utils.py"
    click UTIL4 "https://github.com/zysec-ai/project-zysec/blob/main/modules/file_utils.py"
    click UTIL5 "https://github.com/zysec-ai/project-zysec/blob/main/modules/message_store.py"
    click CFG "https://github.com/zysec-ai/project-zysec/blob/main/config.cfg"
    click START "https://github.com/zysec-ai/project-zysec/blob/main/start.sh"
    click NAV1 "https://github.com/zysec-ai/project-zysec/blob/main/modules/nav_about.py"
    click NAV2 "https://github.com/zysec-ai/project-zysec/blob/main/modules/nav_file_manager.py"
    click NAV3 "https://github.com/zysec-ai/project-zysec/blob/main/modules/nav_query_docs.py"
    click NAV4 "https://github.com/zysec-ai/project-zysec/blob/main/modules/nav_researcher.py"
    click NAV5 "https://github.com/zysec-ai/project-zysec/blob/main/modules/nav_summarizer.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef model fill:#F08080,stroke:#333,stroke-width:2px;
    classDef utilities fill:#90EE90,stroke:#333,stroke-width:2px;
```
