# Module Structure

How ARI modules are organized and how they integrate with the platform.

## Overview

Every ARI module follows a consistent structure. This makes modules predictable, easy to understand, and simple to share with others.

ARI ships with a **Module Template** (`modules-core/module-template/`) that serves as the reference implementation for all new modules. When you create a module with the `/ari-create-module` command, it uses this template as its foundation — so every module starts with the right patterns for authentication, database access, API routes, and security already in place.

## What a Module Contains

A module is a self-contained unit that can include any combination of:

- **Pages** — Full page support within the ARI workspace
- **API Routes** — Dedicated endpoints for the module's data operations
- **Database Tables** — Module-specific tables with row-level security
- **Dashboard Widgets** — Optional cards on the main ARI dashboard
- **Settings** — Per-module configuration options
- **Navigation** — Automatic sidebar integration

## Module File Structure

A typical module directory looks like this:

```
modules-core/my-module/
├── module.json              # Module manifest (required)
├── app/
│   └── page.tsx             # Main page component
├── api/                     # API route handlers
├── components/              # React components
├── hooks/                   # Custom React hooks
└── database/
    ├── schema.sql           # SQL schema (runs on every module enable)
    ├── schema.ts            # Drizzle ORM schema definitions
    ├── relations.ts         # Drizzle relation definitions
    └── uninstall.sql        # Cleanup SQL (manual-only, not auto-run)
```

**Important:** `schema.sql` runs every time a module is enabled, so it must be idempotent (use `CREATE TABLE IF NOT EXISTS`, etc.). The `uninstall.sql` file is not run automatically — it is provided for manual cleanup if needed.

## Module Manifest (`module.json`)

Each module has a `module.json` manifest that defines its metadata and behavior. Here is the full schema:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique module identifier |
| `name` | string | Display name |
| `group` | string | Category grouping (e.g. "Productivity", "Fitness") |
| `description` | string | Short description of the module |
| `version` | string | Semantic version number |
| `icon` | string | [Lucide icon](https://lucide.dev) name for sidebar display |
| `enabled` | boolean | Whether the module is active by default |
| `fullscreen` | boolean | Use fullscreen layout instead of standard sidebar layout |
| `menuPriority` | number | Sort order in the sidebar (lower = higher) |
| `permissions` | object | Module capabilities (`database`, `api`, `dashboard` — all boolean) |
| `routes` | array | Custom route definitions |
| `dependencies` | object | Other modules or core features this module depends on |
| `database` | object | Database configuration |
| `dashboard` | object | Dashboard widget configuration |
| `settings` | object | Module-specific settings schema |
| `topBarIcon` | object | Add a quick-access icon to the top navigation bar (e.g. `{ "icon": "CheckSquare", "route": "/tasks", "tooltip": "Open Tasks" }`) |
| `submenu` | object | Sidebar submenu component configuration |
| `publicRoutes` | array | Routes accessible without authentication |

## Layout Options

Modules support two layout modes:

- **Standard** — Renders within the ARI sidebar layout. Best for most modules like Task Manager, Contacts, and Knowledge Manager.
- **Fullscreen** — Takes the entire viewport. Best for immersive experiences like games, canvases, or visualization tools. Set `"fullscreen": true` in `module.json`.

## Module Directories

ARI loads modules from two directories:

| Directory | Managed By | Survives Upgrade | Priority |
| --- | --- | --- | --- |
| `modules-core/` | Upstream | No (overwritten on upgrade) | Lower |
| `modules-custom/` | You | Yes | Higher |

**Custom overrides core:** If a module with the same `id` exists in both `modules-core/` and `modules-custom/`, only the version in `modules-custom/` is loaded. This lets you fork and customize any core module without modifying the original.

## Module Registration

ARI uses a registry system to manage modules. When you create a module with the `/ari-create-module` command, registration is handled for you automatically. The registry is regenerated at build time by scanning the `modules-core/` and `modules-custom/` directories, so your module is picked up and available in the sidebar and routing.

## Sharing Modules

Because modules are self-contained directories with a consistent structure, they are easy to share. You can copy a module folder to another ARI instance, share it with the community, or fork an existing module and customize it.

See [Creating Modules](https://ari.software/docs/creating-modules) for how to build your own.

## Your Personal Workspace. Your Rules.

Source Code Available. Self-Hosted. Full Data Control. Fully Extendable. AI Native. Dozens of Built-In Modules And Build Your Own In Minutes. No Coding Required.

[Get Started](https://ari.software/docs/installation)

---

Source: https://ari.software/docs/module-structure

Markdown rendering of this page, served for `Accept: text/markdown`. Full site index for agents: https://ari.software/llms.txt