# martimy/bat-q architecture

> Architecture diagram of the GitHub repository martimy/bat-q, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martimy/bat-q
- Repository: https://github.com/martimy/bat-q

## Overview

##### Project type and purpose
- Bat-Q is a Streamlit-based web application for interactive network configuration analysis.
- It leverages the Batfish network analysis engine (running in a Docker container) via the pyBatfish API.

##### File structure
- Home.py
- Entry point: sets up the Streamlit app, navigation menu, and dispatches to individual pages.
- pages/
- 1_Questions.py, 2_Analysis.py, 3_Fail_Tests.py, 4_Differential.py
- Each module implements one Streamlit “page” of the wizard (question selection, result display, failure simulation, comparative analysis).
- pages/common/
- plotting.py – topology and data visualization helpers
- presenter.py – transforms raw query answers into tables/plots
- queries.py – wrappers around pyBatfish question calls
- questions.py – metadata and grouping of available Batfish questions
- reader.py – handles snapshot .zip ingestion and Batfish snapshot creation
- utils.py – shared utility functions (file I/O, environment variable lookup, error handling)
- pics/
- Static screenshots used in the README (not part of runtime flow)
- requirements.txt
- Lists Streamlit, pyBatfish (pinned to a compatible version), and other Python dependencies
- .gitignore, LICENSE, README.md

##### README for additional insights
- Architecture is not explicitly diagrammed, but the narrative describes five main user flows (upload/home, questions, analysis, failure tests, differential).
- Underlying pattern: a single­-process Streamlit app that orchestrates pyBatfish queries against a remote or local Docker–hosted Batfish server.
- Data flows: user → Streamlit UI → common.reader → pyBatfish → Batfish server → common.presenter/plotting → Streamlit UI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Browser(("Browser")):::presentation

    %% Streamlit Application
    subgraph "Streamlit App (Port 8501)"
        direction TB
        Home["Home.py"]:::presentation
        QPage["Questions Page"]:::presentation
        APage["Analysis Page"]:::presentation
        FPage["Failure Tests Page"]:::presentation
        DPage["Differential Page"]:::presentation

        subgraph "Common Modules"
            direction TB
            Reader["Snapshot Reader"]:::service
            Queries["Query Wrappers"]:::service
            Presenter["Presenter"]:::service
            Plotting["Plotting Helpers"]:::service
            Utils["Utility Functions"]:::service
        end
    end

    %% External Service
    BatfishServer(("Batfish Server\n(Docker)\nPorts: 9996/9997")):::external

    %% Storage
    FileStorage[(File Storage)]:::storage

    %% Environment Note
    EnvNote{{"Env: BATFISH_SERVER"}}:::note

    %% Connections
    Browser -->|"UI Events"| Home
    Browser -->|"UI Events"| QPage
    Browser -->|"UI Events"| APage
    Browser -->|"UI Events"| FPage
    Browser -->|"UI Events"| DPage

    Home -->|"load/upload snapshot"| Reader
    QPage -->|"invoke queries"| Queries
    APage -->|"invoke queries"| Queries
    FPage -->|"invoke queries"| Queries
    DPage -->|"invoke queries"| Queries

    Reader -->|"create snapshot via pyBatfish"| BatfishServer
    Queries -->|"send questions"| BatfishServer
    BatfishServer -->|"JSON results"| Presenter
    BatfishServer -->|"JSON results"| Plotting

    Presenter -->|"formatted data"| Home
    Presenter -->|"formatted data"| QPage
    Presenter -->|"formatted data"| APage
    Presenter -->|"formatted data"| FPage
    Presenter -->|"formatted data"| DPage

    Plotting -->|"diagrams/charts"| Home
    Plotting -->|"diagrams/charts"| QPage
    Plotting -->|"diagrams/charts"| APage
    Plotting -->|"diagrams/charts"| FPage
    Plotting -->|"diagrams/charts"| DPage

    Home <-->|"snapshot .zip, YAML"| FileStorage
    QPage <-->|"snapshot .zip, YAML"| FileStorage
    APage <-->|"snapshot .zip, YAML"| FileStorage
    FPage <-->|"snapshot .zip, YAML"| FileStorage
    DPage <-->|"snapshot .zip, YAML"| FileStorage

    Home --- EnvNote

    %% Click Events
    click Home "https://github.com/martimy/bat-q/blob/main/Home.py"
    click QPage "https://github.com/martimy/bat-q/blob/main/pages/1_Questions.py"
    click APage "https://github.com/martimy/bat-q/blob/main/pages/2_Analysis.py"
    click FPage "https://github.com/martimy/bat-q/blob/main/pages/3_Fail_Tests.py"
    click DPage "https://github.com/martimy/bat-q/blob/main/pages/4_Differential.py"
    click Plotting "https://github.com/martimy/bat-q/blob/main/pages/common/plotting.py"
    click Presenter "https://github.com/martimy/bat-q/blob/main/pages/common/presenter.py"
    click Queries "https://github.com/martimy/bat-q/blob/main/pages/common/queries.py"
    click Reader "https://github.com/martimy/bat-q/blob/main/pages/common/reader.py"
    click Utils "https://github.com/martimy/bat-q/blob/main/pages/common/utils.py"
    click QPage "https://github.com/martimy/bat-q/blob/main/pages/common/questions.py"
    click FileStorage "https://github.com/martimy/bat-q/blob/main/requirements.txt"
    click FileStorage "https://github.com/martimy/bat-q/blob/main/README.md"
    click FileStorage "https://github.com/martimy/bat-q/tree/main/pics/"
    click FileStorage "https://github.com/martimy/bat-q/blob/main/.gitignore"
    click FileStorage "https://github.com/martimy/bat-q/tree/main/LICENSE"

    %% Styles
    classDef presentation fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef service fill:#a2d7ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffbd7d,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef note fill:#ffffb3,stroke:#333,stroke-width:1px
```
