pos-system/services/mining-service-net/SERVICE_DOCS.md

MiningService - Service Documentation

1. Overview

Purpose: Pi Network-style point mining service. Users ("miners") earn Mining Points (MP) over time through 24-hour mining sessions. The service manages miner profiles, mining sessions with streak bonuses, security circles (trusted groups for bonus multipliers), and referral programs.

Port: 5006 (Development, via launchSettings.json) / 8080 (Docker/Production)

Database: PostgreSQL -- mining_service on Neon PostgreSQL (ep-holy-glitter-a4hongg7-pooler.us-east-1.aws.neon.tech)

Solution: MiningService.slnx

Target Framework: .NET 10.0, C# 14

Architecture: Clean Architecture + CQRS (MediatR)

Real-time: SignalR Hub at /hubs/mining for live mining updates

Auth: JWT Bearer (Duende IdentityServer), with SignalR token via query string

---

2. API Endpoints

MiningController (/api/v1/mining) -- [Authorize]

Method	Route	Description	Request	Response
GET	/api/v1/mining/me?userId={guid}	Get current miner status	Query: userId (Guid)	MinerStatusDto or 404
POST	/api/v1/mining/start	Start a new 24h mining session	Body: StartMiningRequest { UserId }	StartMiningResult
POST	/api/v1/mining/claim	Claim mining reward from completed session	Body: ClaimMiningRequest { UserId }	ClaimMiningRewardResult
GET	/api/v1/mining/history?userId={guid}&page=1&pageSize=20	Get mining history (paginated)	Query params	MiningHistoryDto
GET	/api/v1/mining/rate?userId={guid}	Get current mining rate breakdown	Query: userId (Guid)	MiningRateDto or 404
GET	/api/v1/mining/leaderboard?limit=100	Get top miners leaderboard	Query: limit (int)	LeaderboardDto -- [AllowAnonymous]

CirclesController (/api/v1/circles) -- [Authorize]

Method	Route	Description	Request	Response
GET	/api/v1/circles/me?userId={guid}	Get user's circle	Query: userId (Guid)	CircleDto or 404
POST	/api/v1/circles	Create a new security circle	Body: CreateCircleRequest { UserId, Name }	CreateCircleResult (201)
POST	/api/v1/circles/invite	Invite a member to circle	Body: InviteMemberRequest { UserId, TargetMinerId }	200 message
POST	/api/v1/circles/accept/{inviteId}?userId={guid}	Accept circle invitation	Path: inviteId, Query: userId	AcceptCircleInviteResult
DELETE	/api/v1/circles/members/{memberId}?ownerId={guid}	Remove member from circle	Path: memberId, Query: ownerId	RemoveCircleMemberResult
GET	/api/v1/circles/trust-score?userId={guid}	Get circle trust score	Query: userId (Guid)	CircleTrustScoreDto or 404

ReferralsController (/api/v1/referrals) -- [Authorize]

Method	Route	Description	Request	Response
GET	/api/v1/referrals?userId={guid}	Get referral code and referrals list	Query: userId (Guid)	ReferralsDto
POST	/api/v1/referrals/apply	Apply a referral code	Body: ApplyReferralRequest { UserId, ReferralCode }	ApplyReferralResult
GET	/api/v1/referrals/code?userId={guid}	Get my referral code	Query: userId (Guid)	ReferralCodeDto or 404
GET	/api/v1/referrals/stats?userId={guid}	Get referral statistics	Query: userId (Guid)	ReferralStatsDto or 404

AdminController (/api/v1/admin) -- [Authorize(Roles = "Admin")]

Configuration

Method	Route	Description	Request	Response
GET	/api/v1/admin/config	Get all system configuration	--	SystemConfigDto
PUT	/api/v1/admin/config	Update system configuration	Body: UpdateSystemConfigCommand	UpdateConfigResult
GET	/api/v1/admin/config/mining	Get mining configuration	--	MiningConfigDto
PUT	/api/v1/admin/config/mining	Update mining configuration	Body: UpdateMiningConfigCommand	UpdateConfigResult
GET	/api/v1/admin/config/streak	Get streak configuration	--	StreakConfigDto
PUT	/api/v1/admin/config/streak	Update streak configuration	Body: UpdateStreakConfigCommand	UpdateConfigResult
GET	/api/v1/admin/config/referral	Get referral configuration	--	ReferralConfigDto
PUT	/api/v1/admin/config/referral	Update referral configuration	Body: UpdateReferralConfigCommand	UpdateConfigResult

Miner Management

Method	Route	Description	Request	Response
GET	/api/v1/admin/miners?page=1&pageSize=20&search=	List all miners (paginated)	Query params	MinersListDto
GET	/api/v1/admin/miners/{id}	Get miner details	Path: id (Guid)	MinerDetailsDto or 404
PUT	/api/v1/admin/miners/{minerId}/suspend	Suspend a miner account	Body: SuspendRequest { Reason }	200 message
PUT	/api/v1/admin/miners/{minerId}/ban	Ban a miner account	Body: BanRequest { Reason }	BanMinerResult
PUT	/api/v1/admin/miners/{minerId}/restore	Restore a suspended miner	--	200 message
PUT	/api/v1/admin/miners/{minerId}/adjust-points	Adjust miner points	Body: AdjustPointsRequest { Amount, Reason }	AdjustPointsResult
PUT	/api/v1/admin/miners/{minerId}/reset-streak	Reset miner streak	Body: ResetStreakRequest { Reason }	ResetStreakResult

Analytics

Method	Route	Description	Response
GET	/api/v1/admin/analytics/overview	Admin dashboard overview	AdminOverviewDto
GET	/api/v1/admin/analytics/miners	Miner analytics	MinerAnalyticsDto
GET	/api/v1/admin/analytics/circles	Circle analytics	CircleAnalyticsDto (stub)
GET	/api/v1/admin/analytics/referrals	Referral analytics	ReferralAnalyticsDto (stub)
GET	/api/v1/admin/analytics/points	Points analytics	PointsAnalyticsDto (stub -- no handler)
GET	/api/v1/admin/analytics/streaks	Streak analytics	StreakAnalyticsDto (stub -- no handler)
GET	/api/v1/admin/audit-logs?page=1&pageSize=50	Audit logs	AuditLogsDto (stub -- no handler)

Health Endpoints (no auth)

Route	Description
/health	Full health check (includes PostgreSQL)
/health/live	Liveness probe (app is running)
/health/ready	Readiness probe (ready for traffic)

SignalR Hub

Endpoint	/hubs/mining
JoinMinerGroup(minerId)	Subscribe to personal mining updates
LeaveMinerGroup(minerId)	Unsubscribe from personal mining updates
JoinLeaderboardGroup()	Subscribe to leaderboard updates

Server-to-client messages via IMiningHubService:

• PointsUpdated -- { earnedPoints, totalPoints, streakDays }
• SessionStarted -- { endTime, hourlyRate }
• StreakMilestone -- { streakDays, bonusPoints }

---

3. Commands

Core Commands

Command	Parameters	Result	Handler
StartMiningCommand	UserId (Guid)	StartMiningResult { SessionId, HourlyRate, EndTime, StreakDays }	Validates miner active, no existing session. Recalculates rate, creates MiningSession.
ClaimMiningRewardCommand	UserId (Guid)	ClaimMiningRewardResult { PointsEarned, TotalPoints, StreakDays, StreakBonus }	Validates session ready to claim. Calculates points, increments streak, adds milestone bonuses, creates MiningHistory entries.
CreateCircleCommand	UserId (Guid), Name (string)	CreateCircleResult { CircleId, Name }	Validates miner exists, not already in/owning a circle. Creates Circle with owner as first member.
InviteToCircleCommand	UserId (Guid), TargetMinerId (Guid)	bool	Validates inviter owns a circle, target not in a circle. Adds member, recalculates rates if circle becomes valid.
ApplyReferralCodeCommand	UserId (Guid), ReferralCode (string)	ApplyReferralResult { ReferralId, ReferrerId, IsActive }	Validates no existing referrer, valid code, not self-referral. Creates inactive Referral (pending KYC).

Circle Management Commands

Command	Parameters	Result	Handler
AcceptCircleInviteCommand	UserId (Guid), InviteId (Guid)	AcceptCircleInviteResult { Success, Message }	Simplified: adds user as member to circle by InviteId.
RemoveCircleMemberCommand	OwnerId (Guid), MemberId (Guid)	RemoveCircleMemberResult { Success, Message }	Validates owner owns circle. Calls circle.RemoveMember().

Admin Commands

Command	Parameters	Result	Handler
SuspendMinerCommand	MinerId (Guid), Reason (string)	bool	Calls miner.Suspend().
RestoreMinerCommand	MinerId (Guid)	bool	Calls miner.Restore().
BanMinerCommand	MinerId (Guid), Reason (string)	BanMinerResult { Success, Message }	Calls miner.Suspend() (note: uses Suspend, not Ban).
AdjustMinerPointsCommand	MinerId (Guid), Amount (decimal), Reason (string)	AdjustPointsResult { Success, NewBalance, Message }	Calls miner.AddBonusPoints().
ResetMinerStreakCommand	MinerId (Guid), Reason (string)	ResetStreakResult { Success, Message }	Stub -- saves but does not actually reset streak.
UpdateSystemConfigCommand	Mining?, Streak?, Referral?	UpdateConfigResult { Success, Message }	Stub -- returns success without persisting.
UpdateMiningConfigCommand	BaseRate?, SessionDurationHours?, MaxSessionsPerDay?	UpdateConfigResult	No dedicated handler (uses UpdateSystemConfigCommandHandler pattern).
UpdateStreakConfigCommand	Tiers?, GracePeriodDays?	UpdateConfigResult	No dedicated handler registered.
UpdateReferralConfigCommand	BonusPerReferral?, MaxBonusCap?, KycRequired?	UpdateConfigResult	Stub handler -- returns success without persisting.

---

4. Queries

Query	Parameters	Returns
GetMinerStatusQuery	UserId (Guid)	MinerStatusDto? { MinerId, Role, TotalMinedPoints, HourlyRate, DailyRate, CurrentStreak, LongestStreak, StreakBonus, HasActiveSession, SessionEndTime, Status }
GetMiningHistoryQuery	UserId, Page, PageSize	MiningHistoryDto { Items[], TotalCount, Page, PageSize } -- in-memory pagination from miner's histories
GetMiningRateQuery	UserId (Guid)	MiningRateDto? { BaseRate, RoleMultiplier, CircleBonus, ReferralBonus, StreakBonus, TotalRate, HourlyPoints, DailyPoints }
GetLeaderboardQuery	Limit (int, default 100)	LeaderboardDto { Entries[] } -- top miners by TotalMinedPoints
GetCircleQuery	UserId (Guid)	CircleDto? { CircleId, Name, OwnerId, MemberCount, TrustScore, BonusMultiplier, IsValid, Status, Members[] }
GetCircleTrustScoreQuery	UserId (Guid)	CircleTrustScoreDto? { CircleId, Name, MemberCount, TrustScore, IsValid, BonusMultiplier }
GetReferralsQuery	UserId (Guid)	ReferralsDto { MyReferralCode, TotalReferrals, ActiveReferrals, TotalBonusPercent, Referrals[] }
GetReferralCodeQuery	UserId (Guid)	ReferralCodeDto? { ReferralCode, ShareUrl } -- URL: https://goodgo.app/invite/{code}
GetReferralStatsQuery	UserId (Guid)	ReferralStatsDto? { ReferralCode, TotalReferrals, ActiveReferrals, PendingReferrals, TotalEarned, CurrentBonusRate }
GetSystemConfigQuery	--	SystemConfigDto { Mining, Streak, Referral } -- loads from in-memory ConfigurationRepository
GetReferralConfigQuery	--	ReferralConfigDto { BonusPerReferral, MaxBonusCap, KycRequired }
GetAdminOverviewQuery	--	AdminOverviewDto { TotalMiners, ActiveMiners, MinersWithActiveSession, TotalPointsMined, TotalCircles, ValidCircles, TotalReferrals, ActiveReferrals } -- uses DbContext directly
GetMinersListQuery	Page, PageSize, Search?	MinersListDto { Items[], TotalCount, Page, PageSize }
GetMinerDetailsQuery	MinerId (Guid)	MinerDetailsDto? -- full miner detail including rate, streak, circle
GetMinerAnalyticsQuery	--	MinerAnalyticsDto { TotalMiners, ActiveMiners, SuspendedMiners, TotalPointsMined, PointsMinedToday, RoleDistribution }
GetCircleAnalyticsQuery	--	CircleAnalyticsDto -- stub, returns zeros
GetReferralAnalyticsQuery	--	ReferralAnalyticsDto -- stub, returns zeros
GetPointsAnalyticsQuery	--	PointsAnalyticsDto -- no handler registered
GetStreakAnalyticsQuery	--	StreakAnalyticsDto -- no handler registered
GetAuditLogsQuery	Page, PageSize	AuditLogsDto -- no handler registered

---

5. Domain Model

Aggregates

Miner (Aggregate Root)

• File: MiningService.Domain/AggregatesModel/MinerAggregate/Miner.cs
• Properties: UserId, Role (MinerRole), TotalMinedPoints, CurrentRate (MiningRate, owned), ActiveSession (MiningSession?, owned), Streak (MiningStreak, owned), ReferralCode, ReferredById?, CircleId?, Status (MinerStatus), CreatedAt, UpdatedAt, RowVersion (concurrency token), MiningHistories (collection)
• Factory: Miner.Create(userId, referralCode?, referredById?) -- generates 8-char alphanumeric referral code, raises MinerCreatedDomainEvent
• Behavior Methods:
  • StartMiningSession(baseRate, sessionHours) -- validates active status, no existing session; recalculates rate; creates session; raises MiningSessionStartedDomainEvent
  • ClaimMiningReward() -- validates session ready; calculates points + streak milestone bonuses; increments streak; creates MiningHistory entries; raises PointsMinedDomainEvent
  • RecalculateRate(baseRate, circleBonus, referralBonus) -- computes TotalRate formula
  • UpgradeRole(newRole) -- only allows upgrades
  • JoinCircle(circleId) -- auto-upgrades Pioneer to Contributor
  • LeaveCircle() -- auto-downgrades Contributor to Pioneer
  • Suspend(), Restore(), Ban() -- status transitions
  • AddBonusPoints(points, source), DeductPoints(points, reason) -- with history tracking

Milestone Bonuses (on streak claim):

Streak Day	Bonus MP
7	50
14	100
30	300
60	500
90	1000

Circle (Aggregate Root)

• File: MiningService.Domain/AggregatesModel/CircleAggregate/Circle.cs
• Properties: OwnerId, Name, TrustScore (0-100), BonusMultiplier, Status (CircleStatus), CreatedAt, UpdatedAt, Members (collection of CircleMember)
• Constants: MinMembers = 3, MaxMembers = 5, ValidCircleBonus = 0.25m (25%)
• Computed: ActiveMemberCount, IsValid (Active status + 3+ active members)
• Factory: Circle.Create(ownerId, name) -- owner auto-added as first member, status = Incomplete
• Behavior Methods:
  • AddMember(minerId) -- validates not disbanded, max 5, not duplicate; recalculates status; raises CircleCompletedDomainEvent when reaching 3 members
  • RemoveMember(minerId) -- cannot remove owner; deactivates member
  • Disband() -- sets Disbanded, zeroes bonus, deactivates all members
• Trust Score: 3 members = 60, 4 = 80, 5 = 100

CircleMember (Entity)

• File: MiningService.Domain/AggregatesModel/CircleAggregate/CircleMember.cs
• Properties: CircleId, MinerId, JoinedAt, IsActive
• Methods: Deactivate(), Activate()

Referral (Aggregate Root)

• File: MiningService.Domain/AggregatesModel/ReferralAggregate/Referral.cs
• Properties: ReferrerId, ReferredId, ReferralCode, BonusRate (default 0.25 = 25%), IsActive, Level (default 1), CreatedAt, ActivatedAt?
• Factory: Referral.Create(referrerId, referredId, referralCode, bonusRate, level) -- validates no self-referral, starts inactive
• Behavior Methods:
  • Activate() -- sets active + timestamp; raises ReferralActivatedDomainEvent
  • Deactivate() -- sets inactive
  • CalculateBonus(baseRate) -- returns baseRate * BonusRate if active, else 0

MiningHistory (Entity, child of Miner)

• File: MiningService.Domain/AggregatesModel/MinerAggregate/MiningHistory.cs
• Properties: MinerId, PointsEarned, Source, SessionId?, EarnedAt, HourlyRateSnapshot, StreakDaySnapshot
• Factories: CreateFromSession(...), CreateFromBonus(...)

Configuration Aggregates (in-memory, not persisted to DB)

MiningConfiguration

• Properties: BaseRate (0.25), SessionDurationHours (24), MaxSessionsPerDay (1), IsGloballyEnabled (true), UpdatedAt, UpdatedBy

StreakConfiguration

• Properties: Tiers (collection of StreakTier), GracePeriodEnabled (true), GracePeriodHours (24), RecoveryCost (50 MP), FreezeTokenDays (7), UpdatedAt, UpdatedBy
• Default Tiers:

MinDays	MaxDays	BonusPercent	BadgeName	MilestoneMpBonus
1	2	0%	--	0
3	6	10%	3-day badge	0
7	13	25%	7-day badge	50
14	29	50%	14-day badge	100
30	59	100%	30-day badge	300
60	89	125%	60-day badge	500
90	MAX	150%	90-day badge	1000

ReferralConfiguration

• Properties: BonusPercentPerReferral (0.25), MaxBonusPercent (1.0 = 100%), KycRequired (true), MaxReferralLevels (1), UpdatedAt, UpdatedBy

Value Objects

MiningRate (record)

• BaseRate, RoleBonus, CircleBonus, ReferralBonus, StreakBonus
• TotalRate = BaseRate * (1 + Role) * (1 + Circle) * (1 + Referral) * (1 + Streak)
• DailyRate = TotalRate * 24
• Default: BaseRate = 0.25 MP/hour

MiningStreak (record)

• CurrentStreak, LongestStreak, LastMiningDate, FreezeTokens, IsGracePeriod
• BonusMultiplier: 0% (days 1-2), 10% (3-6), 25% (7-13), 50% (14-29), 100% (30-59), 125% (60-89), 150% (90+)
• IncrementStreak() -- earns 1 freeze token per 7 days
• Reset() -- zeroes CurrentStreak

MiningSession (record)

• SessionId, StartTime, EndTime, HourlyRate, Status (MiningSessionStatus), AccumulatedPoints
• IsReadyToClaim -- Active status and EndTime passed
• CalculateEarnedPoints() -- elapsed hours * HourlyRate, capped at 24h
• MarkAsClaimed(earnedPoints) -- sets Claimed status

Enumerations

MinerRole

Value	Name	Bonus
0	Pioneer	0% (base user)
1	Contributor	+10% (has valid circle)
2	Ambassador	+25% (5+ referrals)
3	NodeOperator	+50% (runs node software)

MinerStatus

Value	Name
0	Active
1	Suspended
2	Banned

MiningSessionStatus

Value	Name
0	Active
1	Completed
2	Claimed
3	Expired

CircleStatus

Value	Name
0	Incomplete (< 3 members)
1	Active (3-5 members, valid for bonus)
2	Disbanded

Domain Exceptions

• MiningDomainException -- base exception
• MinerNotFoundException -- miner not found by ID or UserId
• CircleDomainException -- circle operation failures
• ReferralDomainException -- referral operation failures

---

6. Database Schema

Database: mining_service (PostgreSQL)

Migration: 20260117103924_InitialCreate

Table: Miners

Column	Type	Constraints
Id	uuid	PK
UserId	uuid	NOT NULL, UNIQUE (IX_Miners_UserId)
Role	varchar(20)	NOT NULL, string conversion of MinerRole enum
TotalMinedPoints	numeric(18,4)	NOT NULL
CurrentRate_BaseRate	numeric(18,4)	NOT NULL (owned type)
CurrentRate_RoleBonus	numeric(5,4)	NOT NULL (owned type)
CurrentRate_CircleBonus	numeric(5,4)	NOT NULL (owned type)
CurrentRate_ReferralBonus	numeric(5,4)	NOT NULL (owned type)
CurrentRate_StreakBonus	numeric(5,4)	NOT NULL (owned type)
ActiveSession_SessionId	uuid	NULLABLE (owned type)
ActiveSession_StartTime	timestamp with time zone	NULLABLE
ActiveSession_EndTime	timestamp with time zone	NULLABLE
ActiveSession_HourlyRate	numeric(18,4)	NULLABLE
ActiveSession_Status	varchar(20)	NULLABLE
ActiveSession_AccumulatedPoints	numeric(18,4)	NULLABLE
Streak_CurrentStreak	integer	NOT NULL (owned type)
Streak_LongestStreak	integer	NOT NULL
Streak_LastMiningDate	timestamp with time zone	NOT NULL
Streak_FreezeTokens	integer	NOT NULL
Streak_IsGracePeriod	boolean	NOT NULL
ReferralCode	varchar(10)	NOT NULL, UNIQUE (IX_Miners_ReferralCode)
ReferredById	uuid	NULLABLE
CircleId	uuid	NULLABLE
Status	varchar(20)	NOT NULL
CreatedAt	timestamp with time zone	NOT NULL
UpdatedAt	timestamp with time zone	NOT NULL
RowVersion	bytea	NOT NULL, row version (concurrency token)

Indexes: IX_Miners_UserId (unique), IX_Miners_ReferralCode (unique)

Table: MiningHistories

Column	Type	Constraints
Id	uuid	PK
MinerId	uuid	NOT NULL, FK -> Miners (CASCADE)
PointsEarned	numeric(18,4)	NOT NULL
Source	varchar(50)	NOT NULL
SessionId	uuid	NULLABLE
EarnedAt	timestamp with time zone	NOT NULL
HourlyRateSnapshot	numeric(18,4)	NOT NULL
StreakDaySnapshot	integer	NOT NULL

Indexes: IX_MiningHistories_MinerId_EarnedAt (composite)

Table: Circles

Column	Type	Constraints
Id	uuid	PK
OwnerId	uuid	NOT NULL
Name	varchar(100)	NOT NULL
TrustScore	numeric(5,2)	NOT NULL
BonusMultiplier	numeric(5,4)	NOT NULL
Status	varchar(20)	NOT NULL
CreatedAt	timestamp with time zone	NOT NULL
UpdatedAt	timestamp with time zone	NOT NULL

Indexes: IX_Circles_OwnerId

Table: CircleMembers

Column	Type	Constraints
Id	uuid	PK
CircleId	uuid	NOT NULL, FK -> Circles (CASCADE)
MinerId	uuid	NOT NULL
JoinedAt	timestamp with time zone	NOT NULL
IsActive	boolean	NOT NULL

Indexes: IX_CircleMembers_CircleId_MinerId (unique composite), IX_CircleMembers_MinerId

Table: Referrals

Column	Type	Constraints
Id	uuid	PK
ReferrerId	uuid	NOT NULL
ReferredId	uuid	NOT NULL, UNIQUE (IX_Referrals_ReferredId)
ReferralCode	varchar(10)	NOT NULL
BonusRate	numeric(5,4)	NOT NULL
IsActive	boolean	NOT NULL
Level	integer	NOT NULL
CreatedAt	timestamp with time zone	NOT NULL
ActivatedAt	timestamp with time zone	NULLABLE

Indexes: IX_Referrals_ReferrerId, IX_Referrals_ReferredId (unique)

Note: Table names use PascalCase (e.g., Miners, MiningHistories), not the platform-standard snake_case. Value objects (MiningRate, MiningStreak, MiningSession) are stored as owned types with {OwnerProperty}_{ValueProperty} column naming.

---

7. Integration Events

Published Events (outbound)

Event	Fields	Description
PointsMinedIntegrationEvent	EventId, OccurredOn, UserId, MinerId, Points, Source, StreakDays	Points mined, should be credited to wallet
ReferralActivatedIntegrationEvent	EventId, OccurredOn, ReferrerId, ReferredUserId, BonusRate	Referral activated after KYC
CircleCompletedIntegrationEvent	EventId, OccurredOn, CircleId, OwnerId, MemberCount, BonusMultiplier	Security circle completed (3+ members)

Consumed Events (inbound)

Event	Handler	Description
UserRegisteredIntegrationEvent	UserRegisteredIntegrationEventHandler	Creates new Miner profile when user registers in IAM. If referral code provided, creates Referral relationship.
UserKycCompletedIntegrationEvent	UserKycCompletedIntegrationEventHandler	Activates pending referral for user who completed KYC verification.

Note: Integration events are defined as records implementing IIntegrationEvent. Handlers use MediatR notification wrappers (UserRegisteredNotification, UserKycCompletedNotification). The actual message broker (RabbitMQ) integration for publishing/consuming is not yet wired up -- the event definitions and handlers exist but the transport layer is missing.

Domain Events

Event	Fields	Raised By
MinerCreatedDomainEvent	MinerId, UserId	Miner.Create()
MiningSessionStartedDomainEvent	MinerId, SessionId, HourlyRate	Miner.StartMiningSession()
PointsMinedDomainEvent	MinerId, PointsEarned, TotalPoints, StreakDays	Miner.ClaimMiningReward()
StreakUpdatedDomainEvent	MinerId, PreviousStreak, NewStreak, NewBonusMultiplier	Defined but not raised in current code
CircleCompletedDomainEvent	CircleId, OwnerId, MemberCount	Circle.RecalculateStatus() (when reaching 3 members)
ReferralActivatedDomainEvent	ReferralId, ReferrerId, ReferredId	Referral.Activate()
ConfigurationUpdatedDomainEvent	ConfigType, UpdatedBy, UpdatedAt	Defined but not raised in current code

---

8. Dependencies

NuGet Packages

API Layer (MiningService.API.csproj):

Package	Version
MediatR	12.4.1
FluentValidation	11.11.0
FluentValidation.DependencyInjectionExtensions	11.11.0
Microsoft.AspNetCore.Authentication.JwtBearer	10.0.2
Microsoft.EntityFrameworkCore.Design	10.0.2
Microsoft.Extensions.Http.Polly	10.0.2
Swashbuckle.AspNetCore	7.2.0
Asp.Versioning.Mvc	8.1.0
Asp.Versioning.Mvc.ApiExplorer	8.1.0
AspNetCore.HealthChecks.NpgSql	8.0.2
AspNetCore.HealthChecks.Redis	8.0.1
Hellang.Middleware.ProblemDetails	6.5.1
Serilog.AspNetCore	8.0.3
Serilog.Sinks.Console	6.0.0
Serilog.Sinks.Seq	8.0.0

Infrastructure Layer (MiningService.Infrastructure.csproj):

Package	Version
Microsoft.EntityFrameworkCore	10.0.0
Npgsql.EntityFrameworkCore.PostgreSQL	10.0.0
Microsoft.EntityFrameworkCore.Tools	10.0.0
MediatR	12.4.1
Dapper	2.1.35
Microsoft.Extensions.Http.Polly	9.0.0
Polly	8.5.0
StackExchange.Redis	2.8.16

Domain Layer (MiningService.Domain.csproj):

Package	Version
MediatR.Contracts	2.0.1

External Service Dependencies

Service	Default URL	Client Interface	Purpose
IAM Service	http://iam-service-net:8080	IIamServiceClient	Get user info, validate user, KYC status
Wallet Service	http://wallet-service-net:8080	IWalletServiceClient	Transfer mined points to wallet, check balance
Social Service	http://social-service-net:8080	ISocialServiceClient	Friend suggestions for circles, friendship checks

All external clients use Polly resilience policies:

• Retry: 3 retries with exponential backoff (2s, 4s, 8s)
• Circuit Breaker: Opens after 5 failures, stays open for 30s

---

9. Configuration

Environment Variables / appsettings.json

Key	Default	Description
ConnectionStrings:DefaultConnection	Neon PostgreSQL connection string	Primary database connection
DATABASE_URL	--	Fallback database connection string
Redis:ConnectionString	localhost:6379	Redis connection (declared but not actively used in repositories)
Jwt:Secret	your-super-secret-key-min-32-characters	JWT signing key
Jwt:Issuer	goodgo-platform	JWT issuer
Jwt:Audience	goodgo-services	JWT audience
Jwt:AccessTokenExpiryMinutes	15	Token expiry (declared, not used internally)
Jwt:RefreshTokenExpiryDays	7	Refresh token expiry (declared, not used internally)
ExternalServices:IamService:BaseUrl	http://iam-service-net:8080	IAM service URL
ExternalServices:WalletService:BaseUrl	http://wallet-service-net:8080	Wallet service URL
ExternalServices:SocialService:BaseUrl	http://social-service-net:8080	Social service URL
AllowedOrigins	["http://localhost:3000", "http://localhost:5173"]	CORS allowed origins
ASPNETCORE_ENVIRONMENT	Development	Environment name
ASPNETCORE_URLS	http://+:8080 (Docker)	Listen URLs

MediatR Pipeline Order

1. LoggingBehavior -- logs request name, elapsed time
2. ValidatorBehavior -- runs FluentValidation (no validators currently defined)
3. TransactionBehavior -- wraps Commands in DB transaction (skips Queries by name suffix)

Docker

• Multi-stage build: sdk:10.0 (build) -> aspnet:10.0 (runtime)
• Non-root user: dotnetuser (UID/GID 1001)
• Port: 8080
• Health check: curl -f http://localhost:8080/health/live (30s interval, 3 retries)

Database Startup

• Auto-applies EF Core migrations on startup (dbContext.Database.MigrateAsync())
• Npgsql retry on failure: 5 retries, 30s max delay

Idempotency

• ClientRequest entity and RequestManager are defined but not wired into the command pipeline (no commands use idempotency checks).

Known Gaps / Stubs

• No FluentValidation validators are defined for any command
• ConfigurationRepository is purely in-memory (static fields with lock); database persistence for configs is not implemented
• Analytics queries for Points, Streaks, and AuditLogs have no handlers
• BanMinerCommand handler calls Suspend() instead of Ban()
• ResetMinerStreakCommand handler does not actually reset the streak
• UpdateSystemConfigCommand and UpdateMiningConfigCommand handlers do not persist changes
• RabbitMQ integration for publishing/consuming integration events is not connected
• Redis is declared as a dependency but not used in any repository or service
• Dapper is referenced but no raw SQL queries exist
• Table names use PascalCase instead of the platform-standard snake_case