# gg-martins091/fundamentaldata-cli architecture

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

- Interactive diagram: https://gitdiagram.com/gg-martins091/fundamentaldata-cli
- Repository: https://github.com/gg-martins091/fundamentaldata-cli

## Overview

##### Project Overview and Purpose
- This project is a CLI tool designed to access fundamental data on Brazilian stocks (earnings, P/E ratio, etc.). It fetches data via the dadosdemercado.com.br API and stores responses/caches queries in a local PostgreSQL database.
- Although “incomplete yet functional,” the project has a defined modular structure covering data retrieval, data processing/plotting, and utility services (e.g., database interactions, HTTP communication, logging).

##### Key Components
a. CLI Entry and Command Processing:
- The entry point is main.py, which likely routes user commands to different modules.
- CLI as the “User Interface / CLI Layer.”

b. Modules:
- The “modules” directory is subdivided into:
- getinfos: Handles retrieval of fundamental data from the external API.
- loadcompanies: Likely responsible for loading or processing company data (perhaps to seed the database).
- plots: Contains several modules (balance, cashflow, gringos, income, marketratio, ratio) for generating visualizations or further analysis based on downloaded data.
- As functional blocks that the CLI interacts with for specified command execution.

c. Type Definitions:
- The “mytypes” folder is used to define type models (indicators and custom types). Represent this as a shared module for data structures employed across various business logics.

d. Services:
- The “services” directory includes:
- http.py: Likely used to manage API calls.
- pg.py: Used for PostgreSQL database interactions.
- log.py: Manages logging functionalities.
- utils.py: Miscellaneous utility functions.
- These support modules and may be invoked by various parts of the code base to ensure separation of concerns.

e. Database:
- The script.sql file and docker-compose.yml indicate that a PostgreSQL database is used.
- Local PostgreSQL DB as an external component, with the pg service interacting with it.

##### Relationships and Interactions
- The CLI (main.py) channels user commands to relevant modules. For example:
User Command → CLI (main.py) → Appropriate module (e.g., getinfos or loadcompanies) → Further processing (e.g., plotting via the plots modules).
- Modules (especially getinfos) interact with http services to fetch data from the external API.
- After retrieval, data may be passed to the services layer (via pg.py) to cache into the PostgreSQL database.
- The modules that handle plotting use gathered data (and calculations based on type models from mytypes) to generate visual representations.

##### Architectural Patterns and Technologies
- The project’s structure shows a clear separation between:
- User Interface/CLI – entry point via main.py.
- Business logic – implemented in modular subcomponents in the modules and mytypes directories.
- Infrastructure services – encapsulated in the services directory (HTTP calls, database access, logging).
- Technologies/Frameworks include:
- Python as the primary coding language.
- PostgreSQL as the database.
- External integration with dadosdemercado.com.br via custom HTTP interactions.
- Docker Compose (docker-compose.yml) suggests containerized or reproducible environments.

- That each component is clearly labeled (e.g., “CLI (main.py)”, “Get Infos Module”, “Load Companies Module”, “Plots Module”, “HTTP Service”, “PostgreSQL DB”, etc.).
- Annotating key interactions like “API Call”, “Data Caching”, and “Logging” between components.
- If applicable, show the Docker environment via docker-compose.yml as an outer layer encompassing the PostgreSQL container and possibly the application container.

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% User Interface / CLI Layer
  subgraph "User Interface / CLI Layer"
    CLI["CLI (main.py)"]:::cli
  end

  %% Business Logic Modules
  subgraph "Business Logic Modules"
    GETINFOS["Get Infos Module"]:::modules
    LOADCOMPANIES["Load Companies Module"]:::modules
    PLOTS["Plots Module"]:::modules
    MYTYPES["MyTypes Module"]:::modules

    subgraph "Plots Details"
      BALANCE["Balance Plot (balance.py)"]:::modules
      CASHFLOW["Cashflow Plot (cashflow.py)"]:::modules
      GRINGOS["Gringos Plot (gringos.py)"]:::modules
      INCOME["Income Plot (income.py)"]:::modules
      MARKETRATIO["Market Ratio Plot (marketratio.py)"]:::modules
      RATIO["Ratio Plot (ratio.py)"]:::modules
    end

    subgraph "Type Definitions"
      INDICATORS["Indicators (indicators.py)"]:::modules
      MYTYPESDEFS["MyTypes Definitions (mytypes/mytypes.py)"]:::modules
    end
  end

  %% Infrastructure Services
  subgraph "Infrastructure Services"
    HTTP["HTTP Service (http.py)"]:::services
    PG["Database Service (pg.py)"]:::services
    LOG["Logging Service (log.py)"]:::services
    UTILS["Utility Functions (utils.py)"]:::services
  end

  %% External Systems
  subgraph "External Systems"
    API["External API"]:::external
    DB["PostgreSQL DB"]:::external
  end

  %% Connections from CLI to Modules
  CLI -->|"cmd"| GETINFOS
  CLI -->|"cmd"| LOADCOMPANIES
  CLI -->|"cmd"| PLOTS
  CLI -->|"cmd"| MYTYPES

  %% Module to Service interactions
  GETINFOS -->|"api_call"| HTTP
  GETINFOS -->|"cache_data"| PG
  GETINFOS -->|"log"| LOG

  LOADCOMPANIES -->|"db_interaction"| PG
  LOADCOMPANIES -->|"log"| LOG

  PLOTS -->|"data_fetch"| PG
  PLOTS -->|"use_types"| MYTYPESDEFS
  PLOTS -->|"log"| LOG

  %% Service to External Systems
  HTTP -->|"fetch"| API
  PG -->|"query"| DB

  %% Click Events
  click CLI "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/main.py"
  click GETINFOS "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/getinfos/getinfos.py"
  click LOADCOMPANIES "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/loadcompanies/loadcompanies.py"
  click PLOTS "https://github.com/gg-martins091/fundamentaldata-cli/tree/master/modules/plots"
  click BALANCE "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/balance.py"
  click CASHFLOW "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/cashflow.py"
  click GRINGOS "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/gringos.py"
  click INCOME "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/income.py"
  click MARKETRATIO "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/marketratio.py"
  click RATIO "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/modules/plots/ratio.py"
  click INDICATORS "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/mytypes/indicators.py"
  click MYTYPESDEFS "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/mytypes/mytypes.py"
  click HTTP "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/services/http.py"
  click PG "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/services/pg.py"
  click LOG "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/services/log.py"
  click UTILS "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/services/utils.py"
  click DB "https://github.com/gg-martins091/fundamentaldata-cli/blob/master/script.sql"

  %% Styles
  classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
  classDef modules fill:#90EE90,stroke:#000,stroke-width:1px;
  classDef services fill:#FFFF99,stroke:#000,stroke-width:1px;
  classDef external fill:#F08080,stroke:#000,stroke-width:1px;
```
