From 53c4e50f0eedc2c7f062be2907d7204949538340 Mon Sep 17 00:00:00 2001 From: Lulu <104063177+Luluameh@users.noreply.github.com> Date: Thu, 28 Nov 2024 07:49:07 +0000 Subject: [PATCH 1/3] docs: update documentation for all apps --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6c9886ee..c51b5f6f 100644 --- a/README.md +++ b/README.md @@ -2,39 +2,89 @@ This project consist of a monorepo with components required for the implementation of DeRisk on Starknet. There are several components in this repository, each with its own purpose and functionality. The main components are: -- `data_handler` -- `web_app` -- `legacy_app` -- `dashboard_app` -- `shared` - Common code shared between the components +- [`data_handler`](./apps/data_handler/README.md) - Data processing and analysis component +- [`web_app`](./apps/web_app/README.md) - Main web application interface +- [`legacy_app`](./apps/legacy_app/README.md) - Legacy application functionality +- [`dashboard_app`](./apps/dashboard_app/README.md) - Analytics dashboard +- [`shared`](./apps/shared/README.md) - Common code shared between the components + +## Quick Start Guide + +### Prerequisites +- Docker installed on your machine (v19.03+ recommended). +- Docker Compose installed (v1.27+ recommended). + +### Data Handler + +The data handler component processes and manages data for the DeRisk platform. + +#### Local Development -## Data Handler 1. To set up this project run next command for local development in `derisk-research` directory: + +2. Environment Configuration: +```bash +cp apps/data_handler/.env.example apps/data_handler/.env.dev ``` +3. Start the Services: + +```bash docker-compose -f devops/dev/docker-compose.data-handler.yaml up --build ``` -2. To run test cases for this project run next command in `derisk-research` directory: +4. Stop the Services: +```bash +docker-compose -f devops/dev/docker-compose.data-handler.yaml down ``` + +5. To run test cases for this project run next command in `derisk-research` directory: +```bash make test_data_handler ``` +For detailed documentation, see the [Data Handler](./apps/data_handler/README.md) + + ## Legacy app + +The legacy app provides essential functionality for data visualization and analysis through a Streamlit interface. + +#### Local Development + 1. To set up this project run next command for local development in `derisk-research` directory: -``` +```bash make setup ``` + 2. To run streamlit app run next command in `derisk-research` directory: -``` +```bash make app ``` +3. Start Jupyter notebook (optional): +```bash +make notebook +``` +For detailed documentation, see [`legacy_app`](./apps/legacy_app/README.md) + ## Web app (Notification app) -1. To set up this project run next command for local development in `derisk-research` directory: +To set up this project run next command for local development in `derisk-research` directory: + +1. Environment Configuration: +```bash +cp apps/web_app/.env.example apps/web_app/.env.dev ``` + +2. Start the Services: +```bash docker-compose -f devops/dev/docker-compose.notification-app.yaml up --build ``` +3. Stop the Services: +```bash +docker-compose -f devops/dev/docker-compose.notification-app.yaml down +``` + ## Shared package (Common code shared between the components) 1. How to run test cases for shared package, run next command in root folder: From 7f085f7a1ed1aa10188a73ddfa68fab25457b0ce Mon Sep 17 00:00:00 2001 From: djeck1432 Date: Thu, 28 Nov 2024 18:48:31 +0100 Subject: [PATCH 2/3] move db connector inside class --- apps/dashboard_app/helpers/load_data.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/apps/dashboard_app/helpers/load_data.py b/apps/dashboard_app/helpers/load_data.py index 75c37b00..0096021f 100644 --- a/apps/dashboard_app/helpers/load_data.py +++ b/apps/dashboard_app/helpers/load_data.py @@ -19,7 +19,6 @@ from dashboard_app.helpers.tools import get_prices logger = logging.getLogger(__name__) -data_connector = DataConnector() class DashboardDataHandler: @@ -31,6 +30,7 @@ def __init__(self): """ Initialize the data handler. """ + self.data_connector = DataConnector() self.underlying_addresses_to_decimals = defaultdict(dict) self.zklend_state = self._init_zklend_state() self.prices = None @@ -41,8 +41,7 @@ def __init__(self): # nostra_mainnet_state, ] - @staticmethod - def _init_zklend_state() -> ZkLendState: + def _init_zklend_state(self) -> ZkLendState: """ Initialize ZkLend state. Fetch data from the database and initialize the state. @@ -51,9 +50,9 @@ def _init_zklend_state() -> ZkLendState: logger.info("Initializing ZkLend state.") zklend_state = ZkLendState() start = monotonic() - zklend_data = data_connector.fetch_data(data_connector.ZKLEND_SQL_QUERY) - zklend_interest_rate_data = data_connector.fetch_data( - data_connector.ZKLEND_INTEREST_RATE_SQL_QUERY + zklend_data = self.data_connector.fetch_data(self.data_connector.ZKLEND_SQL_QUERY) + zklend_interest_rate_data = self.data_connector.fetch_data( + self.data_connector.ZKLEND_INTEREST_RATE_SQL_QUERY ) zklend_data_dict = zklend_data.to_dict(orient="records") From 340b46df2b298adfef1dad42387033e8cf85daf0 Mon Sep 17 00:00:00 2001 From: Lulu <104063177+Luluameh@users.noreply.github.com> Date: Thu, 28 Nov 2024 18:45:55 +0000 Subject: [PATCH 3/3] docs: update documentation structure --- README.md | 12 +++++- apps/dashboard_app/README.md | 75 ++++++++++++++++++++++++++++++++++++ apps/data_handler/README.md | 22 +++++++---- apps/web_app/README.md | 30 +++++++++++---- 4 files changed, 123 insertions(+), 16 deletions(-) create mode 100644 apps/dashboard_app/README.md diff --git a/README.md b/README.md index c51b5f6f..a70d9585 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ There are several components in this repository, each with its own purpose and f ### Prerequisites - Docker installed on your machine (v19.03+ recommended). -- Docker Compose installed (v1.27+ recommended). +- Docker Compose installed (v2.0+ recommended). ### Data Handler @@ -85,6 +85,16 @@ docker-compose -f devops/dev/docker-compose.notification-app.yaml up --build docker-compose -f devops/dev/docker-compose.notification-app.yaml down ``` +## Dashboard App + +Interactive dashboard application for visualizing and analyzing DeRisk data. + +### Key Features +- Interactive data visualization +- Protocol statistics monitoring +- Loan portfolio analysis +- Real-time data updates +For detailed documentation, see the [Dashboard App](./apps/dashboard_app/README.md) ## Shared package (Common code shared between the components) 1. How to run test cases for shared package, run next command in root folder: diff --git a/apps/dashboard_app/README.md b/apps/dashboard_app/README.md new file mode 100644 index 00000000..c21a70d6 --- /dev/null +++ b/apps/dashboard_app/README.md @@ -0,0 +1,75 @@ +# DeRisk Dashboard App + +Interactive dashboard application for visualizing and analyzing DeRisk data. + + +## Prerequisites + +- Python 3.11+ +- Poetry +- Docker + +## Setup + +### Local Development + +1. Install dependencies: +```bash +./setup.sh +``` + +2. Run the dashboard: +```bash +poetry run python dashboard.py +``` + +### Docker Setup + +1. Build the image: + + +2. Run the container: + +3. stop container: + +## Key Features + +- Interactive data visualization +- Protocol statistics monitoring +- Loan portfolio analysis +- Real-time data updates + +### Adding New Charts + +1. Create chart module in `charts/` +2. Implement chart logic using main.py templates +3. Register in dashboard.py + +### Data Integration + +Use `data_connector.py` to add new data sources: + +```python +from data_connector import DataConnector + +connector = DataConnector() +data = connector.get_data() +``` + +## Testing + +```bash +poetry run pytest +``` + +## Contributing + +1. Fork the [repository](https://github.com/CarmineOptions/derisk-research) +2. Create feature branch +3. Submit pull request + +Read [contribution guide](CONTRIBUTING.md) + +## License + +[License details](LICENSE.txt) diff --git a/apps/data_handler/README.md b/apps/data_handler/README.md index f4d338a5..37e0d922 100644 --- a/apps/data_handler/README.md +++ b/apps/data_handler/README.md @@ -1,5 +1,6 @@ # DeRisk Data Handler +## Overview This project was created to make data public for Derisk Alert app. This app is not intended for you to use in production. It's just a research project. @@ -23,7 +24,7 @@ git clone https://github.com/CarmineOptions/derisk-research.git cd data_handler ``` -### 3. Set up `.env` file +### 3. Configure Environment Variables Create `.env` file or just rename `.env.example` --> `.env` @@ -57,26 +58,29 @@ docker-compose up -d --build docker-compose down ``` -## Data migrations +## Data migrations with Alembic In this project is using `alembic` for data migrations. -For generating new migration use this command: -In folder `apps` run these commands: + +### Generating Migrations +Navigate to the `apps` folder and generate a new migration using the following command: ```bash +cd apps alembic -c data_handler/alembic.ini revision --autogenerate -m "your message" ``` - +### Applying Migrations After generating new migration, you need to apply it: ```bash alembic -c data_handler/alembic.ini upgrade head ``` - +### Rolling Back Migrations For downgrading migration: ```bash alembic -c data_handler/alembic.ini downgrade -1 ``` +### Migration Utility Commands Useful commands: Purge all celery tasks: ```bash @@ -91,13 +95,15 @@ Go to bash docker-compose exec backend bash ``` -## How to run migration command: +## Running Migration Command: 1. Go to root folder `derisk-research` + +### Prepare the Environment 2. Run up db in docker: ``` docker-compose -f devops/dev/docker-compose.db.yaml up -d --remove-orphans ``` -3. Go to `data_hander` folder: +3. Navigate to the `data_hander` directory: ``` cd apps/data_handler ``` diff --git a/apps/web_app/README.md b/apps/web_app/README.md index ff850f9d..f41e88ac 100644 --- a/apps/web_app/README.md +++ b/apps/web_app/README.md @@ -1,15 +1,23 @@ # DeRisk Alert # How it works: + +This section provides an overview of how the DeRisk Alert system operates. ![A diagram that illustrates how this app works](docs/how-it-works.drawio.png) + +### Demo Video ### `Here is a demo video of how it works` [Click](https://drive.google.com/file/d/1TYwEx6PWvPerrJSfiePQzZEtbj53Yn_g/view?usp=sharing) +### Notification System ### When the `health ratio` is appropriate to the value you ### have set you will be notified via `Telegram` ![An image that illustrates a notification](docs/notification.png) -# Database ordering: +# Database Structure: + + +This diagram shows the ordering and structure of the database for the DeRisk Alert system: ![A diagram that illustrates the ordering of the DB](docs/db-ordering.png) ## Requirements @@ -18,20 +26,28 @@ - docker - docker-compose +## Telegram Bot Setup + +To receive alerts via Telegram, follow these steps to set up your Telegram bot: + ## How to get Telegram Token: -### 1. To get a token and create a chatbot, you need to find a bot named BotFather in the Telegram messenger. +### 1. Find BotFather: +To get a token and create a chatbot, you need to find a bot named BotFather in the Telegram messenger. ![An image that shows how to find bot father in telegram](docs/find-bot-father.jpg) -### 2. In the BotFather bot, you need to write the command `/newbot`. After that, BotFather will prompt you to enter: +### 2. Create Your Bot: +In the BotFather bot, you need to write the command `/newbot`. After that, BotFather will prompt you to enter: - the name of your bot that users will see; - uri of the bot, i.e. the link to the bot that will be added to the link https://t.me/{youruri}. ![An image that shows how to create a new bot](docs/newbot-botfather.jpg) -### 3. After the data is entered and it has passed validation, BotFather will respond with a message that will contain the API token of the created bot. +### 3. Retrieve Your Token: +After the data is entered and it has passed validation, BotFather will respond with a message that will contain the API token of the created bot. ![An image that shows how to get a created token](docs/get-token.jpg) -### 4. Done! At this moment, the bot has already been created, and it is possible to subscribe to it by finding it in Telegram search or by following the link. +### 4. Access Your Bot: +Done! At this moment, the bot has already been created, and it is possible to subscribe to it by finding it in Telegram search or by following the link. # Setup @@ -41,7 +57,7 @@ git clone https://github.com/CarmineOptions/derisk-research.git ``` -### 2. Go to `web_app/` +### 2. Navigate to the `web_app/` Directory ```bash @@ -77,7 +93,7 @@ DATA_HANDLER_URL=# url to data handler docker-compose up -d --build ``` -#### Stop your containers +#### 6. Stop your containers ```bash docker-compose down