Domains Overview & Architecture Map#

Purpose: Understand all domains, their responsibilities, and dependencies
Format: Quick reference + dependency matrix + detailed entries

🎯 Quick Reference (14 Domains)#

📊 Dependency Matrix#

Visualization#

Core
 ├─ Identity (depends on Core)
 ├─ Ledger (depends on Core)
 ├─ Payments (depends on Core, Ledger)
 ├─ Content (depends on Core)
 ├─ Access (depends on Core, Content, Ledger)
 ├─ Discovery (depends on Core, Content, Access, Social)
 ├─ Social (depends on Core, Content)
 ├─ Monetization (depends on Core, Access, Ledger)
 ├─ FanClub (depends on Core, Identity)
 ├─ Moderation (depends on Core, Content)
 ├─ Promotions (depends on Core, Ledger)
 ├─ Notifications (depends on Core, Identity, Content)
 └─ AdminBackoffice (depends on all domains)

Legend#

A → B means:
  B depends on A (imports models, services, contracts from A)
  B can call A's services
  B can listen to A's events
  B cannot be called by A (no circular dependencies)

Key Rules#

1. Core has no dependencies (foundation)
2. No circular dependencies (enforced by code review)
3. Higher domains depend on lower, never reverse
4. AdminBackoffice is exception (depends on all for admin operations)
5. Always depend on contracts (interfaces), not implementations

🏛️ Domains by Layer#

Layer 0: Foundation#

• Core — Infrastructure, no business logic

Layer 1: User & Identity#

• Identity — User management, authentication

Layer 2: Financial Foundation#

• Ledger — Double-entry accounting

Layer 3: Monetization & Payments#

• Payments — MPESA integration, withdrawals
• Access — Gating rules, purchases
• Monetization — Tiers, subscriptions

Layer 4: Content & Discovery#

• Content — Posts, media, publishing
• Social — Interactions, relationships
• Discovery — Timelines, search, ranking

Layer 5: Platform Features#

• FanClub — Communities
• Moderation — Safety
• Promotions — Growth
• Notifications — Communications

Layer 6: Operations#

• AdminBackoffice — Admin panel

📖 Domain Entries#

1️⃣ Core Domain#

Status: ✅ Live
Location: app/Core/
Purpose: Cross-cutting infrastructure for all domains

Owned Concepts:

• Authorization (Scope enum, dual-approval workflows)
• HTTP middleware (request correlation, rate limiting)
• Error handling (DomainException, ErrorCode enum)
• Response envelopes (Shapes A/B/C)
• Logging (request logger, payload redaction)
• Platform settings & feature flags
• Cache management

Public Contracts:

• ILedgerService — Post financial transactions
• IPlatformSettings — Get platform config
• IFeatureFlags — Check feature state
• IRequestLogger — Log HTTP requests

Key Services:

• PlatformSettingsService — Dynamic configuration
• FeatureFlagsService — Feature toggles
• LedgerService — Post ledger transactions
• RequestLogger — MongoDB logging

Database:

• platform_settings — Configuration table
• feature_flags — Feature toggles
• ledger_* — Ledger tables (see Ledger domain)
• request_logs — MongoDB (not PostgreSQL)

Events: None (events come FROM other domains)

Consumed Events: None

API Endpoints: None (internal only)

See: CORE.md

2️⃣ Identity Domain#

Status: ✅ Live
Location: app/Identity/
Purpose: User management, authentication, MFA

Owned Concepts:

• User accounts (email, password, profile)
• Admin realms (admin/user distinction)
• Email verification
• OAuth (Google, Facebook, Apple)
• MFA (TOTP, email OTP)
• Password resets

Public Contracts:

• IIdentityService — User operations
• IMfaProvider — MFA methods (TOTP, email)

Key Services:

• TotpMfaProvider — Google Authenticator
• EmailOtpMfaProvider — Email OTP

Key Actions:

• RegisterUserAction — Create account
• LoginUserAction — Authenticate
• EnableMfaAction — Enable MFA
• ConfirmMfaAction — Verify MFA code

Models:

• User — User account (has many posts, follows, likes)
• MfaChallenge — Active MFA challenge

Database:

• users — User accounts
• mfa_challenges — MFA sessions

Events:

• UserRegistered — New account created
• UserLoggedIn — User authenticated
• MfaEnabled — MFA activated
• EmailVerified — Email confirmed

API Endpoints:

• POST /v1/auth/register — Create account
• POST /v1/auth/login — Authenticate
• POST /v1/auth/mfa/enable — Enable MFA
• POST /v1/auth/mfa/verify — Verify MFA code

See: ./identity/README.md or IDENTITY.md

3️⃣ Ledger Domain#

Status: ✅ Live
Location: app/Ledger/
Purpose: Double-entry accounting, financial integrity

Owned Concepts:

• Double-entry ledger (every transaction has two sides)
• Accounts (cash, holdings, revenue, etc.)
• Transactions (immutable financial records)
• Entries (lines in a transaction, sum to zero)
• Wallet projections (future balance calculations)
• Settlement workflows

Public Contracts:

• ILedgerService — Post transactions (most important)
• IWalletService — Wallet operations

Key Services:

• LedgerService — Core posting logic

Key Actions:

• PostTransactionAction — Record transaction
• ReconcileAccountsAction — Balance check

Models:

• LedgerAccount — Account (cash, holdings, revenue)
• LedgerTransaction — Complete transaction
• LedgerEntry — One side of transaction
• Wallet — User wallet projection

Enums:

• LedgerTransactionType — Type of transaction
• LedgerAccountType — Account category
• AccountHierarchy — Account structure

Database:

• ledger_accounts — All accounts
• ledger_transactions — Complete transactions
• ledger_entries — Transaction lines
• wallets — Wallet projections

Invariants:

• Every transaction must sum to zero (tested in LedgerInvariantTest)
• No negative balances on certain account types
• Immutable entries (no updates, only create)

Events:

• TransactionPosted — Transaction recorded

See: ./ledger/README.md or LEDGER.md

4️⃣ Payments Domain#

Status: ✅ Live
Location: app/Payments/
Purpose: MPESA integration, withdrawal requests, settlements

Owned Concepts:

• MPESA C2B top-ups (customer to business)
• MPESA B2C withdrawals (business to customer)
• Withdrawal requests (user initiates)
• Withdrawal approvals (admin dual-approval)
• Settlement batches (daily withdrawal settlements)
• MPESA callbacks (webhook handlers)

Public Contracts:

• IPaymentProvider — MPESA interface
• IWithdrawalService — Withdrawal operations

Key Services:

• MpesaPaymentProvider — MPESA integration

Key Actions:

• RequestWithdrawalAction — User requests withdrawal
• ApproveWithdrawalAction — Admin approves
• ProcessPaymentAction — Execute MPESA call

Models:

• WithdrawalRequest — User withdrawal
• WithdrawalSettlement — Daily batch
• MpesaCallback — MPESA webhook record

Database:

• withdrawal_requests — User withdrawals
• withdrawal_settlements — Batches
• mpesa_callbacks — Webhook logs

Events:

• WithdrawalRequested — User requested
• WithdrawalApproved — Admin approved
• WithdrawalSettled — Funds sent to MPESA
• PaymentReceived — Top-up from customer

API Endpoints:

• POST /v1/withdrawals — Request withdrawal
• GET /v1/withdrawals/{id} — Get status
• POST /v1/payments/callback/mpesa — MPESA webhook

Depends On:

• Core (authorization, error handling)
• Ledger (post transactions via ILedgerService)

See: ./payments/README.md or PAYMENTS.md

5️⃣ Content Domain#

Status: ✅ Live
Location: app/Content/
Purpose: Posts, media, publishing lifecycle

Owned Concepts:

• Posts (text, image, video, audio, polls, livestreams)
• Media attachments (processing pipeline)
• Post status (draft, published, archived)
• Media variants (thumbnails, multiple resolutions)
• Publishing workflow (draft → publish)
• Media processing (image resize, video transcode)

Public Contracts:

• IContentService — Post operations
• IMediaProcessor — Media processing

Key Services:

• MediaProcessorRegistry — Find processor for media type
• ImagePostProcessor — Process images
• VideoPostProcessor — Process videos

Key Actions:

• CreatePostAction — Create draft
• PublishPostAction — Publish post
• DeletePostAction — Archive/delete
• ProcessMediaAction — Queue processor

Models:

• Post — Core post
• Media — Attachment
• Poll — Poll post
• Livestream — Livestream post

Database:

• posts — Posts table
• post_media — Media attachments
• post_polls — Poll options

Events:

• PostCreated — Draft created
• PostPublished — Published (triggers AI screening, index)
• PostArchived — Archived
• MediaProcessed — Media ready

API Endpoints:

• POST /v1/posts — Create post
• PATCH /v1/posts/{id} — Update draft
• PATCH /v1/posts/{id}/publish — Publish
• DELETE /v1/posts/{id} — Archive

See: ./media/README.md or CONTENT.md

6️⃣ Access Domain#

Status: ✅ Live
Location: app/Access/
Purpose: Access rules, post purchases, visibility gating

Owned Concepts:

• Access rules (who can see each post)
• Rule types (public, tier-gated, purchase-gated, exclusive)
• One-off purchases (buy access to post)
• Access verification (canView? checks)
• Visibility enforcement (don't show restricted posts)

Public Contracts:

• IAccessService — Check access (most important)

Key Services:

• AccessService — canView() logic

Key Actions:

• CreateAccessRuleAction — Set post access
• PurchasePostAction — Buy access to post

Models:

• AccessRule — Gating rule (public/tier/purchase)
• PostPurchase — Purchase record

Database:

• access_rules — Post visibility rules
• post_purchases — Purchase records

Events:

• PostPurchased — User bought access

API Endpoints:

• POST /v1/posts/{id}/rules — Create rule
• POST /v1/purchases — Purchase post
• GET /v1/access-check — Check if can view

Depends On:

• Core (error handling)
• Content (Post model)
• Ledger (via Monetization when billing)

See: ACCESS.md

7️⃣ Discovery Domain#

Status: ✅ Live
Location: app/Discovery/
Purpose: Timelines, search, ranking, signal refresh

Owned Concepts:

• Home timeline (personalized feed)
• Explore timeline (public trending)
• Creator browse (list creators)
• Search (posts by keyword, creator by name)
• Ranking algorithm (weighted scoring)
• Seen suppression (Redis-backed recently seen)
• Signal refresh (refresh recommendation signals)

Public Contracts:

• IRankingService — Score posts
• ISearchService — Full-text search

Key Services:

• TimelineService — Generate timelines
• SearchService — Search posts & creators
• RankingService — Score posts
• SeenPostStore — Redis seen tracking

Models: None (uses Posts from Content)

Database: (Redis for seen posts)

Events: None (consumes posts from Content)

API Endpoints:

• GET /v1/timeline/home — Home feed
• GET /v1/timeline/explore — Explore feed
• GET /v1/creators/browse — Creator browse
• GET /v1/search — Search posts & creators

Depends On:

• Core (authorization)
• Content (Post model)
• Access (check visibility in results)
• Social (follow/like signals)

See: ./discovery/README.md or DISCOVERY.md

8️⃣ Social Domain#

Status: ✅ Live
Location: app/Social/
Purpose: Follows, likes, shares, interactions, blocking, muting

Owned Concepts:

• Follows (follow creator)
• Likes (heart post)
• Saves (save for later)
• Shares (share post)
• Blocks (block user)
• Mutes (mute notifications)
• Interactions (engagement data)

Key Actions:

• FollowCreatorAction — Create follow
• LikePostAction — Create like
• SavePostAction — Save post
• BlockUserAction — Block user

Models:

• Follow — Follow relationship
• Like — Post like
• Save — Saved post
• Block — User block

Database:

• follows — Follow relationships
• likes — Post likes
• saves — Saved posts
• blocks — Block list

Events:

• PostLiked — User liked post
• UserFollowed — User followed creator
• PostShared — User shared post

API Endpoints:

• POST /v1/creators/{id}/follow — Follow
• POST /v1/posts/{id}/like — Like
• POST /v1/posts/{id}/save — Save
• POST /v1/users/{id}/block — Block

See: SOCIAL.md

9️⃣ Monetization Domain#

Status: ✅ Live
Location: app/Monetization/
Purpose: Creator tiers, subscriptions, earnings

Owned Concepts:

• Subscription tiers (creator-defined pricing levels)
• Tier members (subscribers)
• Tier gates (tier-gated content access)
• Earnings forecasting (projected revenue)
• Payout calculations (creator earnings)
• Earnings holds (3-day hold before withdrawal)

Key Actions:

• CreateTierAction — Create tier
• SubscribeTierAction — Subscribe to tier

Models:

• SubscriptionTier — Creator tier
• SubscriptionMember — Tier subscriber

Database:

• subscription_tiers — Creator tiers
• subscription_members — Subscribers

Events:

• TierCreated — Tier created
• TierSubscribed — User subscribed

API Endpoints:

• POST /v1/tiers — Create tier
• POST /v1/tiers/{id}/subscribe — Subscribe

Depends On:

• Core (error handling)
• Access (tier gating)
• Ledger (earnings transactions)

See: ./monetization/README.md or MONETIZATION.md

🔟 FanClub Domain#

Status: ✅ Live
Location: app/FanClub/
Purpose: Creator communities, member management

Owned Concepts:

• Fan clubs (creator community spaces)
• Members (community participants)
• Moderated discussions
• Member-only content
• Exclusivity tiers

Key Actions:

• CreateFanClubAction — Creator creates community
• JoinFanClubAction — Fan joins community

Models:

• FanClub — Community space
• FanClubMember — Member record

Database:

• fan_clubs — Communities
• fan_club_members — Membership

Events:

• FanClubCreated
• MemberJoined

See: FANCLUB.md

1️⃣1️⃣ Moderation Domain#

Status: ✅ Live
Location: app/Moderation/
Purpose: Content moderation, reports, violations, suspensions

Owned Concepts:

• Content reports (user reports inappropriate content)
• Violations (policy breaches)
• AI prescreen (automatic content screening)
• Warnings (first violation)
• Suspensions (account locked)
• Appeal workflows

Key Services:

• AiPrescreenService — AI content filtering

Key Actions:

• ReportContentAction — User reports post
• SuspendAccountAction — Admin suspends account

Models:

• Report — Content report
• Violation — Violation record
• ModerationQueue — Review queue

Database:

• reports — Content reports
• violations — Violation records
• moderation_queue — Admin queue

Events:

• ContentReported
• ContentViolating
• AccountSuspended

Depends On:

• Core (authorization)
• Content (Post model)

See: MODERATION.md

1️⃣2️⃣ Promotions Domain#

Status: ✅ Live
Location: app/Promotions/
Purpose: Referrals, promo codes, campaigns, growth

Owned Concepts:

• Referral codes (invite friends)
• Referral rewards (incentives)
• Promo codes (discount codes)
• Boost campaigns (paid promotion)

Key Actions:

• GenerateReferralCodeAction — Create invite

Models:

• ReferralCode — Referral link
• ReferralReward — Bonus given

Database:

• referral_codes
• referral_rewards

Depends On:

• Ledger (credit rewards via ILedgerService)

See: PROMOTIONS.md

1️⃣3️⃣ Notifications Domain#

Status: ✅ Live
Location: app/Notifications/
Purpose: Email, push, SMS, digest notifications

Owned Concepts:

• Email notifications
• Push notifications
• SMS notifications
• Digest emails (weekly/daily summaries)
• Notification preferences (opt-in/out)

Key Actions:

• SendEmailAction — Queue email
• SendPushAction — Queue push notification

Models:

• NotificationLog — Sent notification record

Events Consumed:

• UserRegistered → send welcome email
• PostPublished → notify followers
• PostPurchased → send confirmation

See: NOTIFICATIONS.md

1️⃣4️⃣ AdminBackoffice Domain#

Status: ✅ Live
Location: app/AdminBackoffice/
Purpose: Admin panel (Filament), operations, dashboards

Owned Concepts:

• Admin resources (CRUD for models)
• Dashboards (analytics, health)
• Admin actions (bulk operations)
• Audit logs
• System configuration

Key Resources:

• UserResource — Manage users
• PostResource — Manage posts
• WithdrawalRequestResource — Approve withdrawals
• PlatformSettingsResource — Configuration

Depends On: All other domains

Note: AdminBackoffice is exception to dependency rule — it depends on all domains for admin operations.

See: ADMIN.md

🔗 References#

Quick Links by Type#

For Getting Started:

• Installation & Setup
• Configuration
• File Structure

For Understanding Domains:

• Each domain README (e.g., app/Domain/README.md)
• Deep-dive wiki (docs/wikis/04-DOMAINS/DOMAIN.md)

For Implementation:

• AGENTS.md — Code standards
• CLAUDE.md — AI dev guide
• loreax-technical-design.md — Detailed spec

✅ Domain Checklist#

When implementing a new domain:

• Create app/Domain/ directory
• Write domain README (app/Domain/README.md)
• Create Models/, Contracts/, Actions/, Services/, Exceptions/, Http/ subdirectories
• Implement service contracts (interfaces)
• Create actions for business logic
• Thin controllers (I/O adapters only)
• Write Unit + Feature tests (≥80% coverage)
• Write OpenAPI annotations
• Update dependencies (which domains depend on this?)
• Create wiki entries
• Add events/listeners
• Document invariants

📞 Support#

• Questions: Check domain README or deep-dive wiki
• Architectural: Review AGENTS.md §9
• Issues: GitHub Issues
• Slack: #loreax-dev

Last Updated: April 25, 2026