{"id":22794498,"url":"https://github.com/blue-davinci/optivest","last_synced_at":"2025-04-18T23:37:25.776Z","repository":{"id":258361690,"uuid":"861660724","full_name":"Blue-Davinci/OptiVest","owner":"Blue-Davinci","description":"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 financial management.","archived":false,"fork":false,"pushed_at":"2024-12-03T18:18:55.000Z","size":561,"stargazers_count":5,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T06:42:17.923Z","etag":null,"topics":["ai","authentication-backend","automation","finance","golang","newsfeed","newsfeed-aggregator","postgresql","predictive-analytics","sse"],"latest_commit_sha":null,"homepage":"https://github.com/Blue-Davinci/OptiVest","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Blue-Davinci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-23T09:53:44.000Z","updated_at":"2025-03-20T21:39:24.000Z","dependencies_parsed_at":"2024-11-27T19:34:43.943Z","dependency_job_id":null,"html_url":"https://github.com/Blue-Davinci/OptiVest","commit_stats":null,"previous_names":["blue-davinci/optivest"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blue-Davinci%2FOptiVest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blue-Davinci%2FOptiVest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blue-Davinci%2FOptiVest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blue-Davinci%2FOptiVest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blue-Davinci","download_url":"https://codeload.github.com/Blue-Davinci/OptiVest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249565253,"owners_count":21292427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","authentication-backend","automation","finance","golang","newsfeed","newsfeed-aggregator","postgresql","predictive-analytics","sse"],"created_at":"2024-12-12T04:09:02.983Z","updated_at":"2025-04-18T23:37:25.757Z","avatar_url":"https://github.com/Blue-Davinci.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"\" rel=\"noopener\"\u003e\n \u003cimg width=200px height=190px src=\"https://i.ibb.co/hZdMWvh/optivest-cropped.png\" alt=\"Project logo\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eOptiVest\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Status](https://img.shields.io/badge/status-active-success.svg)]()\n[![GitHub Issues](https://img.shields.io/github/issues/Blue-Davinci/OptiVest.svg)](https://github.com/Blue-Davinci/OptiVest/issues)\n[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/Blue-Davinci/OptiVest.svg)](https://github.com/Blue-Davinci/OptiVest/pulls)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)\n\n\u003c/div\u003e\n\n---\n\n\u003cp align=\"center\"\u003e Optivest \u003cb\u003e[Back-End]: \u003c/b\u003e This is the backend sister project of OptiVest Project. To Check out the Frontend, go \u003ca href=\"https://github.com/Blue-Davinci/OptiVest-Frontend\"\u003ehere\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr /\u003e \n\n## 📝 Table of Contents\n\n- [About](#about)\n- [Features](#features)\n- [Getting Started](#getting_started)\n- [Endpoints](#endpoints)\n- [Deployment](#deployment)\n- [Usage](#usage)\n- [Built Using](#built_using)\n- [TODO](./TODO.md)\n- [Authors](#authors)\n- [Acknowledgments](#acknowledgement)\n\n## 🧐 About \u003ca name = \"about\"\u003e\u003c/a\u003e\n\nThe 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.\n\nA 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.\n\n## ✨ Features \u003ca name=\"features\"\u003e\u003c/a\u003e\n1. **AI-Driven Financial Insights**\n- Provides intelligent financial advice using pre-trained AI models, enabling users to make data-backed investment decisions.\n- Customizable recommendations on portfolio rebalancing, risk management, and asset allocation.\n2. **Real-Time Portfolio Analysis**\n- 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.\n- Calculates key performance metrics such as ROI, Sharpe ratio, and sector performance.\n3. **Automated Portfolio Management**\n- Supports automated portfolio rebalancing based on individual risk tolerance and investment goals.\n- Uses advanced algorithms to identify top-performing stocks and bonds, updating recommendations regularly.\n4. **Personal Finance Tools**\n- Budgeting and Goal Setting: Tracks spending, monitors goals, and provides summaries for financial planning.\n- Debt Management: Analyzes debt information, including payment history, interest rates, and payoff estimates, and visualizes debt progress.\n5. **Notification Center**\n- Real-time notifications for market updates, investment alerts, and goal progress. **In Progress**\n- Allows users to view messages with detailed metadata, including links and images, for quick navigation.\n6. **Advanced Security and Integration**\n- Secure WebSocket connection for real-time updates and data handling.\n- Implements Redis caching for efficient data retrieval, reducing load on API calls and improving performance.\n7. **Prediction Capability**\n- Based on your spending, expense, income and debt rates, OptiVest is able to come up with predictions of future habits\nusing the OptiVest Predictor Micr-Service.\n\n## 🏁 Getting Started \u003ca name = \"getting_started\"\u003e\u003c/a\u003e\n\nThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See [deployment](#deployment) for notes on how to deploy the project on a live system.\n\n### Prerequisites\n\nBefore you can run or contribute to this project, you'll need to have the following software installed:\n\n- [Go](https://golang.org/dl/): The project is written in Go, so you'll need to have Go installed to run or modify the code.\n- [PostgreSQL](https://www.postgresql.org/download/): The project uses a PostgreSQL database, so you'll need to have PostgreSQL installed and know how to create a database.\n- 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.\n- [Git](https://git-scm.com/downloads): You'll need Git to clone the repo.\n- [Redis](https://redis.io/): OptiVest uses Redis for caching to enhance performance and reduce API load.\n- [OptiVest-Predictor-Microservice](https://github.com/Blue-Davinci/OptiVest_Finance_Predictor_Micro_Service_V1): Clone and set up this micro-service, which is esential for financial predictions and recommendations\n\n\n### Installing\n\nA step by step series of examples that tell you how to get a development env running.\n\n1. **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:\n    ```bash\n    git clone https://github.com/Blue-Davinci/OptiVest.git\n    ```\n2. **Navigate to the project directory:** Use the `cd` command to navigate to the project directory:\n\n    ```bash\n    cd optivest\n    ```\n3. **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:\n\n    ```bash\n    go mod download\n    ```\n4. **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.\nWe use `GOOSE` for all the data migrations and `SQLC` as the abstraction layer for the DB. To proceed\nwith the migration, navigate to the `Schema` director:\n```bash\ncd internal\\sql\\schema\n```\n- Then proceed by using the `goose {connection string} up` to execute an \u003cb\u003eUp migration\u003c/b\u003e as shown:\n- \u003cb\u003eNote:\u003c/b\u003e You can use your own environment variable or load it from the env file.\n\n```bash\ngoose postgres postgres://aggregate:password@localhost/aggregate  up\n```\n\n5. **Download and Setup the MIcroService:** Follow the instructions highlighted [here](https://github.com/Blue-Davinci/OptiVest_Finance_Predictor_Micro_Service_V1) to get the micro-service up and running.\n\n6. **Environment Variable Setups:** OptiVest uses a few external APIs. You will need to set them up and make an `.env` containing the following templates:\n```bash\n# DSN Link to our Postgres database\nOPTIVEST_DB_DSN=postgres://optivest:yourpassword@localhost/optivest?sslmode=disable\n# For deployment: , comment the above and uncomment the below DSN\n#OPTIVEST_DB_DSN=postgres://optivest:yourpassword@host.docker.internal/optivest?sslmode=disable\nOPTIVEST_DATA_ENCRYPTION_KEY=xxxxxxx\n\n# Mailer configuration\nOPTIVEST_SMTP_HOST=xxxxx\nOPTIVEST_SMTP_USERNAME=xxxxxx\nOPTIVEST_SMTP_PASSWORD=xxxxxxx\nOPTIVEST_SMTP_SENDER=Optivest \u003cno-reply@optivest.tech\u003e\n\n# Exchange Rate API\nOPTIVEST_EXCHANGERATE_API_KEY=xxxxxxxxx\n# Alpha Vantage API\nOPTIVEST_ALPHAVANTAGE_API_KEY=xxxxxx\n# Fred API\nOPTIVEST_FRED_API_KEY=xxx\n# Financial Modeling Prep API\nOPTIVEST_FINANCIALMODELINGPREP_API_KEY=xxxxx\n# Samba Nova LLM API\nOPTIVEST_SAMBA_NOVA_LLM_API_KEY=xxxx\n# Optivest Predictor Microservice\nOPTIVEST_PREDICTOR_API_KEY=xxx\n# OCR.Space API\nOPTIVEST_OCRSPACE_API_KEY=xxxx\n```\n**The above .env is self explanatory for each API needed**\n\n5. **Build the project:** You can build the project using the makefile's command:\n\n    ```bash\n    make build/api\n    ```\n    This will create an executable file in the current directory.\n    \u003cb\u003eNote: The generated executable is for the windows environment\u003c/b\u003e\n      \u003cb\u003e- However, You can find the linux build command within the makefile!\u003c/b\u003e\n\n6. **Run the project:** You can run the project using the `go run` or use \u003cb\u003e`MakeFile`\u003c/b\u003e and do:\n\n    ```bash\n    make run/api\n    ```\n\n7. **MakeFile Help:** For additional supported commands run `make help`:\n\n  ```makefile\n  make help\n  ```\n**output:**\n```bash\nUsage:\nrun/api: Run the API server\nrun/api/origins: Run the API server with CORS origins\ndb/psql            -  connect to the db using psql\nbuild/api          -  build the cmd/api application\n```\n\n### Description\n\nThe 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.\n  - This will start the application. You should be able to access it at `http://localhost:4000`.\n\n\u003chr /\u003e\nYou can view the **parameters** by utilizing the `-help` command. Here is a rundown of \nthe available commands for a quick lookup (INCOMPLETE, use help for full list).\n\n```bash\n- api-author string\n        API author (default \"Blue_Davinci\")\n  -api-default-currency string\n        Default currency (default \"USD\")\n  -api-key-alphavantage string\n        Alpha Vantage API key (default \"NYRXRLGLWY29115K\")\n  -api-key-exchangerates string\n        Exchange-Rate API Key (default \"2bd6d65a467e533704e0a7fb\")\n  -api-key-fmp string\n        FMP API Key (default \"LtEBinivcBs2uzHNg1PHXJIRj5KsLmxJ\")\n  -api-key-fred string\n        FRED API Key (default \"1c78299c9778f33eeacf2f85261f9183\")\n  -api-key-ocrspace string\n        OCR.Space API Key (default \"K82853087188957\")\n  -api-key-optivestmicroservice string\n        OptiVest Microservice API Key (default \"xJ8u4Kz7wA9vT3gPzB2dF1mLq8N5cY6s\")\n  -api-key-sambanova string\n        Sambanova API Key (default \"4044b951-1161-4165-b025-8a7bc6f46155\")\n  -api-name string\n        API name (default \"OptiVest\")\n  -api-url-alphavantage string\n        Alpha Vantage API URL (default \"https://www.alphavantage.co/query?\")\n  -api-url-exchangerates string\n        Exchange-Rate API URL (default \"https://v6.exchangerate-api.com/v6\")\n  -api-url-fmp string\n        FMP API URL (default \"https://financialmodelingprep.com/api/v3\")\n  -api-url-fred string\n        FRED API URL (default \"https://api.stlouisfed.org/fred/series/observations?\")\n  -api-url-ocrspace string\n        OCR.Space API URL (default \"https://api.ocr.space/parse/image\")\n  -api-url-optivestmicroservice string\n        OptiVest Microservice API URL (default \"http://127.0.0.1:8000/v1/predict\")\n  -api-url-sambanova string\n        Sambanova API URL (default \"https://fast-api.snova.ai/v1/chat/completions\")\n  -cors-trusted-origins value\n        Trusted CORS origins (space separated)\n  -db-dsn string\n        PostgreSQL DSN (default \"postgres://optivest:pa55word@localhost/optivest?sslmode=disable\")\n  -db-max-idle-conns int\n        PostgreSQL max idle connections (default 25)\n  -db-max-idle-time string\n        PostgreSQL max connection idle time (default \"15m\")\n  -db-max-open-conns int\n        PostgreSQL max open connections (default 25)\n  -encryption-key string\n        Encryption key (default \"330d12d2eacd444bd87126221c91150a09cbaee8529a387282e1e910c8be3868\")\n  -env string\n        Environment (development|staging|production) (default \"development\")\n  -expired-notification-burst-limit int\n        Batch Limit for Expired Notification Tracker (default 100)\n  -frontend-activation-url string\n        Frontend Activation URL (default \"http://localhost:5173/verify?token=\")\n  -frontend-callback-url string\n        Frontend Callback URL (default \"https://adapted-healthy-monitor.ngrok-free.app/v1\")\n  -frontend-login-url string\n        Frontend Login URL (default \"http://localhost:5173/login\")\n  -frontend-password-reset-url string\n        Frontend Password Reset URL (default \"http://localhost:5173/passwordreset/password?token=\")\n  -frontend-url string\n        Frontend URL (default \"http://localhost:5173\")\n  -http-client-retrymax int\n        HTTP client maximum retries (default 3)\n  -http-client-timeout duration\n        HTTP client timeout (default 10s)\n```\n\nUsing `make run`, will run the API with a default connection string located \nin `cmd\\api\\.env`. If you're using `powershell`, you need to load the values otherwise you will get\na `cannot load env file` error. Use the PS code below to load it or change the env variable:\n\n```powershell\n$env:OPTIVEST_DB_DSN=(Get-Content -Path .\\cmd\\api\\.env | Where-Object { $_ -match \"OPTIVEST_DB_DSN\" } | ForEach-Object { $($_.Split(\"=\", 2)[1]) })\n```\n\nAlternatively, in unix systems you can make a .envrc file and load it directly in the makefile by importing like so:\n```makefile\ninclude .envrc\n```\n\nA succesful run will output something like this:\n\n```bash\nmake run/api\nRunning API server..\ngo run ./cmd/api\n{\"level\":\"info\",\"time\":\"2024-1\",\"caller\":\"api/main.go:374\",\"msg\":\"Loading Environment Variables\",\"path\":\"cmd\\\\api\\\\.env\"}\n{\"level\":\"info\",\"time\":\"2024-1]\",\"caller\":\"api/main.go:268\",\"msg\":\"Redis connection established\",\"addr\":\"localhost:6379\"}\n{\"level\":\"info\",\"time\":\"2024-1\",\"caller\":\"api/main.go:277\",\"msg\":\"database connection pool established\",\"dsn\":\"postgres://optivest:yourpassword@localhost/optivest?sslmode=disable\"}\n{\"level\":\"info\",\"time\":\"2024-1\",\"caller\":\"api/helpers.go:215\",\"msg\":\"currency certified, using cached currencies\",\"currency\":\"USD\"}\n{\"level\":\"info\",\"time\":\"2024-1-2\",\"caller\":\"api/main.go:337\",\"msg\":\"Starting Schedulers\"}\n{\"level\":\"info\",\"time\":\"2024-0-2\",\"caller\":\"api/schedulers.go:64\",\"msg\":\"Starting the recurring expenses tracking cron job..\",\"time\":\"2024-00-2\"}\n{\"level\":\"info\",\"time\":\"2024-1\",\"caller\":\"api/schedulers.go:199\",\"msg\":\"Tracking recurring expenses\",\"time\":\"2024-1 EAT m=+0.533360001\"}\n```\n\n\u003chr /\u003e\n\n### API Endpoints 📌 \u003ca name=\"endpoints\"\u003e\u003c/a\u003e\nA full ist is documented using swagger, but here is a quick runwdown:\n1. **GET /v1/healthcheck:** Checks the health of the application. Returns a 200 OK status code if the application is running correctly.\n\n2. **POST /v1/users:** Registers a new user.\n\n3. **PUT /v1/users/activated:** Activates a user.\n\n4. **POST /v1/api/authentication:** Creates an authentication token.\n\n5. **GET /debug/vars:** Provides debug variables from the `expvar` package. \n\n(will be added)\n\n## 🔧 Running the tests \u003ca name = \"tests\"\u003e\u003c/a\u003e\n\nThe project has existing tests represented by files ending with the word `\"_test\"` e.g `internal_helpers_test.go`\n\n### Break down into end to end tests\n\nEach test file contains a myriad of tests to run on various entities mainly functions.\nThe test files are organized into `structs of tests` and their corresponding test logic.\n\nYou can run them directly from the vscode test UI. Below represents test results for the scraper:\n\n```bash\n=== RUN   Test_generateSecurityKey\n=== RUN   Test_generateSecurityKey/Valid_AES-128_key_(16_bytes)\n--- PASS: Test_generateSecurityKey/Valid_AES-128_key_(16_bytes) (0.00s)\n=== RUN   Test_generateSecurityKey/Valid_AES-192_key_(24_bytes)\n--- PASS: Test_generateSecurityKey/Valid_AES-192_key_(24_bytes) (0.00s)\n=== RUN   Test_generateSecurityKey/Valid_AES-256_key_(32_bytes)\n--- PASS: Test_generateSecurityKey/Valid_AES-256_key_(32_bytes) (0.00s)\n=== RUN   Test_generateSecurityKey/Invalid_key_length_(0_bytes)\n--- PASS: Test_generateSecurityKey/Invalid_key_length_(0_bytes) (0.00s)\n=== RUN   Test_generateSecurityKey/Invalid_key_length_(-1_bytes)\n--- PASS: Test_generateSecurityKey/Invalid_key_length_(-1_bytes) (0.00s)\n--- PASS: Test_generateSecurityKey (0.00s)\nPASS\nok      github.com/Blue-Davinci/OptiVest/internal/data  0.674s\n```\n- \u003cb\u003eAll other tests follow a similar prologue.\u003c/b\u003e\n\n## 🎈 Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\nAs earlier mentioned, the api uses a myriad of flags which you can use to launch the application.\nAn example of launching the application with your `smtp server's setting` includes:\n```bash\nmake build/api ## build api using the makefile\n./bin/api.exe -smtp-username=pigbearman -smtp-password=algor ## run the built api with your own values\n\nDirect Run: \ngo run main.go\n```\n\n\n## 🚀 Deployment \u003ca name = \"deployment\"\u003e\u003c/a\u003e\n\n**(Will Be Added Soon.)**\n\n## ⛏️ Built Using \u003ca name = \"built_using\"\u003e\u003c/a\u003e\n- [Go](https://golang.org/) - Backend\n- [PostgreSQL](https://www.postgresql.org/) - Database\n- [Redis](https://redis.io/) - Cacheing\n- [Paystack](https://paystack.com) - Payment processing\n- [SQLC](https://github.com/kyleconroy/sqlc) - Generate type safe Go from SQL\n- [Goose](https://github.com/pressly/goose) - Database migration tool\n- [HTML/CSS](https://developer.mozilla.org/en-US/docs/Web/HTML) - Templates\n\n## ✍️ Authors \u003ca name = \"authors\"\u003e\u003c/a\u003e\n\n- [@Blue-Davinci](https://github.com/Blue-Davinci) - Idea \u0026 Initial work\n\nSee also the list of [contributors](https://github.com/Blue-Davinci/OptiVest/contributors) who participated in this project.\n\n## 🎉 Acknowledgements \u003ca name = \"acknowledgement\"\u003e\u003c/a\u003e\n\n- Hat tip to anyone whose code was used\n- Inspiration\n\n## 📚 References \u003ca name = \"references\"\u003e\u003c/a\u003e\n\n- [Go Documentation](https://golang.org/doc/): Official Go documentation and tutorials.\n- [PostgreSQL Documentation](https://www.postgresql.org/docs/): Official PostgreSQL documentation.\n- [SQLC Documentation](https://docs.sqlc.dev/en/latest/): Official SQLC documentation and guides.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblue-davinci%2Foptivest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblue-davinci%2Foptivest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblue-davinci%2Foptivest/lists"}