# marketcalls/openadvisor architecture

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

- Interactive diagram: https://gitdiagram.com/marketcalls/openadvisor
- Repository: https://github.com/marketcalls/openadvisor

## Overview

##### Project type and purpose
- OpenAdvisor is a full-stack, self-hostable investment platform.
- Backend: Flask REST-style web app (Python) serving HTML templates and JSON endpoints.
- Frontend: Jinja2 templates + Tailwind CSS/Daisy UI + Alpine.js.
- ML pipeline: CatBoost models trained on stock data, scheduled tasks for data download, training, and predictions.
- Database: SQLite via SQLAlchemy.
- External services: Yahoo Finance (via yfinance), Amazon SES (email).

##### File structure
Top-level components:
- app.py, config.py, extensions.py – initializes Flask app, loads config, registers extensions (DB, mail, scheduler).
- routes/ – Flask Blueprints for auth, dashboard, predictions, charts, backtest, core.
- models.py, forms.py – data layer and form definitions (MVC pattern).
- templates/, static/ – UI layer (HTML, CSS, JS, images).
- data_downloader.py, training_predictions.py – standalone scripts for scheduled tasks (AP Scheduler).
- catboost_info/, Notebook/ – trained model artifacts and experimental notebooks.
- predictions/ – CSV outputs consumed by the app.
- portfolio.csv – seed data for backtesting.
- requirements.txt – dependency manifest.

##### Key README insights
- AP Scheduler is used to automate daily data downloads and weekly trainings/predictions.
- ML stack: yfinance → raw data → CatBoost training → catboost_info (model + logs) → predictions CSV.
- User flows: register/login → set preferences → view dashboard & charts → run backtest → receive email alerts.

##### Main components
A. Client layer
– Web Browser (HTML/CSS/JS)
- Alpine.js components
- Tailwind CSS / Daisy UI styling
B. Web Server layer (Flask app)
– Blueprints (auth, core, dashboard, charts, backtest, predictions)
– Controllers (routes/*.py)
– View layer (templates/*.html)
– Forms (forms.py)
– Business logic & services (extensions.py, config.py)
C. Data layer
– SQLite database (SQLAlchemy ORM via models.py)
– CSV file store (predictions/, portfolio.csv)
– Model artifacts (catboost_info/)
D. ML pipeline & scheduler
– AP Scheduler (embedded in Flask or standalone)
- data_downloader.py (daily job)
- training_predictions.py (weekly job)
– yfinance (data source)
– CatBoost (training & prediction engine)
E. External services
– Yahoo Finance API (via yfinance)
– Amazon SES (email notifications)

##### Relationships & data flows
1. User → Browser → HTTP(S) → Flask app
2. Flask controllers ↔ Database (read/write user & portfolio data)
3. ML scheduler → yfinance → raw data → CatBoost train → model artifacts → predictions CSV
4. Flask job readers → predictions CSV → incorporate into dashboard & charts
5. Email service invoked by Flask (e.g., on registration, alerts) via Amazon SES

##### Architectural patterns & design principles
- MVC (models.py, forms.py, templates, routes)
- Layered architecture (presentation, application, domain, infrastructure)
- Modularization with Flask Blueprints
- Batch processing & scheduled tasks for ML
- Single-file database (SQLite) for ease of self-hosting
- External integration patterns (data ingestion, email)

##### Detailed breakdown
- Presentation Layer: Browser → Static (styles.css, charts.js) + Templates → routes core/dashboard
- Application Layer: Flask app.py → extensions (DB, Mail, Scheduler) → route handlers
- Domain Layer: models.py (User, Portfolio, Prediction), forms.py (Auth, Settings)
- ML Subsystem:
– DataDownloader (daily) → yfinance → raw_data.csv
– Trainer (weekly) → CatBoost → model.bin (catboost_info/)
– Predictor → predictions/*.csv
- Infrastructure Layer: SQLite DB file, CSV file store, environment config (.env)
- External Services: Yahoo Finance API, Amazon SES

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web Browser\n(Alpine.js, Tailwind CSS/Daisy UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Server["Flask Web Server"]:::backend
        Config["Configuration & Env"]:::backend
        Ext["Extensions\n(DB, Mail, Scheduler)"]:::backend

        subgraph "Flask Blueprints (Controllers)"
            Auth["Auth Blueprint"]:::backend
            Core["Core Blueprint"]:::backend
            Dashboard["Dashboard Blueprint"]:::backend
            Charts["Charts Blueprint"]:::backend
            Backtest["Backtest Blueprint"]:::backend
            PredictionsCtrl["Predictions Blueprint"]:::backend
        end

        Models["Domain Models"]:::backend
        Forms["Forms Definitions"]:::backend
        Templates["Templates"]:::frontend
        EmailTemplate["Email Template"]:::frontend
        Styles["static/styles.css"]:::frontend
        ChartsJS["static/charts.js"]:::frontend
        ThemeJS["static/theme.js"]:::frontend
        Images["static/images/"]:::frontend
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["SQLite Database\n(SQLAlchemy)"]:::datastore
        PredictionsCSV["predictions/"]:::datastore
        PortfolioCSV["portfolio.csv"]:::datastore
        Artifacts["Model Artifacts\n(catboost_info/)"]:::datastore
    end

    %% ML Pipeline & Scheduler
    subgraph "ML Pipeline & Scheduler"
        Scheduler["AP Scheduler"]:::backend
        Downloader["Data Downloader\n(daily)"]:::backend
        Trainer["Trainer & Predictor\n(weekly)"]:::backend
        Yahoo["Yahoo Finance API"]:::external
        CatBoost["CatBoost Engine"]:::backend
    end

    %% External Services
    subgraph "External Services"
        SES["Amazon SES"]:::external
    end

    %% Connections
    Browser -->|HTTP GET/POST| Server
    Server -->|loads| Config
    Server -->|initializes| Ext
    Ext -->|registers| Scheduler
    Server -->|registers blueprints| Auth
    Server --> Auth
    Server --> Core
    Server --> Dashboard
    Server --> Charts
    Server --> Backtest
    Server --> PredictionsCtrl
    Server -->|uses| Models
    Server -->|uses| Forms
    Server -->|renders| Templates
    Server -->|sends email via| SES
    Server -->|serves static| Styles
    Server --> Styles
    Server --> ChartsJS
    Server --> ThemeJS
    Server --> Images

    Scheduler -->|triggers daily| Downloader
    Scheduler -->|triggers weekly| Trainer
    Downloader -->|fetches data| Yahoo
    Downloader -->|outputs raw_data.csv| PredictionsCSV
    Trainer -->|uses raw_data.csv| PredictionsCSV
    Trainer -->|trains model| CatBoost
    Trainer -->|saves artifacts| Artifacts
    Trainer -->|generates| PredictionsCSV
    Server -->|reads predictions| PredictionsCSV
    Server -->|reads artifacts| Artifacts
    Server -->|queries| DB
    Server -->|reads| PortfolioCSV

    %% Click Events
    click Server "https://github.com/marketcalls/openadvisor/blob/main/app.py"
    click Config "https://github.com/marketcalls/openadvisor/blob/main/config.py"
    click Ext "https://github.com/marketcalls/openadvisor/blob/main/extensions.py"
    click Auth "https://github.com/marketcalls/openadvisor/blob/main/routes/auth.py"
    click Core "https://github.com/marketcalls/openadvisor/blob/main/routes/core.py"
    click Dashboard "https://github.com/marketcalls/openadvisor/blob/main/routes/dashboard.py"
    click Charts "https://github.com/marketcalls/openadvisor/blob/main/routes/charts.py"
    click Backtest "https://github.com/marketcalls/openadvisor/blob/main/routes/backtest.py"
    click PredictionsCtrl "https://github.com/marketcalls/openadvisor/blob/main/routes/predictions.py"
    click Models "https://github.com/marketcalls/openadvisor/blob/main/models.py"
    click Forms "https://github.com/marketcalls/openadvisor/blob/main/forms.py"
    click Templates "https://github.com/marketcalls/openadvisor/tree/main/templates/"
    click EmailTemplate "https://github.com/marketcalls/openadvisor/blob/main/templates/email/welcome.html"
    click Styles "https://github.com/marketcalls/openadvisor/blob/main/static/styles.css"
    click ChartsJS "https://github.com/marketcalls/openadvisor/blob/main/static/charts.js"
    click ThemeJS "https://github.com/marketcalls/openadvisor/blob/main/static/theme.js"
    click Images "https://github.com/marketcalls/openadvisor/tree/main/static/images/"
    click PredictionsCSV "https://github.com/marketcalls/openadvisor/tree/main/predictions/"
    click PortfolioCSV "https://github.com/marketcalls/openadvisor/blob/main/portfolio.csv"
    click Artifacts "https://github.com/marketcalls/openadvisor/tree/main/catboost_info/"
    click Downloader "https://github.com/marketcalls/openadvisor/blob/main/data_downloader.py"
    click Trainer "https://github.com/marketcalls/openadvisor/blob/main/training/training_predictions.py"
    click Requirements "https://github.com/marketcalls/openadvisor/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0050B3,color:#000
    classDef backend fill:#DFF7D0,stroke:#237A00,color:#000
    classDef datastore fill:#FFE7C0,stroke:#B36A00,color:#000
    classDef external fill:#E7D0FF,stroke:#5C00B3,color:#000
```
