Skip to content

Latest commit

 

History

History
364 lines (294 loc) · 17.4 KB

README.md

File metadata and controls

364 lines (294 loc) · 17.4 KB

Project logo

OptiVest

Status GitHub Issues GitHub Pull Requests License

Optivest [Back-End]: This is the backend sister project of OptiVest Project. To Check out the Frontend, go here

📝 Table of Contents

🧐 About

The OptiVest project is a cutting-edge, AI-driven personal financial advisor platform designed to empower users with smarter financial management tools. Built with a focus on automation and real-time data insights, OptiVest combines dynamic portfolio analysis, personalized investment recommendations, and a suite of tools for budgeting, goal setting, and debt tracking. The backend, developed in Go, integrates financial data from sources like Alpha Vantage and FRED to provide up-to-date insights and robust portfolio optimization.

A standout feature of OptiVest is its focus on actionable financial insights. Users receive real-time portfolio alerts, performance metrics, and risk management tips, helping them make well-informed decisions. The platform’s intelligent algorithms highlight top-performing assets and assist in sector diversification, while additional tools for budgeting and debt tracking offer a holistic approach to personal finance. By merging AI-driven recommendations with user-centric design, OptiVest delivers an all-in-one financial advisory experience tailored to individual financial goals and preferences.

✨ Features

  1. AI-Driven Financial Insights
  • Provides intelligent financial advice using pre-trained AI models, enabling users to make data-backed investment decisions.
  • Customizable recommendations on portfolio rebalancing, risk management, and asset allocation.
  1. Real-Time Portfolio Analysis
  • Integrates with Alpha Vantage and FRED for up-to-date data, delivering real-time analysis of investments, market trends, and external factors like interest rates and market sentiment.
  • Calculates key performance metrics such as ROI, Sharpe ratio, and sector performance.
  1. Automated Portfolio Management
  • Supports automated portfolio rebalancing based on individual risk tolerance and investment goals.
  • Uses advanced algorithms to identify top-performing stocks and bonds, updating recommendations regularly.
  1. Personal Finance Tools
  • Budgeting and Goal Setting: Tracks spending, monitors goals, and provides summaries for financial planning.
  • Debt Management: Analyzes debt information, including payment history, interest rates, and payoff estimates, and visualizes debt progress.
  1. Notification Center
  • Real-time notifications for market updates, investment alerts, and goal progress. In Progress
  • Allows users to view messages with detailed metadata, including links and images, for quick navigation.
  1. Advanced Security and Integration
  • Secure WebSocket connection for real-time updates and data handling.
  • Implements Redis caching for efficient data retrieval, reducing load on API calls and improving performance.
  1. Prediction Capability
  • Based on your spending, expense, income and debt rates, OptiVest is able to come up with predictions of future habits using the OptiVest Predictor Micr-Service.

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

Before you can run or contribute to this project, you'll need to have the following software installed:

  • Go: The project is written in Go, so you'll need to have Go installed to run or modify the code.
  • PostgreSQL: The project uses a PostgreSQL database, so you'll need to have PostgreSQL installed and know how to create a database.
  • A Go IDE or text editor: While not strictly necessary, a Go IDE or a text editor with Go support can make it easier to work with the code. I use vscode.
  • Git: You'll need Git to clone the repo.
  • Redis: OptiVest uses Redis for caching to enhance performance and reduce API load.
  • OptiVest-Predictor-Microservice: Clone and set up this micro-service, which is esential for financial predictions and recommendations

Installing

A step by step series of examples that tell you how to get a development env running.

  1. Clone the repository: Start by cloning the repository to your local machine. Open a terminal, navigate to the directory where you want to clone the repository, and run the following command:

    git clone https://github.com/Blue-Davinci/OptiVest.git

  2. Navigate to the project directory: Use the cd command to navigate to the project directory:

    cd optivest

  3. Install the Go dependencies: The Go tools will automatically download and install the dependencies listed in the go.mod file when you build or run the project. To download the dependencies without building or running the project, you can use the go mod download command:

    go mod download

  4. Set up the database: The project uses a PostgreSQL database. You'll need to create a new database and update the connection string in your configuration file or environment variables. We use GOOSE for all the data migrations and SQLC as the abstraction layer for the DB. To proceed with the migration, navigate to the Schema director:

cd internal\sql\schema
  • Then proceed by using the goose {connection string} up to execute an Up migration as shown:
  • Note: You can use your own environment variable or load it from the env file.
goose postgres postgres://aggregate:password@localhost/aggregate  up

  1. Download and Setup the MIcroService: Follow the instructions highlighted here to get the micro-service up and running.

  2. Environment Variable Setups: OptiVest uses a few external APIs. You will need to set them up and make an .env containing the following templates:

# DSN Link to our Postgres database
OPTIVEST_DB_DSN=postgres://optivest:yourpassword@localhost/optivest?sslmode=disable
# For deployment: , comment the above and uncomment the below DSN
#OPTIVEST_DB_DSN=postgres://optivest:yourpassword@host.docker.internal/optivest?sslmode=disable
OPTIVEST_DATA_ENCRYPTION_KEY=xxxxxxx

# Mailer configuration
OPTIVEST_SMTP_HOST=xxxxx
OPTIVEST_SMTP_USERNAME=xxxxxx
OPTIVEST_SMTP_PASSWORD=xxxxxxx
OPTIVEST_SMTP_SENDER=Optivest <no-reply@optivest.tech>

# Exchange Rate API
OPTIVEST_EXCHANGERATE_API_KEY=xxxxxxxxx
# Alpha Vantage API
OPTIVEST_ALPHAVANTAGE_API_KEY=xxxxxx
# Fred API
OPTIVEST_FRED_API_KEY=xxx
# Financial Modeling Prep API
OPTIVEST_FINANCIALMODELINGPREP_API_KEY=xxxxx
# Samba Nova LLM API
OPTIVEST_SAMBA_NOVA_LLM_API_KEY=xxxx
# Optivest Predictor Microservice
OPTIVEST_PREDICTOR_API_KEY=xxx
# OCR.Space API
OPTIVEST_OCRSPACE_API_KEY=xxxx

The above .env is self explanatory for each API needed

  1. Build the project: You can build the project using the makefile's command:

    make build/api

    This will create an executable file in the current directory. Note: The generated executable is for the windows environment - However, You can find the linux build command within the makefile!

  2. Run the project: You can run the project using the go run or use MakeFile and do:

    make run/api

  3. MakeFile Help: For additional supported commands run make help:

make help

output:

Usage:
run/api: Run the API server
run/api/origins: Run the API server with CORS origins
db/psql            -  connect to the db using psql
build/api          -  build the cmd/api application

Description

The application accepts command-line flags for configuration, establishes a connection pool to a database, and publishes variables for monitoring the application. The published variables include the application version, the number of active goroutines and the current Unix timestamp.

  • This will start the application. You should be able to access it at http://localhost:4000.
You can view the **parameters** by utilizing the `-help` command. Here is a rundown of the available commands for a quick lookup (INCOMPLETE, use help for full list). 
- api-author string
        API author (default "Blue_Davinci")
  -api-default-currency string
        Default currency (default "USD")
  -api-key-alphavantage string
        Alpha Vantage API key (default "NYRXRLGLWY29115K")
  -api-key-exchangerates string
        Exchange-Rate API Key (default "2bd6d65a467e533704e0a7fb")
  -api-key-fmp string
        FMP API Key (default "LtEBinivcBs2uzHNg1PHXJIRj5KsLmxJ")
  -api-key-fred string
        FRED API Key (default "1c78299c9778f33eeacf2f85261f9183")
  -api-key-ocrspace string
        OCR.Space API Key (default "K82853087188957")
  -api-key-optivestmicroservice string
        OptiVest Microservice API Key (default "xJ8u4Kz7wA9vT3gPzB2dF1mLq8N5cY6s")
  -api-key-sambanova string
        Sambanova API Key (default "4044b951-1161-4165-b025-8a7bc6f46155")
  -api-name string
        API name (default "OptiVest")
  -api-url-alphavantage string
        Alpha Vantage API URL (default "https://www.alphavantage.co/query?")
  -api-url-exchangerates string
        Exchange-Rate API URL (default "https://v6.exchangerate-api.com/v6")
  -api-url-fmp string
        FMP API URL (default "https://financialmodelingprep.com/api/v3")
  -api-url-fred string
        FRED API URL (default "https://api.stlouisfed.org/fred/series/observations?")
  -api-url-ocrspace string
        OCR.Space API URL (default "https://api.ocr.space/parse/image")
  -api-url-optivestmicroservice string
        OptiVest Microservice API URL (default "http://127.0.0.1:8000/v1/predict")
  -api-url-sambanova string
        Sambanova API URL (default "https://fast-api.snova.ai/v1/chat/completions")
  -cors-trusted-origins value
        Trusted CORS origins (space separated)
  -db-dsn string
        PostgreSQL DSN (default "postgres://optivest:pa55word@localhost/optivest?sslmode=disable")
  -db-max-idle-conns int
        PostgreSQL max idle connections (default 25)
  -db-max-idle-time string
        PostgreSQL max connection idle time (default "15m")
  -db-max-open-conns int
        PostgreSQL max open connections (default 25)
  -encryption-key string
        Encryption key (default "330d12d2eacd444bd87126221c91150a09cbaee8529a387282e1e910c8be3868")
  -env string
        Environment (development|staging|production) (default "development")
  -expired-notification-burst-limit int
        Batch Limit for Expired Notification Tracker (default 100)
  -frontend-activation-url string
        Frontend Activation URL (default "http://localhost:5173/verify?token=")
  -frontend-callback-url string
        Frontend Callback URL (default "https://adapted-healthy-monitor.ngrok-free.app/v1")
  -frontend-login-url string
        Frontend Login URL (default "http://localhost:5173/login")
  -frontend-password-reset-url string
        Frontend Password Reset URL (default "http://localhost:5173/passwordreset/password?token=")
  -frontend-url string
        Frontend URL (default "http://localhost:5173")
  -http-client-retrymax int
        HTTP client maximum retries (default 3)
  -http-client-timeout duration
        HTTP client timeout (default 10s)

Using make run, will run the API with a default connection string located in cmd\api\.env. If you're using powershell, you need to load the values otherwise you will get a cannot load env file error. Use the PS code below to load it or change the env variable:

$env:OPTIVEST_DB_DSN=(Get-Content -Path .\cmd\api\.env | Where-Object { $_ -match "OPTIVEST_DB_DSN" } | ForEach-Object { $($_.Split("=", 2)[1]) })

Alternatively, in unix systems you can make a .envrc file and load it directly in the makefile by importing like so:

include .envrc

A succesful run will output something like this:

make run/api
Running API server..
go run ./cmd/api
{"level":"info","time":"2024-1","caller":"api/main.go:374","msg":"Loading Environment Variables","path":"cmd\\api\\.env"}
{"level":"info","time":"2024-1]","caller":"api/main.go:268","msg":"Redis connection established","addr":"localhost:6379"}
{"level":"info","time":"2024-1","caller":"api/main.go:277","msg":"database connection pool established","dsn":"postgres://optivest:yourpassword@localhost/optivest?sslmode=disable"}
{"level":"info","time":"2024-1","caller":"api/helpers.go:215","msg":"currency certified, using cached currencies","currency":"USD"}
{"level":"info","time":"2024-1-2","caller":"api/main.go:337","msg":"Starting Schedulers"}
{"level":"info","time":"2024-0-2","caller":"api/schedulers.go:64","msg":"Starting the recurring expenses tracking cron job..","time":"2024-00-2"}
{"level":"info","time":"2024-1","caller":"api/schedulers.go:199","msg":"Tracking recurring expenses","time":"2024-1 EAT m=+0.533360001"}

API Endpoints 📌

A full ist is documented using swagger, but here is a quick runwdown:

  1. GET /v1/healthcheck: Checks the health of the application. Returns a 200 OK status code if the application is running correctly.

  2. POST /v1/users: Registers a new user.

  3. PUT /v1/users/activated: Activates a user.

  4. POST /v1/api/authentication: Creates an authentication token.

  5. GET /debug/vars: Provides debug variables from the expvar package.

(will be added)

🔧 Running the tests

The project has existing tests represented by files ending with the word "_test" e.g internal_helpers_test.go

Break down into end to end tests

Each test file contains a myriad of tests to run on various entities mainly functions. The test files are organized into structs of tests and their corresponding test logic.

You can run them directly from the vscode test UI. Below represents test results for the scraper:

=== RUN   Test_generateSecurityKey
=== RUN   Test_generateSecurityKey/Valid_AES-128_key_(16_bytes)
--- PASS: Test_generateSecurityKey/Valid_AES-128_key_(16_bytes) (0.00s)
=== RUN   Test_generateSecurityKey/Valid_AES-192_key_(24_bytes)
--- PASS: Test_generateSecurityKey/Valid_AES-192_key_(24_bytes) (0.00s)
=== RUN   Test_generateSecurityKey/Valid_AES-256_key_(32_bytes)
--- PASS: Test_generateSecurityKey/Valid_AES-256_key_(32_bytes) (0.00s)
=== RUN   Test_generateSecurityKey/Invalid_key_length_(0_bytes)
--- PASS: Test_generateSecurityKey/Invalid_key_length_(0_bytes) (0.00s)
=== RUN   Test_generateSecurityKey/Invalid_key_length_(-1_bytes)
--- PASS: Test_generateSecurityKey/Invalid_key_length_(-1_bytes) (0.00s)
--- PASS: Test_generateSecurityKey (0.00s)
PASS
ok      github.com/Blue-Davinci/OptiVest/internal/data  0.674s
  • All other tests follow a similar prologue.

🎈 Usage

As earlier mentioned, the api uses a myriad of flags which you can use to launch the application. An example of launching the application with your smtp server's setting includes:

make build/api ## build api using the makefile
./bin/api.exe -smtp-username=pigbearman -smtp-password=algor ## run the built api with your own values

Direct Run: 
go run main.go

🚀 Deployment

(Will Be Added Soon.)

⛏️ Built Using

✍️ Authors

See also the list of contributors who participated in this project.

🎉 Acknowledgements

  • Hat tip to anyone whose code was used
  • Inspiration

📚 References