# MALO - UGO Backoffice POS System Architecture

## Project Overview

MALO is a comprehensive point-of-sale (POS) and business management system for restaurants, cafes, and retail establishments. It handles sales, inventory, purchasing, employee management, and financial reporting. Primary Language: Croatian (HR). Current Version: OrderMan 393+ (AllOrder UUID). Git Branch: feature/orderman393_blokiranje_stola

## Technology Stack

- CakePHP 1.3.x (MVC framework)
- PHP 5.x
- MySQL (InnoDB)
- Apache with mod_rewrite
- jQuery, NyroModal, jQuery Datepicker
- FPDF/FPDI (PDF generation)
- QR Code Library
- PhantomJS, GeckoDriver (browser automation)

## High-Level Architecture

The application follows standard CakePHP MVC pattern with 28+ controllers, 30 domain models, and views organized by controller.

**Data Flow:** Request → Router → Controller → beforeFilter() → ACL Check → Model → Database → View → Response

## Database Schema (30 Models)

### Core Tables
- **User & Access:** users, user_levels, acl_* tables
- **Sales & Orders:** sales, sale_items, retail_items, orders, tables, table_groups
- **Products:** products, product_groups, product_items, articles, article_groups
- **Receiving:** receivings, receiving_items, receiving_orders, receiving_order_items
- **Configuration:** tax_groups (25%, 3%), payment_types, printers, customers, settings, notes

**Database:** localhost:3306, database=malo, user=root, encoding=UTF-8

## Key Directories

- /app/config/ - Database, routes, project settings
- /app/controllers/ - 28+ domain controllers (Sales, Products, Reports, etc.)
- /app/models/ - 30 domain models with validation and relationships
- /app/views/ - Templates by controller with elements for reusable components
- /app/libs/ - FPDF, QRCode libraries
- /app/webroot/ - Public files (CSS, JS, images)
  - /iso/ - Legacy standalone reporting system
  - /files/ - Generated documents
- /app/tmp/ - Logs, sessions, cache
- /cake/ - CakePHP framework

## Configuration Files

**app/config/project.php:** Language=hr, Currency=EUR, Tax1=25%, Tax2=3%
**app/config/core.php:** Debug=0, Logging enabled, UTF-8, ACL=DbAcl
**app/config/database.php:** MySQL connection to malo database
**app/config/routes.php:** Root=/articles, standard RESTful routing

## Important Patterns

### Models
- Display Field: Auto-updated for list views
- Audit Fields: created_by, modified_by
- Containable Behavior: Query optimization
- Validation Rules: Extensive on all models

### Controllers  
- beforeFilter(): ACL setup, auth checks
- Pagination: Built-in on index
- Filter Component: Dynamic search/filtering
- AJAX Support: RequestHandler detection
- Flash Messages: User feedback

### Views
- Element-based UI: header, footer, menu
- Filter Forms: Search interface
- Modal Dialogs: NyroModal
- Form Helpers: CakePHP generators

### Naming Conventions
- Models: Singular CamelCase (Product, Sale)
- Controllers: Plural + Controller (ProductsController)
- Views: snake_case (add.ctp, index.ctp)
- Tables: Plural snake_case (products, sales)
- Foreign Keys: {model_id} convention

## Legacy Reporting System (/iso)

Standalone PHP reporting in app/webroot/iso/:
- default.php - Main reporting interface
- print.php - PDF generation
- _all_reports.php - All reports
- my/ - Helper functions (database, HTML, logging)

## Frontend Architecture

- jQuery: DOM manipulation, AJAX
- NyroModal: Modal dialogs
- jQuery Datepicker: Date selection
- common.js: Multi-submit prevention, flash messages
- CSS: cake.generic, app.css, reporting styles

## Build & Run Instructions

### Prerequisites
- Apache with mod_rewrite
- PHP 5.x with MySQL
- MySQL 5.5+
- WAMP stack

### Installation
1. Extract to /wamp/www/malo
2. Configure app/config/database.php
3. Create database: CREATE DATABASE malo CHARACTER SET utf8;
4. Set permissions on app/tmp/, app/webroot/files/
5. Configure Apache document root

### Running
- Access: http://localhost/malo/
- Default: /articles
- Login: /users/login
- Configure settings after login

### No Automated Tests
- Manual testing only
- PhantomJS for reports, not testing

## Development Conventions

- Code: PHP 4/5 style (mixed procedural/OOP)
- Security: Auth component, ACL-based access
- SQL: Direct queries (mysql_* - SQL injection risk)
- i18n: Croatian (hr_HR) locale
- Logging: error.log, debug.log in app/tmp/logs/

## Recent Development

### Current Branch
feature/orderman393_blokiranje_stola - Table blocking feature

### Recent Commits
1. 7b31a13 (2023-10-13) - Final AllOrder with UUID
2. 01cb595 (2023-07-10) - OrderMan 392/AllOrder
3. 347e76d (2023-06-22) - Open tables, normative colors
4. 2bd60d2 (2023-06-20) - OrderMan 391, payments
5. e6aa36c (2023-06-06) - Initial OrderMan

## Known Limitations

1. Legacy PHP (mysql_* deprecated)
2. CakePHP 1.3 (very old)
3. No automated tests
4. Mixed architecture (CakePHP + /iso)
5. No prepared statements (SQL injection risk)
6. No REST API
7. Large controllers (reports: 134KB)
8. File-based sessions
9. No asset pipeline

## Deployment Considerations

- WAMP stack (Apache, MySQL, PHP 5.x)
- mod_rewrite enabled
- Writable: app/tmp/, webroot/files/
- Single database: malo
- No migration system
- InnoDB recommended
- Backup: database, files, sessions, config

## Conclusion

MALO is a mature POS system for Croatian restaurants/retail built on CakePHP 1.3 MVC. It provides comprehensive sales, inventory, receiving, reporting, and user management. The parallel /iso reporting system indicates incremental development over many years. Consider modernization: PHP upgrade, framework upgrade, automated tests, REST API, and frontend modernization.
