# nnamdi-sys/finalytics architecture

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

- Interactive diagram: https://gitdiagram.com/nnamdi-sys/finalytics
- Repository: https://github.com/nnamdi-sys/finalytics

## Overview

##### Project Type and Purpose
- Finalytics is a multi‐language mono­repo centered on a Rust core library for financial data retrieval, security analysis, and portfolio optimization.
- It provides:
- A Rust crate (`rust/`) implementing analytics (fundamentals, performance, optimization, etc.), data models, charting, and reporting modules.
- A Python binding (`python/`) via Rust FFI, exposing the same functionality to Python users.
- A sample web application (`web/`) built in Rust, rendering dashboards for tickers and portfolios.
- CI/CD workflows (GitHub Actions) and containerization (Docker + Fly.io) are included for building, testing, and deployment.

##### File Structure Analysis
- Top level:
- Cargo.toml, Cargo.lock – root Rust project metadata
- python/ – Python wrapper (pyproject.toml, Rust FFI code, documentation)
- rust/ – core library source (`src/analytics/`, `src/data/`, `src/models/`, `src/charts/`, `src/reports/`, `src/utils/`)
- web/ – web server application (router, components, templates)
- .github/workflows – CI pipelines for Python and Rust
- Dockerfile + fly.toml – container build and Fly.io deployment config
- Patterns:
- Modular Rust library following feature domains (analytics, data, charts, reports, utils)
- FFI layer linking Rust library to Python
- Web server using MVC‐like routing + templates

##### README Insights
- Core functionality: building Tickers, generating reports (performance, financials, options, news), portfolio optimization.
- Python usage mirrors Rust API.
- Sample web dashboards (Ticker Dashboard, Portfolio Dashboard) hosted at finalytics.rs.
- Deployment target: Fly.io container.

##### Detailed Capture of Architectural Elements
- Python process invoking FFI functions.
- Web server routing layer calling core library.
- External data source (e.g., “Yahoo Finance API”) as a separate entity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rust Core Library
    subgraph "Rust Core Library"
        direction TB
        Analytics["Analytics"]:::core
        Data["Data Ingestion"]:::core
        Models["Models"]:::core
        Charts["Charting"]:::core
        Reports["Reporting"]:::core
        Utils["Utilities"]:::core
    end

    %% Python Binding Layer
    subgraph "Python Binding Layer"
        direction TB
        FFI["FFI Interface"]:::interface
        Lib["Library Entry"]:::interface
        TickersAPI["Tickers API"]:::interface
        TickerAPI["Ticker API"]:::interface
        PortfolioAPI["Portfolio API"]:::interface
    end

    %% Python CLI
    CLI["Python CLI"]:::interface

    %% Web Application
    subgraph "Web Application"
        direction TB
        WebUI["Web UI"]:::interface
        Main["Server Entrypoint"]:::interface
        Router["Routing Layer"]:::interface
        Components["UI Components"]:::interface
        Templates["HTML Templates"]:::interface
    end

    %% External Services
    External["Yahoo Finance API"]:::external

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        Workflows["GitHub Actions"]:::cicd
        Docker["Docker"]:::cicd
        Flyio["Fly.io"]:::cicd
    end

    %% Directions and Data Flow
    CLI -->|uses| FFI
    FFI -->|calls| Analytics
    Lib -->|binds| Analytics
    TickersAPI -->|binds| Analytics
    TickerAPI -->|binds| Analytics
    PortfolioAPI -->|binds| Analytics

    WebUI -->|renders| Templates
    Main -->|routes to| Router
    Router -->|invokes| Data
    Data -->|fetches| External
    External -->|returns data| Data
    Data -->|supplies| Analytics
    Analytics -->|computes metrics| Reports
    Reports -->|generates reports| Templates
    Templates -->|display| WebUI
    Router -->|calls| Analytics

    Workflows -->|tests| Analytics
    Workflows -->|tests| FFI
    Workflows -->|builds image| Docker
    Docker -->|deploys| Flyio

    %% Click Events
    click Analytics "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/analytics/"
    click Data "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/data/"
    click Models "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/models/"
    click Charts "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/charts/"
    click Reports "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/reports/"
    click Utils "https://github.com/nnamdi-sys/finalytics/tree/main/rust/src/utils/"
    click FFI "https://github.com/nnamdi-sys/finalytics/blob/main/python/src/ffi.rs"
    click Lib "https://github.com/nnamdi-sys/finalytics/blob/main/python/src/lib.rs"
    click TickersAPI "https://github.com/nnamdi-sys/finalytics/blob/main/python/src/tickers.rs"
    click TickerAPI "https://github.com/nnamdi-sys/finalytics/blob/main/python/src/ticker.rs"
    click PortfolioAPI "https://github.com/nnamdi-sys/finalytics/blob/main/python/src/portfolio.rs"
    click CLI "https://github.com/nnamdi-sys/finalytics/blob/main/python/pyproject.toml"
    click Main "https://github.com/nnamdi-sys/finalytics/blob/main/web/src/main.rs"
    click Router "https://github.com/nnamdi-sys/finalytics/tree/main/web/src/router/"
    click Components "https://github.com/nnamdi-sys/finalytics/tree/main/web/src/components/"
    click Templates "https://github.com/nnamdi-sys/finalytics/tree/main/web/src/templates/"
    click Workflows "https://github.com/nnamdi-sys/finalytics/blob/main/ .github/workflows/rust.yml"
    click Workflows "https://github.com/nnamdi-sys/finalytics/blob/main/ .github/workflows/python.yml"
    click Docker "https://github.com/nnamdi-sys/finalytics/tree/main/Dockerfile"
    click Flyio "https://github.com/nnamdi-sys/finalytics/blob/main/fly.toml"

    %% Styles
    classDef core fill:#add8e6,stroke:#000
    classDef interface fill:#90ee90,stroke:#000
    classDef external fill:#ffa500,stroke:#000
    classDef cicd fill:#d3d3d3,stroke:#000
```
