# hexya-addons/base architecture

> Architecture diagram of the GitHub repository hexya-addons/base, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hexya-addons/base
- Repository: https://github.com/hexya-addons/base

## Overview

##### Project type and purpose
- This is a Go-based “kernel” library for Hexya (an ERP-style framework). It provides the foundational data models, services (cron, queue, security, sequence), resource definitions (XML), seed/demo data (CSV), static assets, and internationalization (PO files).

##### File structure
- Top-level Go files: individual modules (bank.go, company.go, user.go, etc.)
- Directories:
- basetypes: core Go types
- i18n: translation PO files
- data & demo: CSV seed/demo data
- resources: XML view/menu/field definitions
- static: web assets
- tests alongside each module
- Config/build: go.mod, .travis.yml, run_tests.sh

##### Key insights from README
- “The kernel of Hexya, needed for all installation”
- No external microservices—everything is packaged as a Go library that plugs into the Hexya runtime.

##### Main components
A. Go Kernel (library)
- Sub-components (packages/modules):
- basetypes
- model mixins (image_mixin, model_mixin, translation)
- business modules (bank, company, country, partner, user, group, currency)
- services (cron, queue, security, sequence, attachment)
B. Data Loaders
- CSV Loader: data/ & demo/ → database seed
- XML Resource Loader: resources/ → UI metadata & menus
- i18n Loader: i18n/*.po → translation tables
C. Database
- Stores all model tables, sequences, queue jobs, cron schedules
D. Runtime Services
- Cron Scheduler
- Queue Worker
- Sequence Generator
E. Web UI Layer
- Serves metadata-driven UI based on loaded XML resources
- Serves static assets (static/src/img, description)
F. CLI/Test Runner
- run_tests.sh, go test integration

##### Relationships and interactions
- On startup, the Kernel:
1. Registers all Go modules (models + services) with the Hexya core.
2. Loads XML resources → builds UI metadata.
3. Loads CSV seed/demo data → populates DB.
4. Loads PO files → populates translation tables.
- At runtime:
- Web requests → Web UI Layer → Model API → DB
- Cron Scheduler → triggers module cron functions → writes to DB or queue
- Queue Worker → processes queued tasks via module handlers
- Sequence Generator → ensures unique IDs for models

##### Architectural patterns & design principles
- Modular plugin architecture: each .go file is a self-contained module
- Metadata-driven UI: XML resources describe views and menus
- Separation of concerns:
- Data definitions (Go structs + CSV)
- UI definitions (XML resources)
- Translations (PO)
- Static web assets
- Background services (cron / queue)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Go Kernel Library
    subgraph "Go Kernel Library"
        Kernel["Go Kernel Library"]:::code
        Basetypes["Core Types (basetypes)"]:::code
        subgraph "Model Mixins"
            ImageMixin["ImageMixin"]:::code
            ModelMixin["ModelMixin"]:::code
            TranslationMixin["Translation Mixin"]:::code
        end
        subgraph "Business Modules"
            Bank["Bank Module"]:::code
            Company["Company Module"]:::code
            Country["Country Module"]:::code
            Partner["Partner Module"]:::code
            User["User Module"]:::code
            Group["Group Module"]:::code
            Currency["Currency Module"]:::code
        end
        subgraph "Core Services"
            CronService["Cron Service"]:::service
            QueueService["Queue Service"]:::service
            SecurityService["Security Service"]:::service
            SequenceService["Sequence Generator"]:::service
            AutovacuumService["Autovacuum"]:::service
        end
    end

    %% Data Loaders
    subgraph "Data Loaders"
        CSV["CSV Loader"]:::loader
        XML["XML Resource Loader"]:::loader
        I18n["i18n Loader"]:::loader
    end

    %% Database
    Database[(Database)]:::db

    %% Runtime Services
    subgraph "Runtime Services"
        CronScheduler["Cron Scheduler"]:::service
        QueueWorker["Queue Worker"]:::service
        SeqGen["Sequence Generator"]:::service
    end

    %% Web UI Layer
    subgraph "Web UI Layer"
        UI["Metadata-driven UI"]:::ui
        StaticAssets["Static Assets"]:::ui
    end

    %% CLI/Test Runner
    CLI["CLI/Test Runner"]:::cli

    %% Connections - Startup
    Kernel -->|registers modules| Basetypes
    Kernel -->|registers mixins| ImageMixin
    Kernel -->|registers mixins| ModelMixin
    Kernel -->|registers mixins| TranslationMixin
    Kernel -->|registers modules| Bank
    Kernel -->|registers modules| Company
    Kernel -->|registers modules| Country
    Kernel -->|registers modules| Partner
    Kernel -->|registers modules| User
    Kernel -->|registers modules| Group
    Kernel -->|registers modules| Currency
    Kernel -->|registers services| CronService
    Kernel -->|registers services| QueueService
    Kernel -->|registers services| SecurityService
    Kernel -->|registers services| SequenceService
    Kernel -->|registers services| AutovacuumService

    Kernel -->|loads seed data| CSV
    Kernel -->|loads UI metadata| XML
    Kernel -->|loads translations| I18n

    CSV -->|seed data| Database
    XML -->|UI metadata| Database
    I18n -->|translations| Database

    %% Runtime interactions
    UI -->|"HTTP request"| Kernel
    Kernel -->|"model API"| Database
    CronScheduler -->|"triggers cron"| Kernel
    QueueWorker -->|"processes tasks"| Kernel
    SeqGen -->|"generates IDs"| Kernel

    CronScheduler -->|"cron data"| Database
    QueueWorker -->|"queue jobs"| Database
    SeqGen -->|"sequence data"| Database

    StaticAssets -->|"serves assets"| UI

    CLI -->|runs tests| Kernel
    CLI -->|invokes| Database

    %% Click Events
    click Kernel "https://github.com/hexya-addons/base/blob/master/000hexya.go"
    click Basetypes "https://github.com/hexya-addons/base/blob/master/basetypes/basetypes.go"
    click ImageMixin "https://github.com/hexya-addons/base/blob/master/image_mixin.go"
    click ModelMixin "https://github.com/hexya-addons/base/blob/master/model_mixin.go"
    click TranslationMixin "https://github.com/hexya-addons/base/blob/master/translation.go"
    click Bank "https://github.com/hexya-addons/base/blob/master/bank.go"
    click Company "https://github.com/hexya-addons/base/blob/master/company.go"
    click Country "https://github.com/hexya-addons/base/blob/master/country.go"
    click Partner "https://github.com/hexya-addons/base/blob/master/partner.go"
    click User "https://github.com/hexya-addons/base/blob/master/user.go"
    click Group "https://github.com/hexya-addons/base/blob/master/group.go"
    click Currency "https://github.com/hexya-addons/base/blob/master/currency.go"
    click CronService "https://github.com/hexya-addons/base/blob/master/cron.go"
    click QueueService "https://github.com/hexya-addons/base/blob/master/queue.go"
    click SecurityService "https://github.com/hexya-addons/base/blob/master/security.go"
    click SequenceService "https://github.com/hexya-addons/base/blob/master/sequence.go"
    click AutovacuumService "https://github.com/hexya-addons/base/blob/master/autovacuum.go"
    click CSV "https://github.com/hexya-addons/base/tree/master/data/"
    click XML "https://github.com/hexya-addons/base/tree/master/resources/"
    click I18n "https://github.com/hexya-addons/base/tree/master/i18n/"
    click StaticAssets "https://github.com/hexya-addons/base/tree/master/static/"
    click CLI "https://github.com/hexya-addons/base/blob/master/run_tests.sh"

    %% Styles
    classDef code fill:#cce5ff,stroke:#004085,color:#004085;
    classDef loader fill:#d4edda,stroke:#155724,color:#155724;
    classDef service fill:#fff3cd,stroke:#856404,color:#856404;
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef ui fill:#f5e6ff,stroke:#5f259f,color:#5f259f;
    classDef cli fill:#fde2e2,stroke:#ba2d0b,color:#ba2d0b;
```
