This repository and the accompanying interactive website is presented for Code Institute Milestone Project 3.

Visit the Honey Bee site on Heroku

• Introduction
• User Experience (UX)
  • Project Goals
  • Strategy
  • Scope
  • Structure
  • Skeleton
  • Surface
• Site Functionality
• Site Development
• Testing
• Guide to Deployment and Development
• Project Review and Reflection
• Credits

This repository and the associated deployed website comprise my submission for the Diploma in Web Development, Milestone Project 3. The purpose of this project is to demonstrate ability to design and develop a database-backed web site, implemented using Flask and an appropriate database management system, with full CRUD (Create, Read, Update, Delete) functionality.

Return to ToC

The intended users of this web application are amateur beekeepers. In order to complete the British Beekeeping Association (BBKA) Certificate in Beekeeping Husbandry records need to be maintained of the checks carried out on every colony (hive). Although there is no standardised approach for inspection record keeping some data must be retained, such as data about colony health. Many variations and suggestions exist to help beekeepers in maintaining their records, with the BBKA suggesting their own Hive Keeping Record Sheet.

Figure: BBKA Hive Recording System

The aim of this application is to provide an online portal for beekeepers to maintain records of their colonies/hives and the apiaries in which they're located, plus a full digital record of every hive inspection. To this end the BBKA Hive Keeping Record Sheet has been used as the foundation for this hive inspection system.

The primary goal of this project is to design, develop and deploy an interactive website for amateur beekeepers, for the recording and maintaining of apiary and hive data. In particular, this site needs to be usable when on location, and therefore should be designed taking a mobile-first approach.

The target audience for this site are amateur beekeepers. It will support them in maintaining a record of all apiaries and hives/colonies, as well as providing an online form to be used for recording every hive inspection (undertaken weekly from spring to autumn).
Due to the nature of hive inspections, being conducted on-site in the apiary, this web app is designed primary for use on mobile devices (i.e., smartphones/tablets). Hive inspections can therefore be recorded during the inspection process, or immediately after whilst sitting in the van with a flask of tea. It's expected that additional editing and viewing of report data is likely to then be done back at home/in the office.

The scope of this application focuses on the implementation of a record-keeping. This will implement full CRUD functionality for data about apiaries, hives and hive records.

The target audience for this application doesn't include professional bee farmers. These experienced professionals won't be aiming to complete the Certificate in Beekeeping Husbandry and will have more complex requirements for maintaining business records.

The specific needs of the primary target users of this site, amateur beekeepers are outlines in the following user stories:

As a Beekeeper I want to ...

1. Be able to maintain a record of all of my apiaries: 1. create apiary record 2. read (view) apiary record 3. update apiary record 4. delete apiary record 5. view all apiary records
2. Be able to maintain a record of all of my hives/colonies: 1. create hive record 2. read (view) hive record 3. update hive record 4. delete hive record 5. view all hive records
3. Record details of my weekly hive inspections, and save them for later use: 1. create hive inspection record 2. read (view) inspection records 3. update inspection record 4. delete inspection record 5. view all inspection records for each of my hives
4. Have a registered account to secure access to my records 1. create account 2. sign in to account

Some elements considered in the current design will not be implemented due to being outside the scope described above. These include general information pages about honey bees and the beekeeping. Additional users and their user stories have been identified and are listed below. These have been flagged for future development as they fall outside the scope and requirements for Milestone Project 3.

The site structure according to functionality groupings (not strictly mapped to site pages) is shown in the Site Map figure. At the backend all data will be stored online using MongoDB. The structure of the backend database is illustrated in the MongoDB Database Schema figure.

Figure: Site Map

Figure: MongoDB Database Schema

The backend file structure, implementing the designs outlined above, was constructed according to the following design:

- 📰 app.py               <-- Python application, using Flask
- 📂 static               <-- Site files
    - 📂 css              
        - 📰 style.css    <-- CSS stylesheet 
    - 📂 img              <-- Folder containing all site images 
        - 📰 *.jpg
        - 📰 *.png
    - 📂 js
        - 📰 script.js    <-- JavaScript code for dynamic web-page functionality 
- 📂 templates            <-- Site pages
    - 📰 base.html        <-- Base HTML page using Jinja templating
    - 📰 *.html 
- 📂 docs                 <-- Location of project documentation files

Figure : Design of site file structure

Honey Bee will be constructed using a base template file, and populated with data from other html files according to application endpoints defined in flask and content population using the Jinja templating framework. From the perspective of the site visitor however it will appear to be comprised of a number of distinct pages:

• Home / Welcome Page
• Sign in and Registration Pages
• Apiary Pages: View all apiaries, add apiary, edit apiary, delete apiary
• Hive Pages: View all hives, add hive, edit hive, delete hive
• Hive Inspection Pages: View all inspection reports per hive, add inspection report, edit inspection report, delete inspection report.
• Learn About Bees Page (draft content only)
• A placeholder page for as-yet unimplemented content (included for illustration, although in practice all unimplemented functionality would be hidden from site visitors).
• plus, for the unfortunate visitor, and error page informing them when something goes wrong.

Error handling will be provided throughout to ensure that user engagement is not interrupted by functional or runtime errors (or at least minimised). This error handling will be implemented as follows:

• Failed Operations Flask's flash messages will be employed throughout the site. These will keep the site user informed of backend functionality, informing them when events occur 'behind the scenes'. Users will mostly see messages relating to successful operations (successful login, data update or deletion, etc). Flash messages will also be used when an error occurs, such as when data cannot be located in the database, when a data update fails, and so on. In addition to flash messages, every failed operation will be logged in the database for later review.

• Application Exceptions When an exception is raised by the application an error page will be displayed including details of the error that occurred. This is included to ensure the application doesn't 'crash' but informs the user of events that have occurred. In order to handle such exceptions the site will employ the Flash errorhandler endpoint.

• Out of Scope Functionality Until all future functionality is completed, some elements of the site will not be active. Although these are outside the scope of this project, these may cause an issue to visitors of the initial site. As such, where a page is not yet available in the site the page placeholder.html will inform the visitor that the functionality has not yet been implemented.

Due to the primary aim of this site being a tool for beekeepers to use whilst on location, taking records whilst inspecting their bee colonies, the design focus has been on the mobile devices they will be using - smartphones and tablets. The user interface designs are separated into three groups: Apiary Management, Hive Management and Hive Inspections. In addition there are two pages for registered users - Registration and Sign In - and a Home page to welcome all site visitors.

Figure: Home and User Pages

Figure: Apiary Management

Figure: Hive Management

Figure: Hive Inspection

The surface design decisions were made ono consideration of keeping the interface simple, intuitive, with colors associated with nature and bees

All icons across the site are from Google's font library. These Material Symbols and Icons have ben selected to align most closely with the topic to which they're attached (such as a hive or bee) or familiarity to users (sign in and out, information and edit, cancel, etc).

The design intention was to select colors that are associated with bees, honey and nature.

Having selected a honey-yellow color this was entered into the online palette generator from ColorSpace in order to generate suggested palette options. Picking a potential contracting color for site font text, Adobe's Color Contrast Analyzer was used to tweak the color match to ensure the site is accessible to a wider audience of users.

Figure: Color contrast checker from Adobe Accessibility Tools

Fonts used across the site were chosen using the Fontjoy font pairing suggestion site, where fonts pairings are suggested using AI/Deep Learning. The heading font (Montserrat) was selected first due to it's clear structure being easily visible on small viewports. The complementary body (PT Sans) and supporting (Karma) fonts generated were selected based on those I felt complemented the heading font.

Figure: Final font selection in Fontjoy

All images used across Honey Bee were chosen from Pixabay from their royalty free library.

Site accessibility was considered throughout the design, development and testing process. This was guided by W3C ARIA guidelines and MDN.

Return to ToC

This section provides an overview of the application functionality. Further illustrations of application functionality can be found in the accompanying TESTING document.

• User access - registration, sign in & sign out

• Apiary Management - adding, viewing, view all, editing & deleting

• Hive Management - adding, viewing one, view all, editing & deleting

• Hive Inspections - adding, viewing, view all, editing, deleting.

• Additional Pages - home page, learn about bees & about Honey Bee

Site styling is responsive across viewports. Two areas however are work noting: menu/navigation and site tables.

The top menu/navigation bar is responsive across users and device sizes.

The four different types of users are: Unregistered site visitor, Beekeeper, Beekeeper with Admin role, and Admin only.

Figure: Menu - Unregistered user

Figure: Menu - Beekeeper

Figure: Menu - Beekeeper and Administrator

Figure: Menu - Administrator only

The menu/navigation bar is also responsive according to screen size to facilitate easy use across devices, especially mobile devices (tablets and smartphones)

Figure: Collapsed menu on small screen

Figure: Expanded side menu on small screen

Data tables can be unwieldy and cluttered on smaller device screens. To keep the screen uncluttered and clear, and eliminate the need for side scrolling, site tables are responsive, showing/hiding columns according to the viewport.

Figure: Hive Management Table - Laptop screen

Figure: Hive Management Table - Small screen (mobile)

Across all viewports the full details can be viewed by clicking the 'more' button at the right end of every row.

Figure: Individual hive detail screen on small/mobile device

This responsive behaviour is continued across all tables. For example, reviewing the hive inspection reports for The Bookshop Hive in The City Apiary (Beekeeper - AlanP) ...

Figure: Hive inspection reports - small device (eg. smartphone)

Figure: Hive inspection reports - medium device (eg. laptop)

Figure: Hive inspection reports - large device (eg. desktop)

This application has been developed with the intention of it failing gracefully when unforeseen errors occur, and keeping the user informed at all times.

Failed Operations Flash messages inform user when an error has occurred.

Figure: Example flash message - Password error

Application Exceptions When runtime errors occur, such as page access error (e.g. 404), attempted unauthorised access, etc, the user is informed through the use of an error page. This will include the details of the error message, but the user doesn't need to act on these. Error messages are displayed just for information.

Figure: Example error page format - 404 error

Error logging When runtime errors occur, in addition to users being informed these errors are logged to the database:

flash("Error ocurred. New apiary not added. Please try again")
            mongo.db.exceptionLog.insert_one(
                {"datetime": datetime.datetime.now(), 
                 "action": "Add new apiary",
                 "exception": e})

Figure: Example of logging code

Out of Scope Functionality If the user ever stumbles upon a part of the site that has not yet been launched, or is currently unavailable for some reason, a placeholder page will be displayed.

Figure: Placeholder page

Return to ToC

Markup Languages

• HTML: The standard web page markup language for constructing static web pages.
• Markdown: Use to produce project documentation, including this README.

Coding

• Python: The Python programming language was used to provide the majority of the backend functionality.
• Flask: The Flask micro web framework was used to provide a web routing functionality.
• Jinja: This templating language was used to enable dynamic data modifications in the web application from Python and Flask.
• Werkzeug: The security and exceptions modules of Werkzeug were employed to provide password encryption and route exception handling respectively to the web application.
• JavaScript & jQuery: These were used to add additional functionality to the site, primarily for modifying the status of elements within HTML pages,

Styling

• Bootstrap 5.3: The Bootstrap toolkit was used for site layout and styling.
• CSS: Additional styling was added to the site using CSS.

The backend functionality of this web application is underpinned by MongoDB.

This NoSQL database management system (DBMS) was chosen, primarily, for the following three reasons.

1. The database schema for this initial version of the web application isn't overly complex and is relatively static. Future developments would however require schema flexibility for efficient storing of profile data, images, and other unstructured data.
2. The flexibility of a MongoDB schema allows for maintaining a (short) record of each database update for each item in each collection, thus maintaining a history of edits. The current approach includes appending each update to an update-history array, currently in the form of a dictionary containing a datetime stamp and comment. Storing this expanding array of dictionaries would not be possible in a relational database without breaking one of the key requirements for first normal form, where each attribute should be atomic.

Figure: Sample apiary record from the project database, illustrating update history

3. Although relationships and referential integrity can be enforced, the approach to this is flexible and can be controlled by the application developer. This allows for more flexibility in developing this application such as allowing for future intended developments where an administrator can maintain records for apiaries that are no longer managed by a beekeeper. In a relational database breaking the relationship between beekeeper and apiary (or hive) would undermine referential integrity. This is not an issue however within a NoSQL schema.

This section lists the tools used during this project in support of the development and deployment stages.

• VS Code: All code was developed using a local installation of VS Code. (Code Institute development tools were not used during this project)
• Google Chrome Developer Tools: Used throughout development to support page design, testing and accessibility.
• Git & GitHub: Git used for version control, with GitHub being employed as the online repository for all project work.
• Heroku: The Heroku platform has been used in this project to host the final, deployed web site.
• Tinyfy: Used to optimize site images to reduce download time.

Return to ToC

Full overview and results of site testing can be found in TESTING.MD.

Return to ToC

Guidance for how to use the project repository for deploying the site or for undertaking further local development can be found in DEPLOYMENT.MD.

Return to ToC

There are a number of areas where this project could be improved, and where the site can (and will) be developed further.

Currently the user is able to edit and delete data and is notified of success via flash messaging. However, functionality could be improved by adopting a more defensive approach to coding by including checks, asking users to actively confirm deletions and edits.

Manual testing was undertaken before project completion. However, this process could be improved and the site more robust through the inclusion of automated testing.

Site currently relies on HTTP. Future development should include upgrading this to HTTPS.

The code in app.py could be improved by making more use of functions to reduce code duplication. In addition, forms used for creating and editing data could have improved flexibility to be reused. Additional Jinja logic would be used in improving this. The result of this refactoring would improve code readability and maintainability.

Currently flash messages are displayed green. In the next stage of development these would be altered according to the type of message being displayed, such as red for errors/warnings. Using familiar and intuitive colors wil improve the user experience.

Apiary and hive records are currently liked to beekeepers using the username. Although this works well for a small application, this is not suitable for an application that, when launched, would be used by a number of people with a potentially large number of hives and apiaries. Linking records on such fields is not good practice. This will therefore be revised to link records on ObjectIDs. As well as being more robust, this would also enable utilisation of more efficient data indexing.

Aside from implementing the Future User Stories listed above, the site could be improved by undertaking some additional work on this current version. The initial improvements are listed in this section.

At present all hives are listed together per beekeeper. An important future feature is to add a filter whereby the beekeeper can view only those hives within a specified apiary. Being a relatively minor adaption, this would be one of the first improvements to be made to the Honey Bee web application.

Some areas of the site have the potential to become crowded by text. Description table columns in particular could potentially contain more text than fits comfortably on a small screen. In future text would be truncated according to standard breakpoints.

Including popovers or tooltips would help users. In particular, including these on the hive inspection would be beneficial for new beekeepers who will have a lot to learn and handle out in the field. Providing guidance during inspections would support them in skill development and confidence growth. These popovers/tooltips would be an optional feature that could be turned off once no longer required.

When a Hive is deleted, hive inspection reports are currently left unmodified in the database. This is to ensure all records are maintained for reference and auditing. In future versions of this site hives the hive owner will be able to maintain access to all previous records and choose to either export them or permanently delete them. The site administrator will also have access to be able to create digital backups or export to a hard copy.

Currently, when deletion is selected the records are deleted from the database. In future the beekeepers will have more control over deletions.

1. A two-stage delete where the records are flagged as historical. They can the be deleted at a later date once definitely no longer required (eg, when reporting period has passed, according to legal record keeping deadline, etc.)
2. An immediate delete of the selected record, without deleting any others that link to it. For example, deleting an apiary but not deleting the hives.
3. An immediate delete with propagating delete. For example, deleting an apiary AND deleting all hive and all records corresponding to those hives.

Whenever a record is edited in the initial version of this web application, a record is retained of the edit date-time stamp. This means there is a full record of dates and times each edit took place. A future expansion will include noting the details of the edit, such as which items were changed. This will result in a more comprehensive and auditable change history.

Return to ToC

• All images obtained from Pixabay are free to use under their Content License.
• Google fonts and icons have been used across the site.

• Exception handling code was adapted from the Flash errorhandler endpoint example code.
• Inspiration for site button styling was taken from CSS Scan.
• Information badges at top of README created using Shields.io

• Development of the two project markdown files were supported through reference to the following resources:

  • GitHub's Writing on GitHub documentation,
  • Kera Cudmore's Readme Examples for Code Institute Diploma Students,
  • Adam Pritchard's Markdown Cheatsheet.

• General accessibility guidance was obtained from the W3C ARIA guidelines.

• Guidance on ARIA roles and descriptions obtained from MDN.

• The following resources were used to develop coding skills, in addition to the Code Institute learning materials:

  • Information on using Bootstrap 5 was obtained from both the Bootstrap 5.3 documentation and W3Schools Bootstrap 5 Tutorial.
  • MongoDB Atlas documentation and the MongoDB University free courses.
  • Guidance on how to handle application errors, resulting in the inclusion of error handling endpoint and error.html file, obtained from Flask's documentation

• Guidance on using the three Lighthouse modes (user flows) was obtained from Google Chrome's Lighthouse documentation.

• Inspiration for the Hive Inspection Form was taken from the British Beekeeping Association (BBKA) Hive Keeping Record Sheet, my need to maintain such records as a new beekeeper and not being able to find a simple-to-use digital system for recording this data.

I would like to acknowledge the following people who helped me complete this milestone project:

• Amy Richardson - our Code Institute cohort facilitator.
• Jubril Akolade - my Code Institute mentor.
• The Code Institute Slack community, in particular my fellow students in the feb-2023-pla cohort.

Return to ToC