huesos

Base for creating shop chat-robots using Web App technology for Telegram

Functions

1. Tree-structured catalog
2. Product cards with images carousel (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)
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

Integrations

Import

Methods for importing products into the shop

1. Excel-file (products and categories)

Images download

Methods of transferring images when importing products into the shop

1. Yandex.Disk (russian) (API)

Delivery companies

Companies that deliver products from the shop

1. CDEK (russian) (API) (PHP library)

Acquiring companies

Companies that provide acquiring for the shop

1. Robokassa (russian) (no swift) (API)

Dependencies

1. PHP 8.4
2. Composer (php package manager)
3. MINIMAL (PHP framework)
4. Twig (HTML templater)
5. Zanzara (Telegram framework + ReactPHP)
6. ArangoDB (non-relational database)
7. NGINX (web server) (can be replaced)
8. SystemD (service manager) (can be replaced)

You can find other dependencies in the file /composer.json

Installation

AnangoDB

1. Configure unix-socket
   

Edit the file /etc/arangodb3/arangod.conf
endpoint = tcp://127.0.0.1:8529 -> endpoint = unix:///var/run/arangodb3/arango.sock (this will disable the web panel)

To make the web panel work, you can add this to the NGINX server settings:

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)

1. Configure TCP (instead of unix-socket)
   

Edit the file /etc/arangodb3/arangod.conf
endpoint = tcp://127.0.0.1:8529 -> endpoint = tcp://0.0.0.0:8529

Edit the file mirzaev/huesos/system/settings/arangodb.php
unix:///var/run/arangodb3/arango.sock -> tcp://YOUR_IP_ADDRESS:8529 (it is slow and not secure)

---

2. Create a Graph with the specified values
   Name: catalog
   

• Relation 1
  edgeDefinition: entry
  fromCollections: category, product
  toCollections: category

• Relation 2
  edgeDefinition: reservation
  fromCollections: product
  toCollections: cart

---

3. Create a Graph with the specified values
   Name: users
   

• Relation 1
  edgeDefinition: connect
  fromCollections: cart, session
  toCollections: account, session
  

• Orphan Collections
  product

---

4. Create indexes for the "product" collection
   Type: "Inverted Index"
   Fields: name.ru
   Analyzer: "text_ru"
   Search field: true
   Name: name_ru
   
   

Add indexes for all search parameters and for all languages (search language is selected based on the user's language,
otherwise from the default language specified in the active settings from settings collection document)

See fields in the mirzaev/arming_bot/models/product
name.ru, description.ru and compatibility.ru

---

5. Create a View with the specified values
   type: search-alias (you can also use "arangosearch")
   name: products_search
   indexes:
   
   

You can copy an example of view file from here: /examples/arangodb/views/products_search.json

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

NGINX

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

2. Add support for javascript modules
   Edit the file /etc/nginx/mime.types
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

Execute: sudo cp huesos.service /etc/systemd/system/huesos.service && sudo chmod +x /etc/systemd/system/huesos.service

before you execute the command think about what it does and whether the paths are specified correctly
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

Make sure you have a menu collection (can be created automatically)
You can copy a clean menu documents without comments from here: /examples/arangodb/collections/menu

{
  "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

Make sure you have a settings collection (can be created automatically) and at least one document with the "status" parameter set to "active"
You can copy a clean settings document without comments from here: /examples/arangodb/collections/settings.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

Make sure you have a suspension collection (can be created automatically)
You can copy a clean suspension document without comments from here: /examples/arangodb/collections/suspension.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"
    }
}

Used by

List of projects created on the basis of huesos

• ARMING @arming_bot
  Russian weapons tuning shop (repository)