Astrology Consultation Platform Architecture: Real-Time Sessions, Wallets, Astrologer Management, and Payouts

An astrology consultation marketplace looks simple on the screen.

A user chooses a practitioner, starts a chat or call, and pays for the time consumed.

But the backend is coordinating far more than a communication feature.

It needs to know whether the astrologer is actually available, whether the user has enough wallet balance, when the session officially begins, what price applies, how long the service runs, how much should be deducted, what commission belongs to the operator, what amount becomes practitioner earnings, and what happens when the connection drops halfway through.

Those events cannot operate independently.

A reliable Astrology Consultation Platform needs an architecture that connects real-time communication, session state, wallet accounting, practitioner availability, commissions, payouts, notifications, admin operations, and failure recovery.

For founders who want to understand the complete product journey before exploring the technical layers, this guide explains how an astrology consultation platform works across discovery, wallet recharge, consultations, practitioner interactions, and admin operations.

For founders, this is the important distinction:

The difficult part is rarely displaying astrologer profiles. The difficult part is keeping session state and money state synchronized when real users begin creating failures, retries, disconnections, refunds, and payout requests.

Start With Architectural Boundaries, Not Framework Names

Founders often begin technical discussions with:

“Should we use Node.js or PHP?”

“Should the database be SQL or NoSQL?”

“Should the frontend use React?”

Those are useful questions, but they come after a more important one:

What responsibilities should be separated inside the platform?

A consultation marketplace can be divided into several logical layers:

Core Architecture Layers

Layer	Responsibility	Why It Matters
User Applications	Discovery, wallet, consultation requests, sessions, reports, history, ratings, and notifications.	Keeps customer interaction separate from backend business rules.
Practitioner Application	Availability, incoming requests, consultation sessions, earnings, schedules, profile, and withdrawal status.	Separates supply-side workflows from customer workflows.
API / Application Layer	Authentication, profiles, search, session creation, wallet actions, pricing, reviews, and business rules.	Creates one authoritative backend for web and mobile clients.
Real-Time Layer	Presence, consultation requests, chat events, session status, timers, queue changes, and balance notifications.	Keeps long-lived sessions synchronized.
RTC / Media Layer	Voice, video, live audio/video, media routing, and call quality.	Prevents the application server from becoming a media server.
Wallet & Ledger	Recharge, debit, bonus, refund, adjustment, commission, and settlement records.	Creates a reconstructable record of money movement.
Background Jobs	Notifications, stale-session cleanup, payout processing, report generation, retry handling, and reconciliation.	Moves slow or retryable work away from user requests.
Operations Console	Users, practitioners, pricing, refunds, commissions, disputes, wallet actions, payouts, and monitoring.	Allows the business to operate without developer intervention for routine tasks.

The exact frameworks can change.

These architectural responsibilities cannot.

Real-Time Consultation Architecture Is a State-Management Problem

Chat and calls are long-lived interactions.

That means a consultation cannot be represented only as “booked” or “completed.”

A practical consultation may move through:

requested → accepted → connecting → active → ending → completed

It may also enter:

rejected, canceled, expired, disconnected, failed, disputed

Every state should have clearly defined rules.

For example:

• Can another user request the same practitioner?
• Has billing started?
• Can the user cancel?
• Should the practitioner appear busy?
• Should wallet balance be reserved?
• Should the session be automatically closed?
• Can a retry reopen the same session?
• Does practitioner earning already exist?

If those rules are scattered across frontend code, WebSocket handlers, payment logic, and database callbacks, edge cases become difficult to reason about.

A better architecture gives the backend one authoritative consultation state.

WebSockets and RTC Solve Different Problems

Founders often combine “real-time” into one technical requirement.

But there are two different real-time problems.

WebSockets: real-time application state

WebSockets are useful for lightweight bidirectional events such as:

• Astrologer online/offline status
• Busy status
• Incoming consultation request
• Request accepted
• Queue position
• Chat messages
• Typing indicators
• Read receipts
• Session start
• Session timer updates
• Low-balance warnings
• Session ended
• Wallet balance updates

RTC: real-time media

Voice and video have different requirements.

Dedicated RTC/WebRTC infrastructure is better suited to:

• Audio transport
• Video transport
• Network adaptation
• Device permissions
• Media quality
• Reconnection
• TURN/STUN handling
• Recording where enabled

The application backend should control whether a session may exist.

The RTC layer should carry its media.

For a deeper implementation-level explanation of real-time events, this guide covers WebSocket architecture for live astrology consultations.

Build the Consultation Session Around a State Machine

A state machine makes consultation rules explicit.

Example Consultation State Flow

State	Backend Responsibility	Money Rule
Requested	Create request, confirm practitioner can receive it, notify practitioner.	No consultation debit yet.
Accepted	Lock or mark practitioner busy and prepare session credentials.	Confirm sufficient balance or eligibility.
Connecting	Create chat/RTC session and wait for both participants.	Avoid billing before the service is actually considered active.
Active	Track authoritative start time and session health.	Meter according to the configured charging rule.
Ending	Stop new metering, close communication channel, finalize duration.	Calculate the final debit once.
Completed	Persist history, enable review, update practitioner status.	Create commission and practitioner earning records.
Failed / Disputed	Preserve logs and reason codes for support review.	Refund or adjustment follows defined business rules.

The important word is authoritative.

The mobile timer is not authoritative.

The practitioner device is not authoritative.

The user’s screen is not authoritative.

The backend should determine the billing-relevant state.

Practitioner Availability Needs Its Own Architecture

Availability sounds simple until thousands of users begin reading and modifying it.

An astrologer may be:

• Offline
• Online
• Available
• Busy
• In chat
• In voice call
• In video call
• On break
• Scheduled for later
• At queue capacity

The platform should not treat “logged in” and “available for consultation” as the same thing.

Why presence becomes difficult

Consider this sequence:

1. Practitioner opens the app.
2. Platform marks them available.
3. User A sends a consultation request.
4. Practitioner accepts.
5. User B sees cached availability and sends another request.
6. Practitioner loses connectivity.
7. Session remains marked active.

Without coordinated state management, the marketplace begins showing false availability.

A robust design combines:

• Persistent practitioner status
• Short-lived presence/heartbeat data
• Session-state locks
• Request expiry
• Queue rules
• Stale-status cleanup jobs

Redis or another fast ephemeral store can be useful for presence and temporary locks, while the primary database keeps durable practitioner and consultation records.

Do Not Let Search Results Become the Source of Availability Truth

Search can cache practitioner profiles.

Availability usually cannot be cached for long.

Profile information such as:

• Languages
• Skills
• Bio
• Rating
• Base rate

changes relatively slowly.

Availability can change in seconds.

Architect the two differently.

The practitioner profile can come from a cached search index or application cache, while the final consultation action should revalidate live availability at the backend.

This prevents the classic problem:

“The screen showed available, but the request failed.”

It may still happen occasionally, but backend revalidation prevents two users from both successfully acquiring the same consultation slot.

Wallet Architecture Should Be Ledger-First

A wallet should not be designed as:

users.wallet_balance = 450

That value alone cannot explain where the money came from or where it went.

Instead, think in events.

A wallet ledger may contain entries such as:

• Recharge +500
• Promotional credit +50
• Chat consultation −120
• Video consultation −200
• Refund +75
• Paid report −100
• Manual correction +20

The visible balance is derived from or reconciled against those records.

Why this matters

When support receives:

“My balance should be 350, not 250.”

the operator needs evidence.

A ledger allows the system to reconstruct the answer.

For deeper payment architecture—including server-side verification, wallet refills, webhook handling, and transaction records—review Miracuves’ guide to wallet refill and payment architecture for astrology platforms.

Payment Verification Should Happen Before Wallet Credit

The frontend can say:

Payment successful.

That does not make the transaction trustworthy.

The backend should validate the payment through the configured gateway flow before creating wallet credit.

A safer flow is:

1. Backend creates payment order.
2. User completes hosted or SDK checkout.
3. Gateway returns status.
4. Backend verifies trusted gateway evidence.
5. System checks order ID and amount.
6. Transaction is checked for duplication.
7. Wallet ledger receives one credit event.
8. User receives updated balance.

This introduces an important architecture principle:

Idempotency

Suppose the payment gateway sends the same success webhook three times.

The user’s wallet should still be credited once.

The same principle applies to:

• Consultation completion
• Refund events
• Payout callbacks
• Commission creation
• Retry jobs

Every money-changing operation should have a stable business identifier so retries do not duplicate financial effects.

Keep Money State Separate From Session UI

The UI may show a timer moving every second.

That does not mean you need to create a permanent financial record every second.

A better approach depends on the charging model.

For example:

• Record authoritative start/end timestamps.
• Push estimated balance to the UI during the session.
• Create billing checkpoints where needed.
• Finalize the authoritative financial amount at defined boundaries.
• Keep enough records to recover from server or client failures.

The exact method depends on business rules.

But one rule should stay constant:

Do not make a client device responsible for deciding the amount owed.

Handle Disconnects as a First-Class State

Users lose connectivity.

Practitioners close applications.

Mobile operating systems suspend background processes.

RTC connections fail.

Servers restart.

These are normal operating conditions.

Define rules for:

• Temporary disconnection
• Reconnection window
• User never joining
• Practitioner never joining
• Practitioner disconnecting
• User disconnecting
• Both participants disconnecting
• Server missing end event
• RTC provider callback delayed

The architecture should determine when billing pauses, continues, ends, or requires operator review.

Without those rules, technical failures become financial disputes.

Astrologer Management Is More Than Profile CRUD

A practitioner system needs to manage both identity and marketplace operations.

Typical practitioner domains include:

Profile

• Name
• Languages
• Skills
• Experience
• Biography
• Profile photo
• Consultation categories

Marketplace state

• Approval status
• Online status
• Availability
• Queue state
• Consultation permissions
• Rate
• Promotional eligibility

Reputation

• Reviews
• Ratings
• Complaints
• Restrictions
• Moderation status

Financial state

• Gross earnings
• Commission
• Adjustments
• Refund impact
• Pending earnings
• Available withdrawal balance
• Payout history

Founders mapping these modules can review the core consultation platform features required across customer, practitioner, wallet, real-time session, and operator workflows.

These should not all live in one giant practitioner table.

Architect around clear entities and responsibilities so changes in one area do not accidentally affect another.

Founders evaluating the complete product surface can also review the consultation platform feature architecture across customer, practitioner, wallet, real-time, and admin workflows.

Separate Profile Data From Availability Data

This architectural split deserves emphasis.

Practitioner profile data is durable.

Availability is highly volatile.

A common pattern is:

Primary database: profile, pricing, skills, approvals, permanent schedule

Fast ephemeral layer: presence, active session, temporary queue, last heartbeat

That prevents constant availability writes from unnecessarily loading the primary profile data path.

It also simplifies scaling when more real-time users arrive.

Commission Logic Should Be Deterministic

Once the consultation ends, the platform needs to decide:

• Gross consultation value
• Operator share
• Practitioner share
• Promotional effect
• Refund effect
• Applicable withholding or adjustments
• Final practitioner earning

This logic should be deterministic.

The same input should produce the same result.

Avoid hiding commission calculations in frontend code or manual spreadsheets.

Ideally:

session record → pricing snapshot → billing result → commission result → practitioner earning

Store the relevant pricing context that applied to the session.

Why?

Because the practitioner rate may change tomorrow.

That should not change yesterday’s earning calculation.

Snapshot Pricing When the Session Begins

Suppose the practitioner charges 20 units per minute today and 25 tomorrow.

If historical consultation billing simply points to the practitioner’s current rate, old records can become impossible to reconcile.

Store a pricing snapshot with the transaction or session:

• Applied practitioner rate
• Applied currency
• Commission rule
• Promotion
• Conversion rate where relevant
• Pricing version if required

Historical financial records should explain what actually happened at the time.

Payout Architecture Starts Before Withdrawal

Many teams think payout architecture means integrating a bank-transfer API.

That is the last stage.

The real payout pipeline begins when the consultation is settled.

A simplified flow is:

completed consultation
→ gross earning
→ commission calculation
→ adjustments/refunds
→ practitioner pending balance
→ eligible balance
→ withdrawal request
→ approval/risk checks
→ payout provider
→ payout result
→ reconciliation

Each transition should be traceable.

Practitioner Payout Architecture

Layer	What It Tracks	Failure to Avoid
Earning Record	Practitioner share generated by a completed paid service.	Recalculating old earnings from current pricing.
Pending Balance	Earnings waiting for settlement window or dispute period.	Making unsettled earnings withdrawable too early.
Adjustment Layer	Refunds, reversals, promotional effects, or operator corrections.	Editing historical earnings without an explanatory record.
Withdrawal Request	Amount requested, payout destination, status, and timestamps.	Allowing two simultaneous withdrawals against the same balance.
Payout Execution	Provider request, provider reference, success/failure state.	Treating a request sent to the provider as confirmed payment.
Reconciliation	Matches internal payout records with provider/bank results.	Manual payout spreadsheets that disagree with marketplace records.

Use Database Transactions for Financial Boundaries

Consider session settlement:

1. Mark session complete.
2. Calculate final charge.
3. Debit wallet.
4. Create commission.
5. Create practitioner earning.

If step 3 succeeds but step 4 fails, the platform is inconsistent.

Critical money transitions should use database transaction boundaries or another consistency mechanism appropriate to the architecture.

The exact implementation depends on system scale.

The architectural principle does not:

A financial workflow should either complete as a consistent unit or have a reliable recovery path.

Background Jobs Should Handle Slow or Retryable Work

Not everything should happen inside the user’s request.

Good candidates for queues include:

• Push notifications
• Email
• SMS
• Report generation
• Payout execution
• Settlement exports
• Stale consultation cleanup
• Practitioner status cleanup
• Retryable webhooks
• Recording processing
• Analytics events

This keeps API requests fast and makes failures retryable.

But queues introduce another requirement:

Jobs must be idempotent too.

If a payout job retries, it cannot create a second payout.

APIs Should Express Business Actions, Not Database Tables

Avoid designing APIs purely around CRUD.

Instead of thinking only in terms of:

POST /consultations
PUT /consultations/123

think about real business actions:

POST /consultations/request
POST /consultations/{id}/accept
POST /consultations/{id}/join
POST /consultations/{id}/end
POST /wallet/recharge
POST /withdrawals/request
POST /refunds/{id}/approve

The backend can then enforce the rules for each transition.

This makes authorization and auditing clearer because the API expresses what the user is trying to do.

Admin Architecture Should Mirror Operational Responsibilities

An admin dashboard is not one role.

Different teams may need different access:

Practitioner operations

• Approvals
• Suspensions
• Skills
• Availability issues
• Profile moderation

Support

• Consultation history
• Failed sessions
• Refund cases
• User complaints

Finance

• Wallet transactions
• Commission
• Earnings
• Withdrawals
• Payout reconciliation

Content

• Horoscope content
• Reports
• Promotional pages

Platform administration

• Pricing
• Integrations
• Feature configuration
• Role permissions

Use role-based access so support staff do not automatically gain the ability to modify payout or wallet settings.

Security should be treated as an operational foundation rather than a marketing feature, and compliance claims should remain tied to the actual jurisdiction, integrations, and operating model.

Observability Matters More Than Another Dashboard Chart

When something breaks, founders need to answer:

• Which consultation failed?
• Which service failed?
• Which user was affected?
• Was wallet balance changed?
• Did the practitioner receive an earning?
• Did the payment gateway send a callback?
• Did the payout provider respond?
• Was the job retried?
• Which admin changed the record?

Architecture should therefore include:

• Structured application logs
• Correlation/session IDs
• Error monitoring
• Job-failure monitoring
• Payment references
• RTC/session references
• Activity logs
• Database metrics
• API latency/error metrics

For real-time marketplaces, support quality often depends on observability more than UI polish.

Scaling: Sessions Matter More Than Page Views

A content website can often scale by caching pages aggressively.

A consultation marketplace behaves differently.

Long-lived state creates the pressure:

• Active WebSocket connections
• Concurrent consultations
• Presence updates
• Session timers
• RTC signaling
• Wallet events
• Notification fan-out

Therefore, founders should monitor:

• Concurrent connected users
• Concurrent active consultations
• WebSocket connection count
• Event throughput
• Queue depth
• Database write rate
• Wallet ledger growth
• RTC provider usage
• Failed sessions

The platform should scale around the real bottleneck rather than around generic requests-per-second benchmarks.

Keep External Providers Behind Interfaces

Consultation marketplaces may depend on:

• RTC providers
• OTP providers
• Payment gateways
• Push notifications
• Storage providers
• AI providers
• Astrology calculation APIs

Avoid spreading provider-specific code throughout the product.

Use an abstraction layer.

For example:

RtcProvider
  ├── createSession()
  ├── createToken()
  ├── endSession()
  └── fetchSessionStatus()

For founders planning AI-assisted experiences alongside human consultations, Miracuves’ white-label AI astrology platform provides a useful reference for connecting AI guidance, reports, wallet billing, and practitioner escalation within one product ecosystem.

Then each vendor implementation can sit behind the interface.

This makes provider replacement and multi-market deployment much easier.

It also keeps core business logic independent of external SDKs.

Design for Failure, Not Only the Happy Path

Architecture reviews should deliberately test:

• Duplicate payment webhook
• Duplicate consultation end event
• User reconnect
• Practitioner reconnect
• RTC provider timeout
• OTP provider outage
• Payment pending for several minutes
• Queue worker crash
• Payout timeout
• Refund after practitioner earning exists
• Pricing change during an active session
• Two withdrawal requests at the same time
• Admin adjustment while payout is pending

The quality of the platform is often determined by how well these unusual paths are handled.

Founder Decision Signals

Architecture Checklist Before Development or Replatforming

Before committing to a technical design, founders and engineering teams should confirm:

• Are customer and practitioner workflows separated clearly?
• Is the backend authoritative for consultation state?
• Are WebSocket responsibilities separated from audio/video media?
• Is there a defined consultation state machine?
• Can one practitioner accept two sessions accidentally?
• How are stale presence records cleaned up?
• Is pricing snapshotted when a session starts?
• Is the wallet ledger reconstructable?
• Are money-changing operations idempotent?
• Are payment webhooks verified server-side?
• Can session settlement run twice?
• How are refunds linked to original transactions?
• How is practitioner earning derived?
• When does earning become withdrawable?
• Can two withdrawal requests spend the same balance?
• Are external providers behind interfaces?
• Which tasks belong in queues?
• How are failed jobs retried?
• Can support trace a session across logs?
• Can finance reconcile wallet and payout records?
• Are admin roles permission-based?
• How does the platform recover from external-provider outages?

If you are still defining the initial product scope, this guide to essential astrology platform features can help separate launch-critical consultation, wallet, practitioner, and admin workflows from secondary additions.

Teams comparing ready-made foundations can also review these ready-made astrology platform options to understand how feature scope, integrations, and pricing considerations affect implementation planning.

If those answers are clear, framework selection becomes easier because the architecture already describes what the technology has to accomplish.

Mistakes Founders Should Avoid

How Miracuves Supports a Launch-Ready Consultation Architecture

Miracuves helps founders launch white-label consultation marketplaces with customer and practitioner workflows, real-time consultation infrastructure, wallet billing, admin control, and source-code ownership.

For teams moving from architecture planning into implementation, this guide on choosing an astrology platform development partner explains what to evaluate around technical delivery, real-time infrastructure, integrations, source-code ownership, and production readiness.

Founders who want to examine a ready-made product foundation can review Miracuves’ astrology consultation marketplace platform after defining their architecture, practitioner model, wallet rules, and target-market integrations.

For deeper commercial planning around commissions, consultation earnings, wallet consumption, and practitioner economics, review the consultation marketplace business model separately.

Once the session architecture, wallet rules, practitioner workflows, integrations, and payout requirements are defined, founders can review astrology consultation platform development cost to understand how technical scope affects the final customization and launch budget.

If the ready-made scope fits the requirements, Miracuves can support 6-day solution delivery, while external provider accounts, payment onboarding, production credentials, store publishing, customization, and pre-launch hardening should still be planned as part of the launch process.

Final Thoughts: The Architecture Must Keep Service State and Money State Together

An astrology consultation platform is not difficult because it has profiles, filters, or horoscope pages.

The difficult architecture sits underneath the consultation.

The platform has to know who is available, who accepted the session, whether both parties connected, when billing started, what rate applied, how much balance remains, when the session ended, what commission was earned, what amount belongs to the practitioner, and whether that earning was later refunded or paid out.

Those systems cannot be designed independently.

Real-time sessions need wallet awareness.

Wallets need authoritative session events.

Practitioner management needs real-time availability.

Commission needs historical pricing.

Payouts need reliable earning records.

Admin operations need visibility across all of them.

For founders, that is the main architecture lesson:

Build the platform around trustworthy state transitions first. The screens can change later.

FAQs