Shepherd

Herd management system

Currently available by following URLs

• http://35.204.203.203/
• http://35.204.203.203/yak-shop/ui

System Context diagram (C4 Level 1)

Container diagram (C4 Level 2)

Project structure

• shepherd - folder with flask application
  • swagger.yml - API specification with mapping to python function in yakshopapi module
  • yakshopapi.py - Adapter between RESTAPI and service
  • service.py - Business logic implementation
  • product_calculator.py - Util module to calculate milk and skins production
  • storage.py - Persistence module, works with database
  • db.py - Setup database connection
  • __init__.py - Create Flask application
  • parser.py - Parser of xml file with herd
  • schema.sql - Script to setup database schema
  • model.py - Dataclasses of core system objects
  • records - Convertor of model from/to db records
  • templates - Jinja2 html templates
    • overview.html - Html for single page application
  • static - Static content
    • js - JavaScript
      • overview.js - Scripts supporting overview.html
• tests - test folder

Checkout project

git clone https://github.com/Vakha/flask_app
cd flask_app

Run as prebuild docker image locally

Requirements

• docker
• docker-compose

Simply run following command

docker-compose up -d

Explore API specification

Open http://127.0.0.1:5000/yak-shop/ui in your favourite browser.

Explore application

Open http://127.0.0.1:5000/ in your favourite browser, and you'll be redirected to overview page.

Overview page contains:

• Navigation between days
• Ordering form
• Amount of resources in stock
• Herd list (as for current day)
• Order list for current day

Installation

Requirements

• Python 3.8+
• pip

1. Setup and activate virtual environment

python3 -m venv venv
. venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

3. Add project root to python path

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Run as python script

python shepherd/herd.py $FILENAME $DAY_NUMBER

Example:

python shepherd/herd.py herd.xml 14

Run as web service locally

1. Setup flask variables

export FLASK_APP=shepherd
export FLASK_ENV=development

2. Initialise database schema

flask init-db

3. Write test data to database

flask write-test-data tests/data.sql

4. Run Flask application

flask run

Run test

pytest

Check test coverage

1. Run test with coverage

coverage run -m pytest

2. See report in terminal

coverage report

3. More detailed html report

coverage html
open htmlcov/index.html

Make distribution file

python setup.py bdist_wheel

.whl file could be found in dist folder

ls dist/shepherd-1.0.0-py3-none-any.whl

Could be run on another machine as following:

pip install shepherd-1.0.0-py3-none-any.whl
flask init-db
flask write-test-data $TEST_DATA_FILE
flask run 

Note: If you see this message

The swagger_ui directory could not be found.

run the following command (must be quoted in zsh)

pip install 'connexion[swagger-ui]'

Build docker image

docker build -t vakha/shepherd:latest .

then run

docker-compose up -d