Athenian Social Users Core

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

8. Technical Architecture

Service-Oriented Plugin Boot

The plugin uses a central service bootstrap pattern in includes/Plugin.php.

Booted services include:

| Service | Purpose | |---|---| | Options | Defaults and stored settings | | DB | Custom database schema installation and versioning | | Roles | Social roles and capabilities | | People | Canonical Person CPT, taxonomy, meta, sync, geocoding | | Person_Score | Trust/risk/payment readiness scoring | | Profile | User social profile fields and updates | | Follows | Follow graph service | | Messaging | Private message threads and send/list/read logic | | Alerts | Notification/alert service | | Media | Attachment pricing, lock state, and unlocks | | REST | REST route registration | | Assets | Public/admin CSS and JS registration | | Admin | Admin menu, settings, user screen integration | | Admin_People_Editor | Custom Person editor UI | | Shortcodes | Frontend shortcode surfaces | | Integrations | WooCommerce account, credits, OwlPay, dashboard hooks |

The plugin fires:

do_action('asu_social_users_core_booted');

after all services are booted.

Files & Directories

athenian-social-users-core.php
includes/
  Admin.php
  Admin_People_Editor.php
  Alerts.php
  Assets.php
  DB.php
  Follows.php
  functions.php
  Geocoder.php
  Integrations.php
  Media.php
  Messaging.php
  Options.php
  People.php
  Person_Score.php
  Plugin.php
  Profile.php
  REST.php
  Roles.php
  Schema.php
  Shortcodes.php
  Util.php
  REST/
    Controller_Alerts.php
    Controller_Base.php
    Controller_Follows.php
    Controller_Media.php
    Controller_Messaging.php
    Controller_Person.php
    Controller_Profile.php
    Controller_Uploads.php
assets/
  admin.css
  admin.js
  admin-person.css
  admin-person.js
  public.css
  public.js
docs/
  asu-social-users-core-marketing-document.md
  cli-snippets.md

---

9. Data Model

Custom Post Type

| Key | Description | |---|---| | ath_person | Canonical Person record linked to WP users |

The CPT is private but shown in wp-admin and REST. It supports:

• Title
• Author
• Featured image / thumbnail
• Registered meta fields
• Admin UI management

Taxonomy

| Key | Description | |---|---| | ath_person_type | Non-public taxonomy for person classification |

Suggested person type usage includes:

• creator
• service_provider
• technician
• vendor_contact
• customer
• student
• staff

Person Meta Schema

Core person meta includes:

| Meta Key | Type | REST | Purpose | |---|---:|---:|---| | asu_user_id | int | yes | Linked WordPress user | | parent_person_id | int | yes | Parent/related person | | business_provider_post_id | int | yes | Related business/provider post | | business_provider_user_id | int | yes | Related provider user | | primary_location_post_id | int | yes | Primary location relationship | | location_post_ids | json | yes | Related location IDs | | email | string | yes | Contact email | | phone | string | yes | Contact phone | | billing_ | string | yes | Billing address fields | | shipping_ | string | yes | Shipping address fields | | geo_lat | float | yes | Latitude | | geo_lng | float | yes | Longitude | | geo_place_id | string | yes | Provider/place identifier | | geo_label | string | yes | Human-readable geo label | | geo_radius_mi | int | yes | Service radius | | timezone | string | yes | Time zone | | extra_json | json | yes | Extension payload |

Other plugins can extend the schema through:

apply_filters('asu_person_meta_schema', $base);

User Meta

| Key | Purpose | |---|---| | asu_person_id | Cached relationship from user to Person CPT | | asu_display_name | Social display value where applicable | | asu_bio | Profile bio | | asu_location | Profile location | | asu_website | Profile website | | asu_social_links | JSON social links | | asu_avatar_id | Avatar attachment ID | | asu_cover_id | Cover attachment ID | | asu_is_creator | Creator flag | | asu_creator_tagline | Creator tagline | | asu_allow_messages | Message privacy |

Attachment Meta

| Key | Purpose | |---|---| | _asu_owner_user_id | Owner marker for user media | | _asu_price_credits | Credit price for media access | | _asu_is_locked | Locked/unlocked state |

---

10. Custom Database Tables

The plugin installs and versions a custom database schema through DB::SCHEMA_VERSION = 4.

wp_asu_threads

Stores one thread per unique user pair.

| Column | Purpose | |---|---| | id | Thread ID | | user_low / user_high | Normalized user pair | | last_message_id | Last message pointer | | last_message_at | Last message timestamp | | created_at | Created timestamp | | updated_at | Updated timestamp |

Important indexes:

• Unique pair index on user_low, user_high
• updated_at
• last_message_at

wp_asu_messages

Stores direct message records.

| Column | Purpose | |---|---| | id | Message ID | | thread_id | Parent thread | | sender_id | Sender user ID | | body | Message body | | meta | Context JSON | | is_read | Read flag | | created_at | Created timestamp |

wp_asu_alerts

Stores user alerts and notifications.

| Column | Purpose | |---|---| | id | Alert ID | | user_id | Recipient | | actor_id | Actor user | | source | Source plugin/system | | type | Alert type | | entity_type | Related entity type | | entity_id | Related entity ID | | title | Alert title | | body | Alert body | | url | Destination URL | | severity | low, normal, high, critical | | status | Read/unread status | | meta | JSON payload | | is_read | Read flag | | created_at | Created timestamp | | read_at | Read timestamp |

wp_asu_follows

Stores follow relationships.

| Column | Purpose | |---|---| | id | Follow row ID | | follower_id | User following another user | | followed_id | User being followed | | created_at | Created timestamp |

Important index:

• Unique relationship on follower_id, followed_id

wp_asu_media_unlocks

Stores viewer unlocks for paid/locked media.

| Column | Purpose | |---|---| | id | Unlock ID | | attachment_id | Attachment/media ID | | owner_id | Media owner | | viewer_id | User who unlocked | | price_credits | Price at time of unlock | | txn_ref | Optional transaction reference | | created_at | Created timestamp |

Important index:

• Unique relationship on attachment_id, viewer_id

wp_asu_person_score_events

Stores score evidence events.

| Column | Purpose | |---|---| | id | Event ID | | person_id | Person CPT ID | | user_id | Linked WP user | | source | Source system | | metric | Metric key | | value | Event value | | weight | Metric weight | | confidence | Confidence value | | event_key | Unique event key | | occurred_at | Event date | | expires_at | Optional expiration | | meta | JSON payload | | created_at | Created timestamp |

---

11. REST API Reference

REST namespace:

/wp-json/asu/v1

Profile & Current User

| Method | Route | Purpose | |---|---|---| | GET | /me | Current user/profile state; returns logged-out state if not logged in | | GET | /profile/{user_id} | Public profile payload | | POST | /profile/update | Update current user social profile |

Person Records

| Method | Route | Purpose | |---|---|---| | GET | /person/me | Current user's canonical Person record; auto-creates if needed | | PUT/PATCH/POST | /person/me | Update whitelisted Person meta for current user | | GET | /person/{person_id} | Read a Person record by Person ID | | GET | /person/by-user/{user_id} | Read Person record by WP user ID |

Person read access is limited to the owner or users with ASU/admin capabilities.

Follows

| Method | Route | Purpose | |---|---|---| | POST | /follow/{user_id} | Follow a user | | DELETE | /follow/{user_id} | Unfollow a user | | GET | /follows | List followers/following |

Messaging

| Method | Route | Purpose | |---|---|---| | GET | /threads | List current user's message threads | | GET | /threads/{thread_id} | Read a thread | | POST | /messages/send | Send a message | | POST | /threads/{thread_id}/read | Mark a thread read |

Alerts

| Method | Route | Purpose | |---|---|---| | GET | /alerts | List alerts | | GET | /alerts/counts | Get unread/alert counts | | POST | /alerts/{alert_id}/read | Mark one alert read | | POST | /alerts/read | Mark all alerts read |

Uploads

| Method | Route | Purpose | |---|---|---| | POST | /upload | General logged-in user upload | | POST | /profile/avatar | Upload/set profile avatar | | POST | /profile/cover | Upload/set profile cover |

Media

| Method | Route | Purpose | |---|---|---| | GET | /media/my | List current user's owned media | | GET | /media/{attachment_id} | Read media payload and visibility state | | POST | /media/{attachment_id}/pricing | Owner sets pricing/locked state | | POST | /media/{attachment_id}/unlock | Spend/record unlock for media | | GET | /media/{attachment_id}/stream | Guarded media access/stream route |

---

12. Integration Points

WooCommerce

ASU Core integrates with WooCommerce in several ways:

• Mirrors customer address/contact data into Person records.
• Adds WooCommerce account endpoints for profile, messages, and notifications.
• Adds account dashboard cards for social profile, unread messages, and unread notifications.
• Refreshes Person Score snapshots on payment/order lifecycle events.
• Uses customer address changes to trigger geocoding updates.

Related WooCommerce hooks include:

• woocommerce_created_customer
• woocommerce_update_customer
• woocommerce_customer_save_address
• woocommerce_payment_complete
• woocommerce_order_status_completed
• woocommerce_order_status_processing
• woocommerce_order_refunded
• woocommerce_order_status_failed
• woocommerce_order_status_cancelled

Athenian Site Credits / Credit Pack Manager

The integrations layer supports credit balances, credit spending, credit adjustments, transaction history, and transfers through multiple conventions.

Detected function conventions include:

• asc_get_credit_balance
• asc_get_balance
• athenian_site_credits_get_balance
• asc_get_credit_transactions
• asc_get_transactions
• athenian_site_credits_get_transactions
• asc_add_credits
• asc_credit_user
• athenian_site_credits_add
• asc_transfer_credits
• athenian_site_credits_transfer
• asc_spend_credits

It also checks for the CPM_Credits class and common methods such as:

• get_balance
• get_transactions
• get_history
• get_ledger
• add_credits
• credit_user
• transfer_credits
• deduct_credits

Fallback filters allow another plugin to implement the credit provider.

Athenian Owl Pay

The integrations layer includes account snapshot and sync hooks for Owl Pay-style payout systems.

Function conventions include:

• aop_get_user_payout_account
• athenian_owl_pay_get_account
• aop_sync_user_payout_account
• athenian_owl_pay_sync_account

Filters include:

• asu_owl_pay_account_snapshot
• asu_sync_owl_pay_account

Header / Dashboard Integrations

The plugin exposes unread counts to theme/header integrations through:

• athenian_header_alert_count
• athenian_header_message_count

It also contributes dashboard integrations and cards through:

• athenian_user_dashboard_integrations
• athenian_user_dashboard_cards

---

13. Hooks & Extensibility

Core Actions

| Hook | Purpose | |---|---| | asu_social_users_core_booted | Fired after plugin services are booted | | asu_person_created | Fired when a Person record is created | | asu_person_linked | Fired when an existing Person record is linked to a user | | asu_person_synced | Fired when a user is synced to a Person record | | asu_person_updated | Fired after Person meta is updated | | asu_person_geo_updated | Fired after geocoding updates a Person | | asu_follow_created | Fired after a follow is created | | asu_follow_deleted | Fired after a follow is removed | | asu_message_sent | Fired after a message is sent | | asu_create_alert | Action interface for creating alerts | | asu_alert_created | Fired after alert insert | | asu_person_score_refreshed | Fired after person score refresh |

Core Filters

| Hook | Purpose | |---|---| | asu_person_meta_schema | Extend canonical Person meta | | asu_person_get | Modify Person payload output | | asu_profile_get | Modify profile payload output | | asu_can_message | Override message permission | | asu_message_send_allowed | Final message send permission override | | asu_message_context_privacy_bypass | Context-specific messaging bypass | | asu_can_view_media | Override locked media visibility | | asu_can_view_creator_content | Creator content access gate | | asu_geocode_address | Replace/default geocoding result | | asu_enable_default_geocoder | Enable/disable bundled geocoder | | asu_geocode_http_request_args | Adjust HTTP args for geocoder | | asu_nominatim_query_variants | Adjust Nominatim query attempts | | asu_show_account_dashboard_cards | Show/hide Woo account dashboard cards | | asu_person_score_calculated | Modify calculated person score | | asu_person_payment_readiness_snapshot | Extend payment readiness scoring facts | | asu_person_score_ai_review | Feed AI review data into score | | asu_person_score_capabilities | Extend score capability flags | | asu_get_credit_balance | Provide credit balance | | asu_credit_transaction_history | Provide credit history | | asu_adjust_credits | Provide credit adjustment implementation | | asu_transfer_credits | Provide transfer implementation | | asu_spend_credits | Provide credit spend implementation |

Person Editor Extension Hooks

The custom Person editor is intentionally extensible. Notable hooks include:

• asu_person_editor_tabs
• asu_person_editor_groups
• asu_person_editor_render_panel
• asu_person_editor_credit_manager_panel
• asu_person_editor_input_html
• asu_person_editor_label
• asu_person_editor_lookup_target
• asu_person_editor_lookup_post_types

These allow other plugins to add their own profile sections without replacing ASU Core.

---

14. Security & Permission Model

Login Requirements

Most write actions require logged-in users. REST controllers use dedicated permission callbacks, and profile/person updates are scoped to the current user unless the user can manage the target user.

Admin Capabilities

Administrative screens require asu_manage, while administrators are granted:

• asu_manage
• asu_moderate
• list_users
• create_users
• edit_users

Media Ownership

Media pricing changes require owner access. The plugin checks WordPress attachment authorship and _asu_owner_user_id.

Media Visibility

Locked media returns no direct URL unless:

• The viewer is the owner.
• The viewer has an unlock record.
• A filter grants access, such as subscription or staff/tooling access through asu_can_view_media.

Messaging Privacy

Message send permission checks:

• Prevent self-messaging.
• Respect recipient privacy settings: all, followers, or none.
• Support reply/thread and context-based bypasses where appropriate.
• Allow downstream filters to add additional rules.

Rate Limiting

Message sending is rate limited through configurable options:

• msg_rate_limit_count
• msg_rate_limit_window

Upload Restrictions

Uploads are constrained by:

• Logged-in user requirement
• Maximum upload size
• Allowed MIME type list
• WordPress media handling

---

16. WP-CLI / Developer Snippets

Check REST Routes

wp eval '
do_action("rest_api_init");
global $wp_rest_server;
$routes = $wp_rest_server->get_routes();
foreach (["/asu/v1/me","/asu/v1/profile/(?P<user_id>\\d+)","/asu/v1/threads"] as $k) {
  echo "Has $k ? ".(isset($routes[$k]) ? "YES" : "NO")."\n";
}
'

Create a Test Message

FROM=1 TO=2 BODY="hello" wp eval '
$from=(int)getenv("FROM"); $to=(int)getenv("TO"); $body=(string)getenv("BODY");
$svc = new \Athenian\ASU\Core\Messaging();
var_export($svc->send($from,$to,$body));
echo "\n";
'

Inspect a User Profile Payload

UID=1 wp eval '
$uid=(int)getenv("UID");
$p=new \Athenian\ASU\Core\Profile();
print_r($p->get($uid));
'

Sync All Users to Person Records

wp eval '
$result = \Athenian\ASU\Core\People::sync_all_users();
print_r($result);
'

Refresh a Person Score

UID=1 wp eval '
$user_id = (int) getenv("UID");
$person_id = \Athenian\ASU\Core\People::get_person_id($user_id);
if ($person_id) {
    $score = \Athenian\ASU\Core\Person_Score::refresh_person($person_id, $user_id);
    print_r($score);
}
'

---

17. Example Implementation Scenarios

Creator Profile Page

A frontend page can use [asu_profile] for user self-management and [asu_creator_grid] for discovery. Creator profile fields can be surfaced in custom Bricks templates, and premium media can be fetched through /asu/v1/media/{attachment_id}.

Marketplace Messaging

A marketplace plugin can use Messaging::send() with contextual metadata such as swap_id, offer_id, listing_id, or context_kind. The ASU message service stores the thread while the marketplace plugin owns the business object.

Paid Media Unlock

A creator uploads media, sets _asu_price_credits, and marks the asset locked. A viewer calls /media/{attachment_id}/unlock, which delegates credit spending to Athenian Site Credits or another credit provider. If successful, ASU records the unlock in asu_media_unlocks.

Customer Identity Unification

A WooCommerce customer updates billing or shipping address details. ASU Core mirrors the address fields into the linked Person record and refreshes geolocation when address data changes.

Trust & Risk Scoring

A user places orders, receives refunds, or has payment failures. ASU Core listens to WooCommerce order lifecycle events and refreshes the Person score snapshot so other modules can use trust/risk/payment readiness values.

---

25. Implementation Readiness Assessment

ASU Core is already structured like a reusable platform component. It has a clear service architecture, proper activation setup, database-backed relationship models, admin screens, frontend shortcodes, REST endpoints, and multiple integration hooks.

The most important existing strengths are:

• Stable canonical Person model.
• Rich People editor.
• Custom tables for follows, messages, alerts, unlocks, and score events.
• WooCommerce account integration.
• REST-first architecture.
• Credit and payout provider abstraction.
• Flexible schema and editor extension filters.
• Strong foundation for future creator/community modules.

The main areas to harden before broad production rollout would be:

• Formal API documentation and examples.
• Admin moderation flows.
• End-to-end permission testing for media streaming/unlocks.
• Rate limit testing under real traffic.
• Credit provider transaction atomicity.
• Privacy and data retention policies.
• UI polish for public shortcode surfaces.
• Automated integration tests for WooCommerce, credits, and media access.

---