Tafsiri

Payments and inventory management web platform powered by HTMX.
Swagger Documentation »

View Demo · Report Bug · Request Feature

Initial load time to view demo and swagger documentation may take up to one minute due to cold booting.

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Inspiration

Tafsiri in Swahili means to translate, or as more applicable in this context, understand.

This tackles inefficiencies in manual payment recording observed at a friend's business:

• Lack of real time sales data for busy owners
• Difficulty attributing who made a payment recording and when this happened
• Time consuming manual reconciliation of daily/weekly/monthly payments, especially factoring in extended credit facilities

Tasfiri automates recording of sales & inventory tracking via a web based platform, allowing cashiers to easily start, suspend and resume payment orders with inventory details readily available to them.

Most of the work is open sourced under an MIT license, and will be using this as a basis to create a bespoke web platform for use in said business (majorly changing the look from Pico CSS to Tailwind CSS).

Technical Details

This is a hands on learning project for working with HTMX on real world project. The code is a culmination of improvements/refactors made over time to work better with HTMX.

Typescript was chosen over Go/Rust because of the ease of working with JSX for templating. This means that there isn't any need to learn any templating language, which I think is a huge productivity boost.

ElysisJS was chosen as the web framework as it is optimized for Bun and out performs Go and Rust frameworks in some benchmarks. Through usage, I've found it's still not as mature, but workable.

TypeORM was used as the database connector (been using it for years), but I would personally recommend replacing TypeORM with Drizzle.

Checking Out The Demo

TBA

(back to top)

Built With

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

This is an example of how to list things you need to use the software and how to install them.

• npm

  npm install npm@latest -g

Installation

Multiple ways to get started are supported. But they all start with cloning the repo:

git clone https://github.com/nigelnindodev/Tafsiri.git

Local Installation

A local installation assumes you have a local PostgreSQL Server running, docker installed, and are running Linux, MacOS or Windows Subsystem for Linux (WSL).

Install the latest version of Bun:

curl -fsSL https://bun.sh/install | bash

Install project dependencies

bun install --frozen-lockfile

Add a .env file with the following properties:

APPLICATION_PORT=3000
BASE_URL="http://localhost:3000"
JWT_SECRET="some_jwt_secret"
POSTGRES_USER="your_local_postgres_user"
POSTGRES_PASSWORD="your_local_postgres_password"
POSTGRES_HOST="localhost"
POSTGRES_PORT="5432"
POSTGRES_DATABASE_NAME="your_local_postgres_database_name"

Run the project in development mode

bun run dev

Open http://localhost:3000/ with your browser to see the result.

Run Test

To run tests, use the command setup-run-test defined in package.json:

bun run setup-run-test

That will use the compose.yaml file to create a testing PostgreSQL server instance using docker, and ensure it's volume is correctly cleared up after running tests.

Docker Installation

TBA

Usage

Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.

For more examples, please refer to the Documentation

(back to top)

Roadmap

TODO

• Remove long polling in creation of an order
• Instead of repeating try/catch error handling for each service method, refactor the try catch to wrap all controller methods. TODO: Does this this also propagate to the service methods? This will be interesting to find out!
• Add Zod for handling API validations
• Use snake_case for all DB columns (Untested across the board, unit tests would have been nice right now :-))
• Add DB indexes
• Improve logging with ts-log and create standard semantics for logs
• For HTMX sections where we replace all content(hx-target="outerHTML"), would be a good practice to place these sections in constants sine they are referenced in multiple locations. Should we then choose to rename them, we'll then just need to change once reference (DRY)
• Ensure once order item added to an order, it's price is immutable
• Fix bug with updated at not correctly propagating on DB level (a workaround is currently being used). Was not working because updated_at on date functionality is only supported on Postgres for TypeORM. So the workaround is the solution.
• Remove hardcoding of base url
• Return BAD REQUEST on failed Zod validations
• API tests
• HTMX input white listing (Maybe important to avoid XSS attacks)
• Timezone awareness
• Proper handling of amounts with decimals

Updcoming Features

• Authentication (username & password) to prevent unauthorized access
• Add staff details to an order to know who completed an order. Staff can log in with their dedicated credentials.
• Restriction of sensitive sections of the service to admin users only i.e Inventory Section (which can change pricing of items)
• Ability to filter for payments according to date and time interval
• Pagination of data (currently fetching all rows from the DB, this isn't feasible for a real world project)
• Store when a user last logged in
• Manual reconciliation via CSV and/or Excel/Google Sheets
• IP Address white listing (help for example ensure the service can only be accessed when connected to the store's WiFi)

Would be nice

• End to end tests with Puppeteer
• MetaBase for more in depth BI analysis
• Automated daily backups of all transactions to CSV files (stored on S3 buckets)
• Allow for changes to a confirmed order
• Add partial and deferred payments, together with tracking of the same
• Maybe to be added, but also tracking of how many inventory items are coming in. This together with order tracking can automate knowing how many inventory items are left in stock
• Mobile App?

See the open issues for a full list of proposed features (and known issues). See the project roadmap for what's currently being worked on, and future work.

(back to top)

Contributing

Contributions are much welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Your Name - @nigelnindo - nigelnindodev@gmail.com

Project Link: https://github.com/nigelnindodev/Tafsiri

(back to top)

Acknowledgments

• HTMX for Impatient Devs

(back to top)