Skip to content

Architecture Overview

Jump to bottom
Varun Kumar Dubey edited this page Mar 27, 2026 · 1 revision

Architecture Overview

Jetonomy uses a clean, WordPress-native architecture with dedicated database tables, model classes, and clear separation of concerns.

Directory Structure

jetonomy/
  jetonomy.php                  # Bootstrap, constants, EDD SDK
  includes/
    class-jetonomy.php          # Singleton, activation, dependency loading
    class-router.php            # URL rewrite rules for /community/*
    class-template-loader.php   # Template resolution with theme overrides
    class-mentions.php          # @mention parser and notifier
    class-cron.php              # Scheduled jobs (trust evaluation, cleanup)
    class-shortcodes.php        # [jetonomy] shortcode
    class-abilities.php         # WP Abilities API (18 abilities)
    class-activity-tracker.php  # Centralized event logging via hooks
    db/
      class-schema.php          # All 22 table definitions (dbDelta)
      class-migrator.php        # Version-based schema migrations
    models/                     # 15 model classes (all extend abstract Model)
      class-post.php
      class-reply.php
      class-space.php
      class-category.php
      class-vote.php
      class-notification.php
      class-subscription.php
      class-user-profile.php
      class-flag.php
      class-space-member.php
      class-tag.php
      class-join-request.php
      class-access-rule.php
      class-activity-log.php
      class-restriction.php
    api/                        # 15 REST controllers (all extend Base_Controller)
      class-base-controller.php
      class-posts-controller.php
      class-replies-controller.php
      class-spaces-controller.php
      class-users-controller.php
      class-votes-controller.php
      class-tags-controller.php
      class-notifications-controller.php
      class-moderation-controller.php
      class-search-controller.php
      class-subscriptions-controller.php
      class-categories-controller.php
      class-leaderboards-controller.php
      class-bookmarks-controller.php
      class-updates-controller.php
    permissions/
      class-permission-engine.php   # 3-layer permission resolver
      class-capabilities.php        # WP capability registration
      class-rate-limiter.php        # Trust-level-based rate limiting
    trust/
      class-trust-evaluator.php     # Auto-promotion logic
      class-reputation.php          # Reputation point system
    notifications/
      class-notifier.php            # Event-driven notification dispatcher
    adapters/                       # Interface-based backends
      interface-email-adapter.php
      interface-search-adapter.php
      interface-membership-adapter.php
      interface-realtime-adapter.php
      class-adapter-registry.php
      class-wp-mail-adapter.php
      class-polling-adapter.php
      class-member-press-adapter.php
      class-pmpro-adapter.php
      class-wp-roles-adapter.php
    captcha/
      class-captcha-manager.php     # reCAPTCHA v3 / Turnstile
    import/
      class-import-manager.php      # bbPress + wpForo importers
    admin/
      class-admin.php               # Menu, settings, asset loading
      ajax/                         # AJAX handlers (separated from Admin)
        class-spaces-handler.php
        class-categories-handler.php
        class-moderation-handler.php
        class-users-handler.php
        class-content-handler.php
        class-import-handler.php
        class-settings-handler.php
        class-setup-handler.php
      views/                        # Admin page templates
  templates/
    views/                          # Frontend page templates (theme-overridable)
    partials/                       # Reusable components (theme-overridable)
  assets/
    css/jetonomy.css                # Frontend styles with --jt-* tokens
    css/admin.css                   # Admin styles
    js/view.js                      # Interactivity API store
    js/admin.js                     # Admin JavaScript

Database

Jetonomy uses 22 dedicated MySQL tables (prefixed wp_jt_*), not WordPress custom post types. This ensures forum queries never degrade wp_posts performance.

Key Tables

Table Purpose Key Columns
jt_categories Space categories id, name, slug, parent_id, sort_order
jt_spaces Forum spaces id, title, slug, type, visibility, join_policy, settings (JSON)
jt_posts Topics/threads id, space_id, author_id, title, slug, content, status, vote_score, reply_count
jt_replies Replies/comments id, post_id, author_id, parent_id, content, status, vote_score
jt_votes Up/downvotes id, object_type, object_id, user_id, value
jt_user_profiles Extended profiles user_id, trust_level, reputation, settings (JSON)
jt_notifications Notification inbox id, user_id, actor_id, type, message, is_read
jt_subscriptions Follow spaces/posts id, user_id, object_type, object_id
jt_space_members Space membership space_id, user_id, role
jt_flags Content reports id, reporter_id, object_type, object_id, reason, status
jt_tags Post tags id, name, slug
jt_access_rules Membership gates id, space_id, rule_type, rule_value
jt_activity_log Activity feed id, user_id, action, object_type, object_id
jt_join_requests Space join requests id, space_id, user_id, status, message

Design Decisions

  • Denormalized counters — reply_count, vote_score, post_count stored directly on parent rows. No COUNT queries on page load.
  • JSON settings columns — Space settings and user notification preferences stored as JSON. Merged on update via array_merge(), never replaced.
  • Cursor-based pagination — Available on all list endpoints via after parameter for consistent performance at any page depth.

Models

All models extend the abstract Model class which provides:

  • find($id) — Single row lookup with object caching
  • insert($data) — Insert with auto-timestamps
  • update($id, $data) — Partial update
  • delete($id) — Hard delete
  • table() — Prefixed table name
  • db() — $wpdb instance

Models handle data access only. Business logic lives in controllers and service classes.

Permission Resolution

Permission_Engine::can( $user_id, $action, $space_id )
  1. WordPress capabilities (manage_options, jetonomy_moderate, etc.)
  2. Space role (viewer < member < moderator < admin)
  3. Trust level (0-5, global, auto-earned)
  → Returns bool

Request Flow

HTTP Request
  → WordPress REST API (wp-json/jetonomy/v1/*)
  → Controller::permission_callback() — 3-layer check
  → Controller::handler() — validate, sanitize
  → CAPTCHA check (trust level < 2)
  → Rate limiter check (trust-level based)
  → apply_filters('jetonomy_check_content') — moderation
  → Model::create/update/delete
  → do_action('jetonomy_after_*') — hooks fire
  → Activity_Tracker logs event
  → Notifier dispatches notifications
  → JSON response with pagination metadata

Naming Conventions

Type Pattern Example
Options jetonomy_* jetonomy_settings, jetonomy_db_version
User meta jetonomy_* jetonomy_onboarding_complete
DB tables jt_* wp_jt_posts, wp_jt_replies
Hook names jetonomy_* jetonomy_after_create_post
AJAX actions jetonomy_* wp_ajax_jetonomy_update_space
REST namespace jetonomy/v1 /wp-json/jetonomy/v1/spaces
Asset handles jetonomy jetonomy, jetonomy-admin
CSS tokens --jt-* --jt-accent, --jt-text

URL Structure

/community/                     → Home (space directory)
/community/category/:slug/      → Category
/community/s/:slug/             → Space (topic listing)
/community/s/:slug/t/:slug/     → Single post + replies
/community/s/:slug/new/         → New post form
/community/s/:slug/members/     → Space members
/community/s/:slug/roadmap/     → Ideas roadmap
/community/u/:login/            → User profile
/community/u/:login/edit/       → Edit profile
/community/tag/:slug/           → Tag view
/community/search/              → Search
/community/leaderboard/         → Leaderboard
/community/notifications/       → Notifications
/community/mod/                 → Moderation queue
/community/invite/:code/        → Invite link

The base slug (/community/) is configurable in Settings > General.

Clone this wiki locally