Mikane is a tool designed for calculating payments to settle shared expenses from group trips, parties, and similar activities. Whether you're on a trip, hosting a party, or sharing a flat, this application helps in managing and tracking shared expenses efficiently.

Features

• Event Management: Create and manage events, view a summary of all expenses.
• Expense Tracking: Add, edit, and delete expenses; categorize and attribute them to categories.
• User Management: Invite users to join events, create and manage guests for people without users.
• Optimized Payments: Dynamically calculates minimal transactions to settle expenses efficiently.
• Mobile Support: Full mobile support with a responsive design and PWA capabilities for a seamless experience on any device.
• Authentication: Secure login and registration of users.
• Notifications: Send email notifications for event activities and updates.

Installation

Prerequisites

• Node.js 24.x
• PostgreSQL 15+ (backend setup - option A)
• Docker (backend setup - option B)

Steps

Clone the repository:

git clone https://github.com/pudding-tech/mikane.git
cd mikane

Frontend

1. Install dependencies for the frontend:

   cd app/mikane
   npm install

2. Run the frontend application:

   npm run dev

Backend

Option A:

1. Set up a PostgreSQL database, then run db_schema.sql and all functions in the db_scripts folder against it.

2. Create a .env file and populate the required variables.

3. Install dependencies for the backend:

   cd server
   npm install

4. Run the backend server:

   npm run dev

Option B:

Use this method if you only want to work with the frontend (a database will be automatically set up, and the backend will be non-editable).

1. Create a .env file and populate the required variables:

   • Add POSTGRES_USER and POSTGRES_PASSWORD to the .env file to be used for the database setup, and ensure these values are reflected in the DB_USER and DB_PASSWORD variables, respectively.
   • The remaining database variables should be set as follows: DB_HOST=db, DB_PORT=5432, and DB_DATABASE=mikane.

2. Run the backend server, which will automatically create and connect to a ready-to-use database:

   cd server
   docker compose up

Usage

1. Open your browser and navigate to http://localhost:4200.
2. Register new accounts at http://localhost:4200/register/u, or log in with existing credentials.
3. Create an event and start adding participants and expenses.

The API documentation, following the OpenAPI specification, is available at http://localhost:3002.

Testing

Frontend

To run frontend tests:

cd app/mikane
npm run test

Backend

The backend has integration tests that require a database to function. However, this is automatically set up through Docker with the npm run db command below, so no additional actions are needed.

To run backend tests:

cd server
npm run db
npm run test

Contributing

If you want to contribute to Mikane, please fork the repository and submit a pull request. While this tool is mainly an in-house Puddingtech project, we are open to contributions from the community.

License

Mikane is licensed under the GPL-3.0 License - see the License for more information.