Mbeca Ciaku

This application is currently under development for Version2. You may find a lot of the parts are broken. Onc everything has been modified and fixed, I will make a note of it here.

Mbeca (pronounced as 'besha') means "money" and Ciaku (pronounced as 'shiaku') means "mine" in Kikuyu, one of the venacular languages in Kenya. Put together, you get "My money". This project is aimed at helping a user to visualize his money.

Table of Contents

• Overview
• Features
• Tools Used
• Design
• Contributors
• License
• Deployed Application
• User Roles
• How To Use The Application
• Testing The Application Locally
• Areas of improvement
• Known Issues
• Future Plans to Solve the Issues

Overview

For many years, I have used Google Sheets to record how my money comes in and goes out. At the end of each day, preferably at night, I consistently update this file with the current state of my money.

It works well, but it is quite cumbersome to use over a long period of time. For example, I have to manually create the table structures occassionally. I also have to manually add the formulas to generate a chart of my income and expenses. Google Sheets allows me to organize my data, and the data is presentable, but if I cannot quickly visualize this data, then it is hard to know what is going on.

Besides detailed budget, income and expenses data, I wanted to have a summary of the health status of my money. I would compare my expenses to my budget and see if I was spending too much. Of course, expenses are made possible by my income. This cashflow is what can enable one to buy an asset and experience freedom or live a liability-filled life.

Mbeca Ciaku is an attempt to create an easier solution to this small problem. Besides simplicity, I wanted to make an application that would be usable by multiple other people. These users can download their data for offline analysis. The downloaded data would be organized and encrypted in a PDF file.

Sample income data on Mbeca Ciaku

Sample financial statement on Mbeca Ciaku

Inspired by MPesa, I found the encryption process of personal data very interesting. This feature is really useful. In the MPesa context, the need to guard against the rampant MPesa fraud cases is critical. If you are an active MPesa user, sometimes you would like to refer to your transactions to settle a dispute, confirm a payment, or to make a complaint. Whatever the case, Safaricom allows you to easily request for a copy of your transaction data for free. The statement would be sent to you via email. This file is encrypted and can only be accessed by you. At the time of this writing, decrypting the file is dependant on the user providing their National ID number plus a one-time numeric token sent to their phone. The decryption format is "ID-token".

Features

• Password-based user authentication
• Two-factor authentication
• Custom super user (aka admin)
• Custom user roles
• Email notification
• Interactive tables with search, sort and pagination functionality
• Download of user data as PDF file
• Encryption of downloaded PDF file
• Tests
• Custom support dashboard
• Dynamic charts
• Password reset
• Rich text integration and preview

Tools Used

• Flask (Python framework)
• Flask Bootstrap for styling and cross-browser responsive design
• Flask-WTF for form validation
• Flask-Login for user authentication
• Flask-Mail for email notification
• Flask-SQLAlchemy for database management
• Flask-Migrate for database migrations
• PyFPDF for PDF generation
• PyPDF2 for PDF encryption
• Unittest for unit testing
• ChartJS for data visualization
• Twilio Verify API for SMS verification
  • To work with Twilio Verify API, you need to have a Twilio account. Learn more about it here.
• Flask pagedown for Markdown support on both the client and the server

Design

• Mbeca Ciaku on Figma

Contributors

License

• MIT license

Deployed Application

• Mbeca Ciaku on Heroku (no longer working)
• Mbeca Ciaku on Render (main)

User Roles

Admin

• Has a private link to login
• The idea is to have no registration page for the admin, but since this is a test application, I have included a link to the registration page.
• Adds the support team responsible for for answering user questions
• Can delete support team members permanently

Support Team

• Responsible for answering user questions and providing support
• Has a private link to login
• They cannot register themselves; only done by the admin
• Once registered, their login credentials are automatically sent to them via email
• Receives email notifications when there is a new question

User

• A random user can register themselves
• They will be required to authenticate themselves before they can access the application
• Can update their financial information (budget, income, expenses, assets, liabilities)
• They can download their data as an encrypted PDF file

How To Use The Live Application

• Watch on YouTube

Alternatively, you can do the following:

[Browser 1 (Brave)] Ceate an Admin

• Create a new admin
• Login as admin. You will be redirected to the admin dashboard.
• Create a new support team member

[Browser 2 (Firefox)] Login as Support Team

• Find the login details to your support account in the email you received.
• Login as support team. You will be redirected to the support dashboard.
• Click on "Answer" link to respond to a user's question. The user will recieve an email notification.

[Browser 3 (Chrome)] Register as User

• Create a new user
• Login as user. You will be redirected to the user home page.
• Update your financial information
• User can optionally download their data as an encrypted PDF file. The password is user's username.
• Need help? Contact support team

Testing The Application Locally

1. Clone the repository

   $ git clone git@github.com:GitauHarrison/mbeca-ciaku.git

2. Change to the repository directory

   $ cd mbeca-ciaku

3. Create and activate a virtual environment

   $ virtualenv venv
   $ source venv/bin/activate
   
   # OR using virtualenvwrapper
   
   $ mkvirtualenv mbeca-ciaku

4. Install dependencies

   (mbeca-ciaku)$ pip3 install -r requirements.txt

5. Create .env file in the root directory to store all needed environment variables

   (mbeca-ciaku)$ touch .env

6. Update .env file with the variables seen in .env-template file in the repository root directory

   # Example .env-template file
   
   SECRET_KEY=
   PDF_FOLDER_PATH=
   QUESTIONS_PER_PAGE=

   Note on how to generate a random string for the SECRET_KEY variable:

   # On terminal
   $ python -c "import os; print(os.urandom(24))"
   
   # Output: b'\xc5\xdd\xb3s\xab<\xcc;h$>\x83f>e$\x03\xb8\xc8\xd1\xce\tZ\xd1'
   
   # Or
   
   (mbeca-ciaku)$ python -c 'import secrets; print(secrets.token_hex(16))'
   
   # Output:  ff4fcb6dc2243c5050677dca63c05112
   
   # Or
   
   # Get random value from https://www.grc.com/passwords.htm

7. Run the application

   (mbeca-ciaku)$ flask run

8. Paste the localhost URL http://127.0.0.1:5000 into your browser. You should be able to see the application.

9. Run the tests

   (mbeca-ciaku)$ python3 -m tests.py

Areas of Improvement

• User interface design
• Scheduled email notifications to remind users to update their data at the end of a day

Known Issues

• All users are loaded from the database on every page load. In the event a user, a support and an admin are all logged in, and one out of the three does not log out, the application will still load the current user in the session. Trying to access the anonymous about and learn more pages will not load the session-bound navbar.
• The chart currently displays all the data from the point (0, 0). This may not be accurate if a user updates their data at various stages of the year. Technically if, say, an income was added in July, then the graph should begin from July, not January.
• If a user adds data, say income data, from the month of May when today is July, then the graph should update the user data to include the data from May as May not as July.

Future Plans to Solve the Issues

• Use of data visualization tools such as Seaborn, plotly.express and Matplotlib instead of Chart.js to create charts.