First-Class Plugin Architecture

What a plugin can register

The Plugin base class (in include/hive-api/hive/api/Plugin.hpp) provides all registration methods. After startup, close_for_changes() is called — the plugin becomes immutable at runtime.

Plugin Lifecycle & Dependency Resolution

Main.cpp: register plugin factories
   new CorePlugin(), new SlipBoxPlugin(), new RepetitionPlugin(), new DictionaryPlugin()
          │
          ▼
PluginRegistry::get_plugin_names_sorted_by_dependencies()
   Topological sort of declared dependency graph
   Throws CyclicDependencyException   — if A→B→A detected
   Throws MissingDependencyException  — if declared dep not registered
   Result: [core, slip_box, dictionary, repetition]
          │
          ▼
For each plugin in sorted order:
  SqliteDatabaseMigration::apply_all()
    · Iterate registered V{n}__name migration scripts (embedded SQL)
    · Compute SHA-256 per script + rolling chain_hash
    · Apply only new migrations (compare to schema history)
    · On hash mismatch: throw — startup aborts
          │
          ▼
For each plugin in sorted order:
  plugin.register_models()     → ModelDefinitionRegistry
  plugin.register_validators() → ValidatorRegistry
  plugin.register_triggers()   → TriggerRegistry (sorted by priority)
  plugin.register_jobs()       → JobRegistry
  plugin.register_queries()    → QueryRegistry
  plugin.close_for_changes()   → Plugin becomes read-only at runtime
          │
          ▼
HTTP route generation (one pass over ModelDefinitionRegistry)
Cron scheduler start (4 threads, ScheduledJobEntry per job)

Plugin dependency graph

core ◄── slip_box ◄── repetition
core ◄── dictionary

Core Plugin — Platform Foundation

The Core plugin provides platform-critical infrastructure required by every domain plugin. It is always loaded first and cannot be disabled. Source: src/hive-api/hive/plugins/core/. It is the only plugin that already ships its migrations in two SQL dialects — CoreSQLiteMigrationScripts and CorePostgreSQLMigrationScripts.

enum class UserRole : int {
    Guest      = 0,
    Reader     = 1,
    Editor     = 2,
    Reviewer   = 3,
    Admin      = 4,
    SuperAdmin = 5,
    System     = 100
};

enum class UserStatus : int {
    Pending     = 0,
    Active      = 1,
    Deactivated = 2,
    Banned      = 3,
    Suspended   = 4,
    Deleted     = 5
};

enum class RegistrationMode : int {
    Free                  = 0,
    RequiresAdminApproval = 1,
    AdminAddsUsers        = 2
};

Core plugin SQL schema (real excerpt — V1)

-- V1__create_user (from CoreSQLiteMigrationScripts.cpp)
CREATE TABLE user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,

    username TEXT NOT NULL UNIQUE,
    password_hash TEXT,
    email TEXT,

    display_name TEXT,
    profile_text TEXT,

    role INTEGER NOT NULL DEFAULT 0,   -- UserRole (Guest=0 … System=100)
    status INTEGER NOT NULL,           -- UserStatus (Pending=0 … Deleted=5)

    last_login DATETIME
);

CREATE INDEX idx_user_last_login ON user(last_login);
CREATE INDEX idx_user_status ON user(status);
CREATE INDEX idx_user_role ON user(role);

Core plugin triggers

Core plugin scheduled jobs

Core plugin custom queries

CleanupSQLiteQuery · VacuumSQLiteQuery · CleanupHistoryOrphansSQLiteQuery — the SQL behind the maintenance jobs, registered as named queries so jobs stay database-agnostic.

Slipbox Plugin — Knowledge Graph

A rich knowledge management system inspired by the Zettelkasten / Slip Box methodology. Designed for structured note-taking, knowledge graphs, and linked writing. Depends on: core. Source: src/hive-plugin-slip-box/. In the current CMake configuration it is gated behind ALLOW_LEGACY_PLUGINS (with MINDNET_ENABLE_SLIPBOX_PLUGIN=ON once legacy plugins are allowed).

-- from SlipBoxSQLiteMigrationScripts.cpp
CREATE TABLE note (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,

    map_id INTEGER NOT NULL,
    parent_note_id INTEGER,
    content_id INTEGER UNIQUE,
    source_id INTEGER,
    alias_for_note_id INTEGER,

    title TEXT NOT NULL,
    sibling_order INTEGER NOT NULL,
    importance INTEGER DEFAULT 0,
    difficulty INTEGER DEFAULT 0,

    -- hierarchical metadata
    path TEXT,               -- e.g. '/000001/000045/000099'
    depth INTEGER DEFAULT 0, -- 0=root, 1=child, ...

    FOREIGN KEY (map_id) REFERENCES map(id),
    FOREIGN KEY (parent_note_id) REFERENCES note(id),
    FOREIGN KEY (content_id) REFERENCES content(id),
    FOREIGN KEY (source_id) REFERENCES source(id)
);

Slipbox triggers (10)

Slipbox custom queries (7)

Slipbox validators (29)

One validator per model — NoteValidator, ContentValidator, MapValidator, LinkValidator, TagValidator, TagTypeValidator, PropertyValidator, FlagValidator, PinnedNoteValidator, SourceValidator, UrlValidator, WantedNoteValidator, IdeaValidator, ProjectValidator, TaskValidator, TermValidator, QuestionValidator, TestValidator, TestAttemptValidator, TestAttemptAnswerValidator, CollectionValidator, CollectionItemValidator, MapCollectionValidator, MapCollectionItemValidator, AlertValidator, AnnotationValidator, NoteNavigationValidator, TermFulltextValidator, TagTypeFulltextValidator.

Slipbox jobs

Graph exploration — Slipbox Plugin

Note list view with column selector

Repetition Plugin — Spaced Repetition

SuperMemo-style spaced repetition system for systematic knowledge review and memorisation scheduling. Depends on: slip_box (and transitively core). Source: src/hive-plugin-repetition/.

-- from RepetitionSQLiteMigrationScripts.cpp
CREATE TABLE r_review (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,

    user_id INTEGER NOT NULL,
    map_id INTEGER NOT NULL,
    r_session_id INTEGER,

    algorithm INTEGER NOT NULL,

    note_id INTEGER,

    review_date DATETIME,
    grade INTEGER CHECK (grade BETWEEN 0 AND 5),
    response_data TEXT, -- e.g. JSON: {"selected": [1, 3]}
    notes TEXT,

    started_at DATETIME, -- when started answering
    ended_at DATETIME,   -- when finished
    latency_ms INTEGER   -- response time in ms
    ...
);

Dictionary Plugin — Lexicon Management

A full-featured lexicon and dictionary system with fulltext search, visit analytics, understanding tracking, review integration, and a dedicated 19-language frontend app. Depends on: core. Source: src/hive-plugin-dictionary/. This is the most actively developed domain plugin and the only one enabled in the default CMake configuration (MINDNET_ENABLE_DICTIONARY_PLUGIN=ON).

-- from DictionarySQLiteMigrationScripts.cpp
CREATE TABLE dictionary_term (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,

    dictionary_map_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    disambiguation TEXT,
    definition TEXT,
    status INTEGER NOT NULL,
    importance INTEGER NOT NULL,
    difficulty INTEGER NOT NULL,

    UNIQUE(dictionary_map_id, title, disambiguation),

    FOREIGN KEY(dictionary_map_id)
        REFERENCES dictionary_map(id)
);

CREATE INDEX idx_dictionary_term_map
    ON dictionary_term(dictionary_map_id);
CREATE INDEX idx_dictionary_term_title
    ON dictionary_term(title);

CREATE TABLE dictionary_term_visit (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,

    dictionary_term_id INTEGER NOT NULL,
    user_id INTEGER NOT NULL,
    dictionary_map_id INTEGER NOT NULL,

    FOREIGN KEY(dictionary_term_id)
        REFERENCES dictionary_term(id),
    FOREIGN KEY(user_id) REFERENCES user(id),
    FOREIGN KEY(dictionary_map_id)
        REFERENCES dictionary_map(id)
);

Dictionary triggers (15)

Dictionary custom queries (13)

FindDictionaryTermsSQLiteQuery, FindDictionaryTermsViaAdvancedSearchSQLiteQuery, FindDictionaryTermAliasesSQLiteQuery, FindDictionaryTermMetricsSQLiteQuery, FindDictionaryTermsForReviewSQLiteQuery, FindDictionaryOlderNewerTermsSQLiteQuery, FindNextDictionaryNotePositionSQLiteQuery, FindDictionarySearchesSQLiteQuery, FindDictionaryFlagsSQLiteQuery, FindDictionaryTagTypesSQLiteQuery, FindDictionaryIndexTypesSQLiteQuery, FindDictionarySourceTypesSQLiteQuery, FindDictionaryUrlTypesSQLiteQuery

Dictionary validators (34)

One validator per model plus dedicated validators for every virtual/fulltext model — from DictionaryTermValidator and DictionaryMapValidator through DictionaryTermMetricValidator, DictionaryTermForReviewValidator, DictionaryState18Validator, and the *Fulltext validator family. Includes input hygiene checks such as enforcing trimmed text columns.

Dedicated frontend app (19 languages)

• Modular ES-module app under frontend/dictionary/ — core/DictionaryApp.js, entities, enums, markdown, search, window components
• i18n layer with 19 locale files (en, cs, de, el, eo, es, fa, fr, he, hu, it, ja, ko, la, pl, ru, sk, vi, zh), validated by validate_i18n.sh
• Three-level autocomplete relevance scoring for term search
• TermMetricsWindow and TermVisitHistoryWindow analytics windows
• Unsaved-changes warning; no-op saves are skipped; renaming a term updates localStorage caches
• Static HTML export via DictionaryHtmlExportJob
• Served from /web/app_dictionary.html

Build Your Own Plugin

The plugin system is the intended path for all domain extensions. The four built-in plugins (core, slip_box, repetition, dictionary) are the authoritative structural templates.

src/hive-plugin-myplugin/
└── hive/plugins/myplugin/
    ├── MyPluginFactory.cpp
    ├── models/          — BaseModel subclasses + ModelDefinition
    ├── validators/      — IValidator per model
    ├── triggers/        — optional Before/After/InsteadOf triggers
    ├── jobs/            — optional scheduled jobs
    └── migrations/
        └── MyPluginSQLiteMigrationScripts.cpp
            (embedded V1__…, V2__… SQL scripts)

api::PluginPtr MyPluginFactory::create(
    std::shared_ptr<api::RepositoryFactory>& repository_factory) const
{
    auto plugin = std::make_shared<api::Plugin>(
        MY_PLUGIN_NAME,
        "My domain",
        std::vector<std::string>{"my_app"},      // frontend apps
        std::vector<std::string>{"slip_box"}     // explicit deps
    );  // an implicit dependency on "core" is always added

    REGISTER_MIGRATIONS(MyPlugin, SQLite)

    // REGISTER_MODEL(model, Model, MODEL) expands to:
    // plugin->register_model(models::MODEL_DEFINITION,
    //     std::make_shared<validators::ModelValidator>(),
    //     repository_factory);
    REGISTER_MODEL(my_model, MyModel, MY_MODEL)

    plugin->register_trigger(
        std::make_shared<triggers::MyAfterCreateTrigger>());
    plugin->register_query(
        std::make_shared<queries::FindMyThingsSQLiteQuery>());
    plugin->register_job(std::make_shared<jobs::MyCleanupJob>());

    return plugin;
}

add_migration("V1__create_my_model.sql", R"(
CREATE TABLE my_model (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at DATETIME,
    updated_at DATETIME,
    name TEXT NOT NULL,
    owner_id INTEGER,
    FOREIGN KEY(owner_id) REFERENCES user(id)
);
)");