Minimart and Voucher System The Minimart and Voucher System is a web-based application designed for the Muhammadiyah Welfare Home (MWH). This platform empowers Residents (users) to request products and earn vouchers, while providing Admins (staff) with robust management and reporting tools.

Table of Contents Project Overview Key Features For Residents For Admins Tech Stack Project Structure Prerequisites Installation & Setup Backend Setup Frontend Setup Environment Variables Database Migrations Running the Application Testing Future Enhancements Contributing License Contact

1. Project Overview Muhammadiyah Welfare Home (MWH) is dedicated to providing care and support for boys residing on its campus, creating a nurturing environment to help them thrive. This Minimart and Voucher System aims to streamline requests for products, ensure transparent voucher allocation, and supply administrators with powerful management and reporting features.

The system was developed as part of Hack4Good, where participants collaborated to build a prototype that addresses real-world constraints and can be iteratively enhanced to maximize impact for MWH and its residents.

2. Key Features For Residents User-Friendly Dashboard: View voucher balances, transaction history, and available products. Simple Requests: Request items from the minimart or place preorders for out-of-stock products. Secure Login: Secure registration and login system with optional password reset (via mobile or email, depending on your configuration). For Admins User Management: Add new users, suspend accounts, and reset passwords. Voucher Approvals: Approve or reject voucher tasks and product requests, with status updates and audit tracking. Inventory Tracking: Maintain product inventory with an audit log for accountability. Reporting: Generate weekly requests, inventory summaries, and other analytics for better decision-making.
3. Tech Stack This project leverages a modern, modular approach. Below is an example stack; modify as necessary for your implementation:

Backend: Node.js / Express or Python / Django / Flask Frontend: React.js / Vue.js / Angular Database: PostgreSQL / MySQL / MongoDB Authentication: JSON Web Tokens (JWT) or session-based authentication Hosting: Could be hosted on any cloud platform (AWS, Azure, Heroku, etc.) 4. Project Structure A typical folder structure might look like the following (adapt to your actual files/folders):

java Copy Minimart-Voucher-System/ ├── backend/ │ ├── config/ │ ├── controllers/ │ ├── models/ │ ├── routes/ │ ├── tests/ │ ├── app.js │ └── package.json ├── frontend/ │ ├── public/ │ ├── src/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── services/ │ │ └── App.js │ ├── package.json │ └── README.md ├── docs/ │ ├── design-docs.md │ └── api-spec.md ├── .env.example ├── README.md └── LICENSE Note: This README is placed at the root, containing general instructions. The backend and frontend directories each may have their own additional README files with more granular details.

5. Prerequisites Node.js (v14+ recommended) npm (v6+ recommended) or yarn Git (to clone the repository) Database (PostgreSQL/MySQL/MongoDB, depending on your choice) (Optional) Python 3 (if the backend is built in Django/Flask instead of Node.js)
6. Installation & Setup Backend Setup Clone the repository

bash Copy git clone https://github.com//Minimart-Voucher-System.git cd Minimart-Voucher-System/backend Install Dependencies

bash Copy npm install or

bash Copy yarn install Create your .env file Copy the .env.example into a new file .env, then update the variables (see Environment Variables).

Frontend Setup Navigate to the frontend directory

bash Copy cd ../frontend Install Dependencies

bash Copy npm install or

bash Copy yarn install Configuration

Update any environment variables or API endpoints in the frontend configuration (e.g., .env file or config files) to point to your backend server. 7. Environment Variables In the root of the backend directory, you have an .env.example (or .env) file that includes essential configurations. Example variables might include:

makefile Copy

Backend environment variables

PORT=3001 DATABASE_URL=postgres://user:password@host:port/database JWT_SECRET=supersecretkey EMAIL_SERVICE_API_KEY=xxxxxx SENDGRID_API_KEY=xxxxxx

Frontend environment variables

REACT_APP_API_ENDPOINT=http://localhost:3001 Remember not to commit your actual secrets to GitHub or any public repository.

8. Database Migrations If your framework supports migrations (e.g., using sequelize or Django migrations):

Initialize database bash Copy npx sequelize db:create or the relevant command for your chosen ORM. Run migrations bash Copy npx sequelize db:migrate or: bash Copy python manage.py migrate (depending on your setup) Make sure the database is properly configured in your .env file before running migrations.

9. Running the Application Start the Backend

bash Copy cd backend npm start or

bash Copy yarn start This should start the backend server at http://localhost:3001 (or whichever port you’ve configured).

Start the Frontend

bash Copy cd ../frontend npm start or

bash Copy yarn start This typically starts the frontend development server at http://localhost:3000.

Access the Application

Frontend: Go to http://localhost:3000. Backend: API endpoints can be tested on http://localhost:3001/api/.... 10. Testing Backend Tests From the backend folder, run:

bash Copy npm test or

bash Copy yarn test This should execute all test scripts (e.g., using Jest, Mocha, or PyTest).

Frontend Tests From the frontend folder, run:

bash Copy npm test or

bash Copy yarn test This typically runs tests using Jest and React Testing Library (if you’re using React).

Integration Testing You may implement additional integration or end-to-end tests using Cypress, Selenium, or Playwright.

11. Future Enhancements The current system is a prototype that focuses on the Minimart and Voucher workflow. Planned future enhancements include:

Auctions / Bidding Feature: Users can bid on special items using their vouchers. Mobile App Integration: A mobile application for iOS/Android to further streamline user and admin interactions. Advanced Analytics: Data visualization tools for inventory forecasts and user behavior insights. Notification System: Real-time alerts for voucher approvals, inventory restocks, and system announcements. 12. Contributing We welcome contributions from the community. Please follow these steps to contribute:

Fork the project repository. Create a new branch (e.g., feature/amazing_feature). Commit changes with clear and concise messages. Push to your fork. Open a Pull Request against the main repository. All contributions will undergo a review to ensure quality and maintainability.

13. License This project is licensed under the MIT License. You are free to use, modify, and distribute this software as outlined in the license terms.