Module Manifest

The manifest.yaml file defines module metadata and configuration. (manifest.json is also accepted for backwards compatibility, but every shipped module uses YAML.)

Basic Structure

name: Human Resources
identifier: hr
category: module_category_hr
description: Employee and contract management
dependencies:
- core
- contacts
icon: Users
version: '1.0'

Fields Reference

Required Fields

Field	Type	Description
name	string	Human-readable module name
identifier	string	Unique identifier (snake_case, no spaces)
dependencies	array	List of required module identifiers

Optional Fields

Field	Type	Default	Description
description	string	""	Short description shown in module list
category	string	category identifier (no default — must resolve to an existing ModuleCategory)	Module category for grouping
icon	string	""	Lucide icon name (without “Icon” prefix)
version	string	—	Free-text version label (informational only — not used for upgrade ordering)
implicit	boolean	false	Auto-install once all dependencies are installed
image	string	—	Path to logo/thumbnail (required for Integration and Theme modules)
integration_category	string	—	For integration modules: the integration category (e.g. Online Payment, Messaging)
cron_sync_method	string	—	For integration modules: method name run by the sync cron
static_paths	array	—	Static subdirectories under static/ to serve (e.g. [css, js, images])

The module’s display color is computed deterministically from its name at load time; a color key in the manifest is ignored. There are no author, website, or license manifest keys — the loader does not read them.

Categories

Standard categories for grouping modules:

Category	Description
module_category_sales	Sales & CRM
module_category_crm	Customer Relationship
module_category_inventory	Inventory & Stock
module_category_accounting	Accounting & Finance
module_category_hr	Human Resources
module_category_manufacturing	Manufacturing
module_category_website	Website & E-commerce
module_category_productivity	Productivity Tools
module_category_marketing	Marketing
module_category_services	Services
module_category_other	Uncategorized

Icons

Icons use Lucide Icons. Use the icon name without any prefix. Common examples:

Icon	Name
Users	Users
Shopping Cart	ShoppingCart
Chart	ChartBar
Calendar	Calendar
Mail	Mail
Settings	Settings
Box	Box
Building	Building
Truck	Truck
Credit Card	CreditCard
Newspaper	Newspaper
Globe	Globe
Folder Kanban	FolderKanban
Palette	Palette

Dependencies

Basic Dependencies

{
  "dependencies": ["core", "contacts"]
}

Dependency Resolution

• Dependencies are installed automatically before the dependent module
• Circular dependencies are not allowed
• core is implicitly required

Order of Loading

1. Modules without dependencies (usually core)
2. Modules depending only on loaded modules
3. Repeat until all modules loaded

Implicit (Auto-Install) Modules

Set implicit: true to make a module auto-install itself the moment all of its dependencies are installed — without ever being explicitly selected. This is the “bridge” pattern: glue modules that should appear only when two apps are both present.

name: Sales - Inventory Bridge
identifier: sale_inventory
dependencies:
  - sale
  - inventory
implicit: true

With the manifest above, sale_inventory stays uninstalled while only sale is present, and installs automatically the instant inventory is also installed (and vice-versa). You never tick it in the module list.

How it works:

• After any install / module-list refresh, the engine scans every implicit: true module that is Not Installed and installs those whose entire dependency list is already satisfied.
• It cascades. Auto-installing one implicit module re-runs the scan, so an implicit module whose deps are only completed by another implicit install gets picked up in the same pass.
• It is purely additive — implicit modules are never auto-uninstalled when a dependency is later removed; that follows normal uninstall rules.

Version

The version key is a free-text label (shipped modules use values like '1.0'). It is informational only. Schema/data migrations are not driven by any version — they replay off an append-only change-id ledger (see Migrations & Upgrades), so this key does not affect upgrades.

Complete Example

name: Project Management
identifier: project
category: module_category_services
description: Manage projects, tasks, and timesheets
dependencies:
- core
- contacts
- hr
icon: FolderKanban
version: '2.1'

Best Practices

1. Use descriptive names - Clear, concise module names
2. Choose appropriate icons - Icon should represent the module’s purpose
3. Minimize dependencies - Only depend on what you actually need

Next Steps

• Data Files - Load initial data
• Creating Modules - Full module tutorial