kratos-42 · kratos-42 · Aug 2, 2025 · Aug 2, 2025
diff --git 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.
 
-<p align="center">
-  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="200" alt="Nest Logo" /></a>
-</p>
+## 📋 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.
 
-  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
-    <p align="center">
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
-<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
-<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
-<a href="https://coveralls.io/github/nestjs/nest?branch=master" target="_blank"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#9" alt="Coverage" /></a>
-<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
-<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
-<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
-  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg"/></a>
-    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
-  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
-</p>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+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
@@ -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
+
+---