# igor-ferreira-bezerra/average-price-ir-calculator architecture

> Architecture diagram of the GitHub repository igor-ferreira-bezerra/average-price-ir-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/igor-ferreira-bezerra/average-price-ir-calculator
- Repository: https://github.com/igor-ferreira-bezerra/average-price-ir-calculator

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack Python web application built with Streamlit.
- Its purpose is to calculate the average price of securities (ações and FIIs) from an uploaded Excel “Movimentação” sheet, handle special operations (desdobro, bonificação, transferência, atualização) and enrich results by merging static CNPJ CSV files.

##### File Structure
- Top-level entrypoint: `calculator.py` (Streamlit app containing UI + business logic).
- Data folder: `data/CNPJs_FII.csv`, `data/CNPJs_ACOES.csv` (external metadata).
- Config/development: `.devcontainer/devcontainer.json` (defines a reproducible dev environment).
- Dependency manifest: `requirements.txt` (Pandas, OpenPyXL, Streamlit).

##### Main Components
a. User (browser)
b. Streamlit Front-End (calculator.py UI components)
c. Calculation Engine (data ingestion, preprocessing, average price logic, special operation handlers)
d. Data Sources
- Uploaded Excel (runtime input)
- Static CSVs (`CNPJs_FII.csv`, `CNPJs_ACOES.csv`)
e. Python Runtime / DevContainer (environment boundary)

##### Relationships and Data Flow
- User → Streamlit UI: uploads Excel, sets year-base, confirms updates
- Streamlit UI → Calculation Engine: invokes preprocessing & calculation functions
- Calculation Engine → Excel Reader (OpenPyXL/Pandas): reads “Movimentação” sheet
- Calculation Engine → CSV Reader (Pandas): loads and merges CNPJ data
- Calculation Engine → Streamlit UI: returns two result tables (FIIs / Ações)
- (Optional) DevContainer wraps the Python runtime and dependencies

##### Architectural Patterns and Principles
- Monolith with clearly separated concerns: UI vs. processing vs. data
- MVC-ish: Streamlit handles view + controller, Pandas DataFrames are the model
- Pipeline-style data processing: ingest → transform → merge → output
- File-based integration instead of networked microservices

##### Diagramming Conventions
- Blue rectangle for UI
- Green rectangle for Processing/Calculation Engine
- UI → Calculation Engine (“trigger preprocessing & calc”)
- Calculation Engine → UI (“render result tables”)

##### Detail Without Over-Modularizing
- Every major step—file ingestion, special-case handling (desdobro, bonificação, atualização), data enrichment, result rendering.
- Avoid splitting into dozens of microservices; keep it monolithic but clearly partitioned by responsibility.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    User["User (Browser)"] 

    %% Environment
    subgraph "DevContainer / Python Runtime\n(.devcontainer/devcontainer.json)" 
        classDef env fill:#ddd,stroke:#999,color:#333;
        class DevContainer env
        DevContainer["Python 3.7+ Environment\nStreamlit, Pandas, OpenPyXL"] 

        %% Presentation Layer
        subgraph "Presentation Layer"
            classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
            UI["Streamlit Front-End UI"] 
            class UI ui
        end

        %% Business Logic Layer
        subgraph "Business Logic Layer"
            classDef logic fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
            Engine["Calculation Engine"] 
            class Engine logic
        end

        %% Data Stores
        classDef data fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
        Excel["Uploaded Excel\n(Movimentação sheet)"] 
        class Excel data
        CSV_A{"Static CSV – Ações"} 
        class CSV_A data
        CSV_F{"Static CSV – FIIs"} 
        class CSV_F data
    end

    %% Dependencies Manifest
    Requirements["requirements.txt"]
    click Requirements "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/requirements.txt"

    %% Click Events
    click UI "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/calculator.py"
    click Engine "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/calculator.py"
    click CSV_A "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/data/CNPJs_ACOES.csv"
    click CSV_F "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/data/CNPJs_FII.csv"
    click DevContainer "https://github.com/igor-ferreira-bezerra/average-price-ir-calculator/blob/main/.devcontainer/devcontainer.json"

    %% Connections
    User -->|"Upload Excel & input year"| UI
    UI -->|"trigger preprocessing & calc"| Engine
    Engine -->|"Pandas.read_excel"| Excel
    Engine -->|"Pandas.read_csv & merge"| CSV_A
    Engine -->|"Pandas.read_csv & merge"| CSV_F
    Engine -->|"render result tables"| UI

    %% Styles
    class DevContainer,Requirements env
    class UI ui
    class Engine logic
    class Excel,CSV_A,CSV_F data
```
