# orochford/calculator architecture

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

- Interactive diagram: https://gitdiagram.com/orochford/calculator
- Repository: https://github.com/orochford/calculator

## Overview

##### Project Type and Purpose
- Recognize that this is a single-page (or multi-page) web application using Streamlit, so it’s essentially a full-stack (front-end/interactive backend) tool for budget visualization and analysis.
- Its purpose is to analyze security budgets using both built-in computations and data from Excel sources (usbusinesses.xlsx, calculator.xlsx).

##### Key Components
a. Frontend (User Interface):
- The Streamlit application itself.
- Multiple pages (located under the /pages directory) representing:
- Budget Calculator
- Industry Benchmarks
- NAICS Analysis
- Sector TAM Analysis
- Each of these corresponds to separate functionalities or “tabs” in the UI.

b. Data Layer:
- Excel Data Sources: “calculator.xlsx” and “usbusinesses.xlsx” are the primary datasets feeding the calculations.
- Data processing modules: files like data.py and examine_excel.py, which likely facilitate extraction and formatting of data.

c. Application Logic / Utilities:
- Utility functions and calculation logic in utils.py.
- Possibly “security_budget_calculator.py” as either a main entry point or a script encapsulating core logic.

d. Configuration and Development Environment:
- .streamlit and .devcontainer directories suggest deployment and development configurations.
- Git and license files denote source control and open-source aspects.

##### Relationships and Data Flow
- The user interacts with the Streamlit UI through a browser. The UI is rendered by Streamlit, which leads to different pages (via routing or module import) based on user selection.
- Each page invokes backend logic from the utility scripts, pulling data from the Excel files using the functions defined in data.py or examine_excel.py.
- The utility layer (utils.py) processes the data, performs necessary calculations, and then returns the results to be visualized on the UI.
- The configuration files (.streamlit/config.toml and .devcontainer/devcontainer.json) ensure that the environment is consistent, especially during deployment (for example, containerized development setups).

##### Architectural Patterns and Key Principles
- Separation of Concerns: Each major functionality (UI, data ingestion, processing) is broken out into its own module or directory. This modularity is evident from the structure (pages, separate Python modules for utilities, and data tasks).
- Multi-page Architecture: Leveraging Streamlit's support for multiple pages allows clear UI separation, making it easier to navigate through different analyses.
- Data-Driven Design: Emphasis on reading and processing data from Excel files underlines the data-centric design of the application.

##### Detail Overall
- Modular design which facilitates maintainability and extensibility since changes can be localized within specific modules (e.g., updating the NAICS analysis logic without impacting the budget calculator).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Web Browser"]:::frontend
        MainApp["Streamlit UI - Main Application"]:::frontend
        Page1["Budget Calculator Page"]:::frontend
        Page2["Industry Benchmarks Page"]:::frontend
        Page3["NAICS Analysis Page"]:::frontend
        Page4["Sector TAM Analysis Page"]:::frontend
    end

    %% Business Logic / Data Processing Layer
    subgraph "Business Logic / Data Processing Layer"
        Proc1["Data Extraction - data.py"]:::backend
        Proc2["Data Formatting - examine_excel.py"]:::backend
        Utils["Utility Functions and Calculation Logic - utils.py"]:::backend
    end

    %% Data & Configuration Layer
    subgraph "Data & Configuration Layer"
        ExcelCalc["Excel Data Source - Budget Calculation Data"]:::data
        ExcelUS["Excel Data Source - US Business Data"]:::data
        StreamlitConf["Streamlit Configuration"]:::data
        DevEnv["Development Environment Configuration"]:::data
    end

    %% Connections in Presentation Layer
    Browser --> MainApp
    MainApp --> Page1
    MainApp --> Page2
    MainApp --> Page3
    MainApp --> Page4

    %% Connections from Presentation to Business Logic
    MainApp --> Proc1
    MainApp --> Proc2
    MainApp --> Utils

    %% Business Logic accessing Data Sources
    Proc1 --> ExcelCalc
    Proc1 --> ExcelUS
    Proc2 --> ExcelCalc
    Proc2 --> ExcelUS

    %% Configuration affecting the UI
    StreamlitConf --> MainApp
    DevEnv --> MainApp

    %% Click Events
    click MainApp "https://github.com/orochford/calculator/blob/main/security_budget_calculator.py"
    click Page1 "https://github.com/orochford/calculator/blob/main/pages/budget_calculator.py"
    click Page2 "https://github.com/orochford/calculator/blob/main/pages/industry_benchmarks.py"
    click Page3 "https://github.com/orochford/calculator/blob/main/pages/naics_analysis.py"
    click Page4 "https://github.com/orochford/calculator/blob/main/pages/sector_tam_analysis.py"
    click Proc1 "https://github.com/orochford/calculator/blob/main/data.py"
    click Proc2 "https://github.com/orochford/calculator/blob/main/examine_excel.py"
    click Utils "https://github.com/orochford/calculator/blob/main/utils.py"
    click ExcelCalc "https://github.com/orochford/calculator/blob/main/calculator.xlsx"
    click ExcelUS "https://github.com/orochford/calculator/blob/main/usbusinesses.xlsx"
    click StreamlitConf "https://github.com/orochford/calculator/blob/main/.streamlit/config.toml"
    click DevEnv "https://github.com/orochford/calculator/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef data fill:#fff3cd,stroke:#333,stroke-width:2px;
```
