huesos/README.md

# huesos
Base for creating shop chat-robots using Web App technology for ![Telegram](https://telegram.org)

## Functions
1. Tree-structured catalog
2. Product cards with images carousel based on ![mirzaev/hotline.mjs](https://git.svoboda.works/mirzaev/hotline.mjs)
3. Cart (CRUD with limits and session binding)
4. Saving user data (and session) for all devices
5. Deliveries settings (with interactive maps and automatic geolocation detection on smartphones)
6. Real time price generation
7. Interface according to all Telegram standards
8. Public offer, dynamic settings and suspensions
9. Multi-language and easy to add new languages
10. Multi-currency and easy to add new currencies
11. Loading products and categories from an excel-file with automatic updating of existing ones
12. Flag authorization system, separate access for testers
13. Sending the generated order directly to the chat-robot
14. Intelligent search by titles, descriptions and other parameters (Levenshtein algorithm + separate settings for different languages)
15. Asynchronous chat-robot and Web App based on dynamic queries (AJAX)
16. Modern non-relational database ready for scaling and integration with third-party CRM
17. Fully documented code in English
18. Customizable menu buttons
19. Responsive design with built-in Telegram buttons and haptic functions
20. Automatic download and compression of images in 4 sizes (currently only from Yandex.Disk, but the system is ready to add new sources)
21. Commercially approved fonts and pure CSS icons
22. Product filter panel using pure CSS
23. Damper technology on all user interaction functions (![mirzaev/damper.mjs](https://git.svoboda.works/mirzaev/damper.mjs))
24. Two-step registration system (entering other data after creating an order)
25. Delivery company selection system (ready for scaling)
26. Acquiring company selection system (ready for scaling)
27. Sending paid orders to the operators chat with the customer contacts

## Dependencies
1. ![PHP 8.4](https://www.php.net/releases/8.4/en.php)
2. ![MINIMAL](https://git.svoboda.works/mirzaev/minimal) (PHP framework)
3. ![Twig](https://twig.symfony.com/) (HTML templater)
4. ![Zanzara](https://github.com/badfarm/zanzara) (Telegram framework + ReactPHP)
5. ![ArangoDB](https://docs.arangodb.com/3.11/about-arangodb/) (non-relational database)
6. ![NGINX](https://nginx.org/en/) (web server) *(can be replaced)*
7. ![SystemD](https://systemd.io/) (service manager) *(can be replaced)*
8. ![Composer](https://getcomposer.org/) (php package manager)

<small>You can find other dependencies in the file `/composer.json`</small>

## Installation

### AnangoDB

1. **Configure unix-socket**<br>
<br>
Edit the file `/etc/arangodb3/arangod.conf`<br>
`endpoint = tcp://127.0.0.1:8529` -> `endpoint = unix:///var/run/arangodb3/arango.sock` (this will disable the web panel)<br>
<br>
To make the web panel work, you can add this to the NGINX server settings:
```lua
server {
    ...

    server_name arangodb.domain.zone;

    ...

    allow YOUR_IP_ADDRESS;
    allow 192.168.1.1/24;
    allow 127.0.0.1;
    deny all;

    # ArangoDB
    location / {
        proxy_pass http://arangodb;
    }
}

upstream arangodb {
    server unix:/var/run/arangodb3/arango.sock;
}
```
![here is my solution for "permission denied" problem on Ubuntu (accepted by ArangoDB maintainer)](https://github.com/arangodb/arangodb/issues/17302)<br>

1. **Configure TCP (instead of unix-socket)**<br>
<br>
Edit the file `/etc/arangodb3/arangod.conf`<br>
`endpoint = tcp://127.0.0.1:8529` -> `endpoint = tcp://0.0.0.0:8529`<br>
<br>
Edit the file `mirzaev/huesos/system/settings/arangodb.php`<br>
`unix:///var/run/arangodb3/arango.sock` -> `tcp://YOUR_IP_ADDRESS:8529` (it is slow and not secure)<br>
---
2. **Create a Graph with the specified values**<br>
<br>
**Name:** catalog<br>

* Relation 1<br>
**edgeDefinition:** entry<br>
**fromCollections:** category, product<br>
**toCollections:** category

* Relation 2<br>
**edgeDefinition:** reservation<br>
**fromCollections:** product<br>
**toCollections:** cart
---
3. **Create a Graph with the specified values**<br>
<br>
**Name:** users<br>

* Relation 1<br>
**edgeDefinition:** connect<br>
**fromCollections:** cart, session<br>
**toCollections:** account, session<br>
<br>
**Orphan Collections:** product
---
4. **Create indexes for the "product" collection**<br>
<br>
**Type:** "Inverted Index"<br>
**Fields:** name.ru<br>
**Analyzer:** "text_ru"<br>
**Search field:** true<br>
**Name:** name_ru<br>
<br>
*Add indexes for all search parameters and for all languages (search language is selected based on the user's language, <br>
otherwise from the default language specified in the active settings from **settings** collection document)*<br>
<br>
*See fields in the `mirzaev/arming_bot/models/product`<br>
**name.ru**, **description.ru** and **compatibility.ru***<br>
---
5. **Create a View with the specified values**
**type:** search-alias (you can also use "arangosearch")<br>
**name:** **product**s_search<br>
**indexes:**<br>
<br>
You can copy an example of view file from here: `/examples/arangodb/views/products_search.json`

```json
"indexes": [
    {
      "collection": "product",
      "index": "title_ru" # THIS IS AN EXAMPLE
    }
  ]
```

### NGINX

1. **Create a NGINX server**<br>
You can copy an example of server file from here: `/examples/nginx/server.conf`

2. **Add support for javascript modules**<br>
Edit the file `/etc/nginx/mime.types`<br>
`application/javascript js;` -> `application/javascript js mjs;`

### SystemD (or any alternative you like)
You can copy an example of systemd file from here: `/examples/systemd/huesos.service`<br>
<br>
**Execute:** `sudo cp huesos.service /etc/systemd/system/huesos.service && sudo chmod +x /etc/systemd/system/huesos.service`<br>
<br>
*before you execute the command think about **what it does** and whether the **paths** are specified correctly*<br>
*the configuration file is very simple and you can remake it for any alternative to SystemD that you like*


## Menu
Menu inside the Web App<br>
<br>
Make sure you have a **menu** collection (can be created automatically)<br>
You can copy a clean menu documents without comments from here: `/examples/arangodb/collections/menu`

```json
{
  "urn": "/", // Link
  "name": {
    "en": "Main page",
    "ru": "Главная страница"
  },
  "style": { // The `style` attribute
    "order": 0
  },
  "class": {},
  "icon": { // Icon from `/themes/default/css/icons`
    "style": { // The `style` attribute
      "rotate": "-135deg"
    },
    "class": "arrow circle" // Classes of the icon
  },
  "image": { // Image at the background @deprecated?
    "storage": null
  }
}
```

## Settings
Settings of chat-robot and Web App<br>
<br>
Make sure you have a **settings** collection (can be created automatically) and at least one document with the "status" parameter set to "active"<br>
You can copy a clean settings document without comments from here: `/examples/arangodb/collections/settings.json`

```json
{
    "status": "active",
    "project": {
        "name": "PROJECT"
    },
    "language": "en", // Will be converted to an instance of enumeration `mirzaev\arming_bot\models\enumerations\language`
    "currency": "usd", // Will be converted to an instance of enumeration `mirzaev\arming_bot\models\enumerations\currency`
    "company": {
        "identifier": null, // Example: "000000000000000" (string|null) (if `null` it will not be displayed)
        "tax": null, // Example: "000000000000" (string|null) (if `null` it will not be displayed)
        "name": null, // Example: "COMPANY" (string|null) (if `null` it will not be displayed)
        "offer": false, // Display the data of a public offer in the footer? (bool) (does not affect the `/offer` page generation)
        "sim": null, // Examples: "+7 000 000-00-00", "70000000000" (string|null) (if `null` it will not be displayed)
        "mail": null // Example: "name@domain.zone" (string|null) (if `null` it will not be displayed)
    }
}
```

## Suspensions
System of suspensions of chat-robot and Web App<br>
<br>
Make sure you have a **suspension** collection (can be created automatically)<br>
You can copy a clean suspension document without comments from here: `/examples/arangodb/collections/suspension.json`
```json
{
    "end": 1726068961, // Unixtime
    "targets": {
        "chat-robot": true, // Block chat-robot
        "web app": true // Block "Web App"
    },
    "access": {
        "tester": true, // Account with `"tester": true`
        "developer": true // Account with `"developer": true`
    },
    "description": {
        "ru": "Разрабатываю каталог, поиск и корзину",
        "en": "I am developing a catalog, search and cart"
    }
}
```