GiftFlow

A self-hosted, modern, mobile-friendly web application for managing gift ideas, purchases, and reimbursement tracking among a group of members.

Visual Overview

### Main Dashboard	### Detailed View by Person

---

### Add Idea Form	### Add Purchase Form

---

Historical Archive View 1

Historical Archive View 2

Historical Archive View 3

Table of Contents

• Overview

• Key Features

• Tech Stack

• Getting Started

• Prerequisites

• Installation & Deployment

• Project Structure

• API Usage & Endpoints

• Authentication

• Example Requests

• Endpoint List

• License

Overview

GiftFlow solves the common problem of coordinating gifts for family members or friends. It provides a centralized platform to list gift ideas, convert them into actual purchases, and transparently manage shared costs and debts. The application is designed to be simple, intuitive, and fully responsive, with a focus on a clean user experience.

The entire application is containerized with Docker, making deployment and management straightforward.

Key Features

• Collaborative Idea Management: Any member can add gift ideas for any other member.
• Purchase Tracking: Convert an idea into a purchased gift, tracking price, store, date, and payer.
• Reimbursement System: Clearly define which members are participating in a group gift and track reimbursement statuses (Unpaid, Partial, Fully Paid).
• Full CRUD Operations: Create, Read, Update, and Delete both ideas and purchased gifts.
• Historical Archives: Gifts from previous years are automatically archived and can be browsed by year and by person.
• Multi-language Support (i18n): The interface is translated using JSON files, with the default language configurable at deployment. (Currently supports English & French).
• Secure by Default: API endpoints are protected by Basic Authentication.
• Responsive Design: A mobile-first approach ensures a seamless experience on any device.
• Self-Hosted & Private: Your data stays on your server.

Tech Stack

• Frontend:

• HTML

• CSS

• JS

• Backend:

• Node.js

• Express.js

• Infrastructure & Deployment:

• Docker & Docker Compose

• Nginx (as a web server and reverse proxy)

Getting Started

Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

You need to have Docker and Docker Compose installed on your machine.

Installation & Deployment

Clone the repository:

git clone https://github.com/garnajee/giftflow.git
cd giftflow

Configure Members & Data (Optional):

• Edit data/users.json to define the list of members, their usernames, and passwords.
• The data/database.json file contains gift ideas and purchases. You can start with the provided sample data or clear the arrays to start fresh.

Configure Default Language (Optional):

• Open the docker-compose.yml file.
• Change the DEFAULT_LANG environment variable to your preferred default language (fr or en).

environment:
- DEFAULT_LANG=en

Build and run the application:

docker-compose up --build -d

This command builds the Docker images for the API and the Nginx frontend, then starts both services in detached mode. 1.

Access the application: Open your web browser and navigate to http://localhost:8080. 1.

Stopping the application: To stop the running containers, execute:

docker-compose down

Project Structure

.
├── backend/
│   ├── Dockerfile          # Instructions to build the Node.js API image
│   ├── package.json
│   └── server.js           # The Express API server
├── data/
│   ├── database.json       # Stores gifts and ideas (persistent via volume)
│   └── users.json          # Stores members and credentials (persistent via volume)
├── locales/
│   ├── en.json             # English translation file
│   └── fr.json             # French translation file
├── Dockerfile              # Instructions to build the Nginx frontend image
├── docker-compose.yml      # Orchestrates the api and nginx services
├── entrypoint.sh           # Script to inject environment variables at runtime
├── index.html
├── nginx.conf
├── app.js
└── style.css

API Usage & Endpoints

Authentication

All endpoints under /api/ are protected using HTTP Basic Authentication. You must provide valid user credentials (defined in data/users.json) with every request.

The frontend application handles this automatically after a successful login. For direct API interaction (e.g., with curl), you need to include the credentials.

Example Requests

Here are some examples using curl. Replace Alice:alice with valid credentials from your users.json file.

1. Get All Data (GET)

curl -u "Alice:alice" http://localhost:8080/api/data

2. Add a New Gift Idea (POST)

curl -u "Alice:alice" \
-X POST \
-H "Content-Type: application/json" \
-d '{
"title": "A good book",
"estimatedPrice": 25,
"targetMemberId": 2,
"creatorId": 1
}' \
http://localhost:8080/api/ideas

3. Delete a Purchased Gift (DELETE)

curl -u "Alice:alice" -X DELETE http://localhost:8080/api/gifts/201

Endpoint List

• GET /api/data: Fetches all application data.
• POST /api/ideas: Creates a new gift idea.
• PUT /api/ideas/:id: Updates an existing gift idea.
• DELETE /api/ideas/:id: Deletes a gift idea.
• POST /api/gifts: Creates a new purchased gift.
• PUT /api/gifts/:id: Updates an existing purchased gift.
• DELETE /api/gifts/:id: Deletes a purchased gift and its associated reimbursements.
• POST /api/gifts/:id/revert-to-idea: Converts a purchased gift back into an idea.
• PUT /api/status/:id: Updates a specific reimbursement status.

License

This project is licensed under the MIT License.