diff --git a/README.md b/README.md index 6f502ab..1698b9c 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,87 @@ -# vendomatic-api +# πŸͺ Vendomatic API -This project is the backend piece of software that compounds Vendomatic - a vending machine management software solution. +Backend API for the Vendomatic vending machine management system. Built with NestJS, TypeORM, and GraphQL. -

- Nest Logo -

+## πŸ“‹ Overview -[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456 -[circleci-url]: https://circleci.com/gh/nestjs/nest +A comprehensive dashboard/backoffice system for managing and monitoring vending machines, including machine management, product inventory, restocking operations, and maintenance tracking. -

A progressive Node.js framework for building efficient and scalable server-side applications.

-

-NPM Version -Package License -NPM Downloads -CircleCI -Coverage -Discord -Backers on Open Collective -Sponsors on Open Collective - - Support us - -

- +This API integrates with edge devices (Rust servers running on Raspberry Pi) deployed in vending machines to: +- Communicate with coin acceptors and bill validators via MDB protocol +- Update product prices in real-time on the vending hardware +- Monitor payment device status and transactions +- Collect telemetry data for operational insights -## Description +For detailed project features and roadmap, see [ROADMAP.md](./docs/ROADMAP.md). -[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository. +## πŸš€ Quick Start -## Installation +### Prerequisites +- Node.js 18+ +- PostgreSQL database +- Docker + +### Installation ```bash -$ yarn install +yarn install ``` -## Running the app +### Environment Setup +Create a `.env` file based on your configuration. -```bash -# development -$ yarn run start +### Development -# watch mode -$ yarn run start:dev +```bash +# Start development services +yarn docker -# production mode -$ yarn run start:prod +# Start application locally +yarn start:dev ``` -## Test +### Database Setup ```bash -# unit tests -$ yarn run test +# Run migrations +yarn migration:run +``` -# e2e tests -$ yarn run test:e2e +The API will be available at `http://localhost:3000/graphql` -# test coverage -$ yarn run test:cov -``` +## πŸ“š Available Scripts + +### Development +- `yarn start:dev` - Start development server with hot reload +- `yarn start:debug` - Start with debugging enabled +- `yarn docker` - Run with Docker Compose -## Support +### Database +- `yarn migration:run` - Run database migrations +- `yarn migration:generate` - Generate new migration +- `yarn migration:revert` - Revert last migration -Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support). +### Testing +- `yarn test` - Run all tests +- `yarn test:unit` - Run unit tests only +- `yarn test:e2e` - Run e2e tests only +- `yarn test:cov` - Run tests with coverage -## Stay in touch +### Code Quality +- `yarn lint:check` - Check linting issues +- `yarn lint:fix` - Fix linting issues +- `yarn format:check` - Check code formatting +- `yarn format:fix` - Fix code formatting +- `yarn type:check` - Run TypeScript type checking -- Author - [Kamil MyΕ›liwiec](https://kamilmysliwiec.com) -- Website - [https://nestjs.com](https://nestjs.com/) -- Twitter - [@nestframework](https://twitter.com/nestframework) +### Production +- `yarn build` - Build for production +- `yarn start:prod` - Start production server -## License +## πŸ› οΈ Tech Stack -Nest is [MIT licensed](LICENSE). +- **Framework**: NestJS +- **Database**: PostgreSQL with TypeORM +- **API**: GraphQL with Apollo Server +- **Language**: TypeScript +- **Testing**: Jest diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..8fe396d --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,170 @@ +# πŸ—ΊοΈ Vendomatic Roadmap + +## πŸ“Š Current Implementation Status + +### βœ… Implemented Features + +#### Core Infrastructure +- **NestJS Framework** - REST and GraphQL API foundation +- **Database Setup** - PostgreSQL with TypeORM migrations +- **Configuration Management** - Environment-based configuration +- **Testing Framework** - Jest setup for unit and e2e tests +- **Code Quality** - ESLint, Prettier, and pre-commit hooks + +#### Machine Management (Partial) +- **Spot Entity** - Basic machine/location model (`src/spot/`) + - Create, read, update, delete operations + - Fields: id, name, location, timestamps + - GraphQL API endpoints + +### 🚧 In Development +Currently implementing the foundational machine management system. + +--- + +## 🎯 Planned Features (Based on User Stories) + +### 🏒 Machine Management +- [ ] **US001** - Enhanced machine creation with validation +- [ ] **US002** - Location change tracking with history +- [ ] **US003** - Machine deactivation with data retention +- [ ] Machine status monitoring +- [ ] Machine configuration management + +### πŸ›οΈ Product Management +- [ ] **US004** - Product catalog and machine-specific products +- [ ] **US005** - Location-based pricing system +- [ ] **US006** - Product removal with stock alerts +- [ ] Product capacity and stock tracking +- [ ] Price history tracking + +### πŸ“¦ Restocking Operations +- [ ] **US007** - Restocking registration system +- [ ] **US008** - Waste/disposal tracking +- [ ] **US009** - Restocking history and reporting +- [ ] Employee association with operations +- [ ] Money collection tracking + +### πŸ”§ Maintenance Management +- [ ] **US010** - Maintenance activity logging +- [ ] **US011** - Maintenance history and analytics +- [ ] Preventive maintenance scheduling +- [ ] Technician assignment system +- [ ] Photo/document attachments + +### πŸ‘₯ User Management +- [ ] Authentication and authorization system +- [ ] Role-based access control (Admin, Employee, Technician) +- [ ] User activity auditing +- [ ] Permission management + +### πŸ“Š Analytics & Reporting (Future) +- [ ] **US012** - Sales statistics and charts +- [ ] **US013** - Profitability analysis +- [ ] **US014** - Waste pattern analysis +- [ ] Real-time dashboards +- [ ] Export functionality + +--- + +## πŸ—οΈ Technical Architecture Roadmap + +### Database Schema Evolution +- [ ] Product entities and relationships +- [ ] User management tables +- [ ] Restocking operation tracking +- [ ] Maintenance records +- [ ] Audit logging system + +### API Development +- [ ] Authentication middleware +- [ ] Role-based authorization guards +- [ ] File upload handling (photos/documents) +- [ ] Real-time subscriptions (GraphQL) +- [ ] API rate limiting and security + +### Frontend Integration +- [ ] API documentation (GraphQL schema) +- [ ] Error handling standardization +- [ ] Pagination and filtering +- [ ] Data validation schemas + +### Hardware Integration (Edge Devices) +- [ ] Edge device communication API endpoints +- [ ] Real-time price synchronization with vending machines +- [ ] Payment device status monitoring +- [ ] Transaction event handling from MDB devices +- [ ] Telemetry data collection and aggregation + +--- + +## πŸ”Œ Hardware Architecture (Planned) + +### Edge Device Setup +Each vending machine will have: +- **Raspberry Pi Zero 2W** running custom Rust server +- **4G LTE HAT** for cellular connectivity (Waveshare SIM7600 or similar) +- **MDB-RS232 Interface** for payment device communication +- **USB-to-Serial Adapter** for protocol bridging + +### Communication Flow +``` +Vending Machine Hardware ← MDB Protocol β†’ Raspberry Pi (Rust) ← 4G/API β†’ Vendomatic Backend +``` + +### Edge Device Responsibilities +- Translate MDB protocol to/from API calls +- Push price updates from backoffice to vending machine +- Buffer transactions in SQLite during connectivity issues +- Monitor payment device health +- Report telemetry and diagnostics + +--- + +## πŸ“ˆ Implementation Phases + +### Phase 1: Foundation (Current) +- βœ… Project setup and infrastructure +- βœ… Basic machine/spot management +- 🚧 Database schema design + +### Phase 2: Core Features +- User authentication system +- Complete machine management +- Product catalog and inventory + +### Phase 3: Operations +- Restocking workflow +- Maintenance tracking +- Basic reporting + +### Phase 4: Analytics +- Advanced reporting +- Data visualization +- Performance optimization + +### Phase 5: Advanced Features +- Real-time monitoring +- Mobile app support +- Advanced analytics + +--- + +## πŸ”„ Next Immediate Steps + +1. **Complete Spot/Machine Model** + - Add status field (active/inactive) + - Add configuration fields + - Implement validation + +2. **User Authentication** + - JWT implementation + - Role-based access + - User entity creation + +3. **Product Management** + - Product entity design + - Machine-product relationships + - Pricing system + +---