# convexfi/intradaymodel architecture

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

- Interactive diagram: https://gitdiagram.com/convexfi/intradaymodel
- Repository: https://github.com/convexfi/intradaymodel

## Overview

##### Project type and purpose
- Type: An R library/package (open-source analytical tool).
- Purpose: Provide univariate state-space models (Kalman filter) for modeling and forecasting intraday trading volume, with plotting and decomposition utilities.

##### File structure
Top-level components:
- Package Metadata & Build
– DESCRIPTION, NAMESPACE, LICENSE, NEWS.md, .Rbuildignore, .gitignore, cran-comments.md
- Source Code
– R/ (auxiliary_kalman.R, fit.R, decompose, plot, use_model, volume_xxx)
- Data
– data/ (stored sample .rda datasets)
– R_buildignore/ (development data, scripts, example datasets)
- Documentation
– man/ (Rd files and man/figures)
– vignettes/ (Rmd, html, bibliography, styles)
– README.Rmd, README.md/html
– inst/CITATION
- Testing
– tests/testthat (unit tests & fixtures)
– tests/testthat.R

##### Extract insights from README
- Packages functions: fit_volume, decompose_volume, forecast_volume, generate_plots.
- Dependencies: base R, testthat, likely stats or KF packages.

##### Main components
a. Core Modules (in R/):
– Auxiliary (state-space routines)
– Model Fitting (fit_volume)
– Decomposition/Analysis (decompose_volume)
– Forecasting (forecast_volume)
– Plotting (generate_plots)
– User API (use_model)
b. Data Stores:
– Input datasets (data/volume_*.rda)
– Internal development datasets (R_buildignore)
– Test fixtures (tests/testthat/fixtures)
c. Documentation & Packaging Layers:
– Documentation generator (roxygen → man/*.Rd)
– Vignettes (vignettes/)
– Metadata (DESCRIPTION, NAMESPACE)
d. Testing Framework:
– testthat suite
– Fixtures feeding unit tests
e. R Environment & CRAN/GitHub
– R session executes package
– devtools/R CMD build & check
– CRAN/GitHub host

##### Relationships & interactions
- From fit module → outputs model object → goes to decompose and forecast modules.
- Decompose/forecast modules → produce results → pass to plotting module.
- Packaging flow: source tree → R CMD build/check → tarball → CRAN.

##### Architectural patterns & design principles
- Modular layering: separation between model logic (state-space), I/O (data loading), API (user-facing functions), visualization, and testing.
- Single Responsibility: each R script handles one aspect (fit, decompose, plot).
- Data abstraction: using .rda datasets to decouple code from I/O format.

##### Final checklist
– Have you shown all R/ functions as distinct components?
– Did you represent data sources and test fixtures?
– Are packaging and documentation flows explicit?
– Are dependencies (R session, devtools, CRAN) noted?

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Environment
    User["User Script / R Console"]:::external
    RSession["R Session"]:::external
    User -->|loads package| RSession

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        API["User API\n(use_model)"]:::code
        Auxiliary["Auxiliary Routines\n(auxiliary_kalman.R,\nauxiliary_tools.R)"]:::code
        Fit["Model Fitting\n(fit.R)"]:::code
        Decomp["Decomposition\n(decompose_volume)"]:::code
        Forecast["Forecasting\n(forecast_volume)"]:::code
        Plot["Plotting\n(generate_plots)"]:::code
    end

    RSession --> API
    API --> Fit
    Fit --> Decomp
    Fit --> Forecast
    Decomp --> Plot
    Forecast --> Plot

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Data["Packaged Sample Data\n(volume_*.rda)"]:::data
        DevData["Dev/Raw Data\n(R_buildignore/*.rda)"]:::data
    end

    Data --> Fit
    Data --> API
    DevData --> Fit

    %% Testing Framework
    subgraph "Testing Framework"
        direction TB
        TestEntry["Test Suite\n(tests/testthat.R)"]:::test
        UnitTests["Unit Tests\n(test-*.R)"]:::test
        Fixtures["Fixtures\n(tests/testthat/fixtures)"]:::test
    end

    TestEntry --> UnitTests
    Fixtures --> UnitTests
    UnitTests --> API
    UnitTests --> Fit
    UnitTests --> Auxiliary

    %% Documentation
    subgraph "Documentation"
        direction TB
        Rd["Rd Help Pages\n(man/*.Rd)"]:::docs
        Vignettes["Vignettes & Guides\n(vignettes/)"]:::docs
        Readme["README & Citation\n(README*, inst/CITATION)"]:::docs
    end

    API --> Rd
    Fit --> Rd
    Decomp --> Rd
    Forecast --> Rd
    Plot --> Rd
    Vignettes --> Rd

    %% Packaging & Metadata
    subgraph "Packaging & Build"
        direction TB
        Metadata["Metadata & Build Files\n(DESCRIPTION, NAMESPACE,\nLICENSE, NEWS.md, etc)"]:::docs
        Build["devtools/R CMD build & check"]:::external
        Repo["CRAN/GitHub"]:::external
    end

    Metadata --> Build
    Rd --> Build
    Vignettes --> Build
    Build --> Repo

    %% Legend (implicit via classDef)

    %% Click Events
    click Auxiliary "https://github.com/convexfi/intradaymodel/blob/master/R/auxiliary_kalman.R"
    click Auxiliary "https://github.com/convexfi/intradaymodel/blob/master/R/auxiliary_tools.R"
    click Fit "https://github.com/convexfi/intradaymodel/blob/master/R/fit.R"
    click Decomp "https://github.com/convexfi/intradaymodel/blob/master/man/decompose_volume.Rd"
    click Forecast "https://github.com/convexfi/intradaymodel/blob/master/man/forecast_volume.Rd"
    click Plot "https://github.com/convexfi/intradaymodel/blob/master/R/plot.R"
    click API "https://github.com/convexfi/intradaymodel/blob/master/R/use_model.R"
    click Data "https://github.com/convexfi/intradaymodel/blob/master/data/volume_aapl.rda"
    click Data "https://github.com/convexfi/intradaymodel/blob/master/data/volume_fdx.rda"
    click DevData "https://github.com/convexfi/intradaymodel/blob/master/R_buildignore/AAPL_volume_xts.rda"
    click DevData "https://github.com/convexfi/intradaymodel/blob/master/R_buildignore/GE_volume.rda"
    click DevData "https://github.com/convexfi/intradaymodel/blob/master/R_buildignore/GE_volume_xts.rda"
    click DevData "https://github.com/convexfi/intradaymodel/blob/master/R_buildignore/modelSpec_format.rda"
    click Metadata "https://github.com/convexfi/intradaymodel/tree/master/DESCRIPTION"
    click Rd "https://github.com/convexfi/intradaymodel/blob/master/man/intradayModel-package.Rd"
    click Vignettes "https://github.com/convexfi/intradaymodel/blob/master/vignettes/intradayModel.Rmd"
    click Readme "https://github.com/convexfi/intradaymodel/blob/master/README.md"
    click Readme "https://github.com/convexfi/intradaymodel/tree/master/inst/CITATION"
    click TestEntry "https://github.com/convexfi/intradaymodel/blob/master/tests/testthat.R"
    click UnitTests "https://github.com/convexfi/intradaymodel/blob/master/tests/testthat/test-auxiliary.R"
    click Fixtures "https://github.com/convexfi/intradaymodel/blob/master/tests/testthat/fixtures/ACN_volume.rda"
    click Repo "https://github.com/convexfi/intradaymodel/blob/master/intradayModeling.Rproj"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef test fill:#FFA500,stroke:#000,stroke-width:1px
    classDef docs fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
