# achillesrasquinha/bulbea architecture

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

- Interactive diagram: https://gitdiagram.com/achillesrasquinha/bulbea
- Repository: https://github.com/achillesrasquinha/bulbea

## Overview

Bulbea is a Python library for stock-market data analysis, prediction, and sentiment scoring. The documented prediction workflow loads a Share’s market data, splits it into training and test windows, fits a neural model, and predicts values for evaluation. Separate capabilities include Share plotting and export, Twitter-backed sentiment analysis, and a minimal Flask server. The graph follows documented workflows and visible imports/calls; unsampled model and sentiment internals are represented only at the module level.

Main entry points: [`bulbea/entity/share.py`](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/entity/share.py) (Share Data), [`bulbea/learn/evaluation/split.py`](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/evaluation/split.py) (Window Split), [`bulbea/learn/models/ann.py`](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/models/ann.py) (Neural Network), [`bulbea/config/app.py`](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/config/app.py) (App Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market Data"]
  node_share["Share Data<br/>[share.py]"]
  node_market_ops["Plot And Export<br/>[share.py]"]
end

subgraph group_prediction["Prediction"]
  node_split["Window Split<br/>[split.py]"]
  node_ann["Neural Network<br/>[ann.py]"]
  node_model_base["Model Base<br/>[model.py]"]
  node_evaluation["Prediction Evaluation"]
end

subgraph group_sentiment["Sentiment"]
  node_sentiment["Sentiment Scoring<br/>[sentiment.py]"]
  node_twitter_client["Twitter Client<br/>[twitter.py]"]
end

subgraph group_runtime["Runtime Support"]
  node_config["App Configuration<br/>[app.py]"]
  node_utilities["Validation Utilities<br/>[_util.py]"]
  node_cli["Command Line<br/>[cli.py]"]
  node_server["Flask Server<br/>[server.py]"]
end

node_user(("Library User"))
node_quandl["Quandl"]
node_twitter_api["Twitter API"]

node_user -->|"creates"| node_share
node_share -->|"fetches data"| node_quandl
node_user -->|"prepares data"| node_split
node_split -->|"supplies training data"| node_ann
node_user -->|"fits model"| node_ann
node_user -->|"evaluates predictions"| node_evaluation
node_user -->|"plots or saves"| node_market_ops
node_user -->|"requests score"| node_sentiment
node_sentiment -->|"uses client"| node_twitter_client
node_twitter_client -->|"authenticates with"| node_twitter_api
node_share -->|"reads API settings"| node_config
node_share -->|"validates inputs"| node_utilities
node_split -->|"validates inputs"| node_utilities
node_cli -->|"reads app settings"| node_config
node_server -->|"uses server settings"| node_config
node_ann -.->|"extends model"| node_model_base

click node_share "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/entity/share.py"
click node_market_ops "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/entity/share.py"
click node_split "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/evaluation/split.py"
click node_ann "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/models/ann.py"
click node_model_base "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/models/model.py"
click node_evaluation "https://github.com/achillesrasquinha/bulbea/tree/master/bulbea/learn/evaluation"
click node_sentiment "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/sentiment/sentiment.py"
click node_twitter_client "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/sentiment/twitter.py"
click node_config "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/config/app.py"
click node_utilities "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/_util/_util.py"
click node_cli "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/cli.py"
click node_server "https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/app/server/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_share,node_market_ops,node_user toneBlue
class node_split,node_ann,node_model_base,node_evaluation toneAmber
class node_sentiment,node_twitter_client,node_twitter_api toneMint
class node_config,node_utilities,node_cli,node_server toneRose
class node_quandl toneIndigo
```

## Components

### Market Data

- [Share Data](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/entity/share.py): `bulbea/entity/share.py`
- [Plot And Export](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/entity/share.py): `bulbea/entity/share.py`

### Prediction

- [Window Split](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/evaluation/split.py): `bulbea/learn/evaluation/split.py`
- [Neural Network](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/models/ann.py): `bulbea/learn/models/ann.py`
- [Model Base](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/models/model.py): `bulbea/learn/models/model.py`
- [Prediction Evaluation](https://github.com/achillesrasquinha/bulbea/tree/master/bulbea/learn/evaluation): `bulbea/learn/evaluation`

### Sentiment

- [Sentiment Scoring](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/sentiment/sentiment.py): `bulbea/learn/sentiment/sentiment.py`
- [Twitter Client](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/learn/sentiment/twitter.py): `bulbea/learn/sentiment/twitter.py`

### Runtime Support

- [App Configuration](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/config/app.py): `bulbea/config/app.py`
- [Validation Utilities](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/_util/_util.py): `bulbea/_util/_util.py`
- [Command Line](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/cli.py): `bulbea/cli.py`
- [Flask Server](https://github.com/achillesrasquinha/bulbea/blob/master/bulbea/app/server/server.py): `bulbea/app/server/server.py`

### Other components

- **Library User**
- **Quandl**
- **Twitter API**

## Connections

- Library User → Share Data: creates (evidence: `README.md`)
- Share Data → Quandl: fetches data (evidence: `bulbea/entity/share.py`)
- Library User → Window Split: prepares data (evidence: `README.md`)
- Window Split → Neural Network: supplies training data (evidence: `README.md`)
- Library User → Neural Network: fits model (evidence: `README.md`)
- Library User → Prediction Evaluation: evaluates predictions (evidence: `README.md`)
- Library User → Plot And Export: plots or saves (evidence: `bulbea/entity/share.py`)
- Library User → Sentiment Scoring: requests score (evidence: `README.md`)
- Sentiment Scoring → Twitter Client: uses client (evidence: `bulbea/learn/sentiment/sentiment.py`)
- Twitter Client → Twitter API: authenticates with (evidence: `bulbea/learn/sentiment/twitter.py`)
- Share Data → App Configuration: reads API settings (evidence: `bulbea/entity/share.py`)
- Share Data → Validation Utilities: validates inputs (evidence: `bulbea/entity/share.py`)
- Window Split → Validation Utilities: validates inputs (evidence: `bulbea/learn/evaluation/split.py`)
- Command Line → App Configuration: reads app settings (evidence: `bulbea/cli.py`)
- Flask Server → App Configuration: uses server settings (evidence: `bulbea/app/server/server.py`)
- Neural Network → Model Base: extends model
