maraphon-app/CLAUDE.md

CLAUDE.md — maraphon-app

Project memory for Claude Code sessions on this repository. Keep entries concise. Per-feature learnings are appended below by the feature-planner workflow.

Project Overview

maraphon-app is a sports betting odds analyzer for marathonbet.by. It scrapes pre-match (/su) and live (/su/live) events, persists odds snapshots over time, and detects anomalies — especially the odds-flip pattern (bookmaker freezes bets then inverts underdog/favorite coefficients).

Architecture (Clean Architecture, 5 projects + tests)

Marathon.Domain          ← entities, value objects, no external deps
   ↑
Marathon.Application     ← use cases + abstractions (IOddsScraper, IRepository, ...)
   ↑
Marathon.Infrastructure  ← EF Core (SQLite), scraping (AngleSharp/Playwright), Excel, Polly
Marathon.UI              ← Razor Class Library (all Blazor components — host-agnostic)
   ↑
Marathon.Hosts.WpfBlazor ← WPF + BlazorWebView host (replaceable for ASP.NET Core later)

Key portability invariant: All UI lives in Marathon.UI (Razor Class Library). The host project (Marathon.Hosts.WpfBlazor) is the only thing that changes when migrating to a web app — drop in an ASP.NET Core Blazor Server host that references the same RCL.

Tech stack

• .NET 8 LTS, C# 12
• EF Core 8 + SQLite (WAL mode)
• AngleSharp (HTML), Playwright for .NET (SPA fallback)
• Polly v8 (Microsoft.Extensions.Http.Resilience)
• MudBlazor components, Plotly.Blazor charts
• Serilog logging (rolling file + console)
• xUnit + FluentAssertions + NSubstitute, in-memory SQLite for repo tests

Build & test

Command	Purpose
dotnet build Marathon.sln	Build all projects
dotnet test Marathon.sln	Run all tests
dotnet format Marathon.sln --verify-no-changes	Lint
dotnet run --project src/Marathon.Hosts.WpfBlazor	Run desktop app

Coding conventions

• Nullable reference types: enabled (<Nullable>enable</Nullable>)
• Implicit usings: enabled
• Treat warnings as errors in Release builds
• File-scoped namespaces
• One public type per file (except small DTOs/records grouped in a feature folder)
• Domain entities: prefer record for immutable data; class with private setters when identity matters
• No mutation of domain objects after construction — return new instances
• Repositories return IReadOnlyList<T>, not List<T> or IEnumerable<T> (clarity on enumeration cost)
• Tests follow Given_When_Then or Should_<expected>_When_<condition> naming

Configuration

Every variable parameter is configurable via appsettings.json and overridable via appsettings.Local.json (gitignored) or environment variables:

• Scraping:PollingIntervalSeconds (default 30)
• Scraping:MaxConcurrentRequests (default 4)
• Scraping:UserAgents[] (rotated per request)
• Scraping:RetryPolicy:* (Polly settings)
• Scraping:RateLimit:RequestsPerSecond (default 1)
• Storage:DatabasePath (default ./data/marathon.db)
• Storage:ExportDirectory (default ./exports)
• Storage:SnapshotRetentionDays (default 90)
• Anomaly:SuspensionGapSeconds (default 60)
• Anomaly:OddsFlipThreshold (default 0.30 — implied probability delta)
• Localization:DefaultCulture (default ru-RU)

A future Settings page in the UI binds to these.

Domain model summary

• Sport(Code, Name) — e.g., (6, "Баскетбол")
• Event(Id, SportCode, CountryCode, LeagueId, CategoryId, ScheduledAt, EventCodeFromBookmaker)
• OddsSnapshot(EventId, CapturedAt, Source: Pre|Live, Bets: List<Bet>)
• Bet(Scope: Match|Period[N], Type: Win|Draw|WinFora|Total, Side: 1|2|Less|More, Value?, Rate)
• EventResult(EventId, FinalScore, WinnerSide)
• Anomaly(EventId, DetectedAt, Kind: SuspensionFlip, Score, EvidenceTimeline)

Excel export schema (compliance with customer spec)

Customer TZ requires wide-table layout with columns like Bet_Match_Win_1, Bet_Period-1_Win_Fora_2_Value, etc.

Internal storage is normalized (one row per Bet in OddsSnapshots). The Excel exporter denormalizes to the wide format on demand. Filename pattern:

Marathon_<YYYY-MM-DD>_to_<YYYY-MM-DD>.xlsx

Recurring Issues & Patterns

• dotnet new sln on .NET 10 SDK produces .slnx, not .sln. If the plan references Marathon.sln, hand-craft the traditional format alongside .slnx.
• Marathon.Application namespace vs System.Windows.Application: in any WPF project that references Marathon.Application, always write System.Windows.Application fully qualified in App.xaml.cs.
• Directory.Build.props must NOT set TargetFramework when projects in the same solution use different TFMs (e.g., net8.0 vs net8.0-windows).
• Razor source generator does NOT accept C# 11 raw string literals ("""…""") inside @code blocks — concatenate single-quoted attribute strings instead.
• Razor reserves the identifier code. Loop variables must use any other name (var sportCode in ...) or the parser treats it as the @code directive.
• MudBlazor.DateRange shadows Marathon.Application.Storage.DateRange in any Razor file that pulls both namespaces via _Imports.razor. Use a per-file alias: using AppDateRange = Marathon.Application.Storage.DateRange;.
• Plotly.Blazor.LayoutLib.Margin clashes with MudBlazor.Margin. Fully qualify the Plotly side at the new-expression: new Plotly.Blazor.LayoutLib.Margin {…}.
• Event.ScheduledAt requires offset +03:00. Test fixtures and any code that constructs Moscow datetimes must use new DateTimeOffset(date, TimeSpan.FromHours(3)), never pass a DateTime.UtcNow value to that constructor.
• EF migrations — generate with dotnet ef, do NOT migrations remove. MarathonDbContextFactory is a self-contained design-time factory, so dotnet ef migrations add X --project src/Marathon.Infrastructure --startup-project src/Marathon.Infrastructure works. AVOID dotnet ef migrations remove: older migrations were hand-written without a Designer snapshot, so remove blanks MarathonDbContextModelSnapshot.cs and the next add regenerates the WHOLE schema. Validate a migration on a throwaway DB with dotnet ef database update --connection "Data Source=<ABSOLUTE>/data/_migtest.db" (absolute path — EF resolves relatives from the build-output dir, not the shell cwd; create ./data/ first).
• Sports.Code is .ValueGeneratedNever() — it's the bookmaker's natural sport id (6/11/22723…), not an autoincrement surrogate. Without it EF's int-PK convention emits a spurious AUTOINCREMENT AlterColumn on every migration.
• Validated get-only record properties block with (CS0200): BacktestStrategy.MinScore, PaperBet.Rate/Stake are re-declared with validation, so build a new instance instead of with { ThatProp = … } (you can still with the un-redeclared props, e.g. SavedStrategy with { Strategy = … }).
• JsonSettingsWriter.SaveSectionAsync replaces the whole section (root[section]=json), so a Settings-UI save drops any key not on the form. Never surface a secret-bearing section (e.g. Notifications → Telegram token) in the UI — it would wipe the secret from appsettings.Local.json. To surface a non-secret section, add a mutable mirror options class in Marathon.UI.Services bound to the same section name (UI can't reference Infrastructure's options types — same pattern as the two WorkerOptions).

Feature: Initial Implementation > Phase 4: Application + Workers — Learnings

• Two WorkerOptions classes coexist with the same JSON shape but different namespaces: Marathon.Infrastructure.Configuration.WorkerOptions (immutable init, used by workers) and Marathon.UI.Services.WorkerOptions (mutable set, used by Settings page). Both bind to "Workers" in appsettings.json. Keep them in sync when adding new keys.
• Microsoft.Extensions.Logging.EventId conflicts with Marathon.Domain.ValueObjects.EventId in any project that adds Microsoft.Extensions.Logging.Abstractions. Fix with a global alias in GlobalUsings.cs: global using LogEventId = Microsoft.Extensions.Logging.EventId; and local file aliases where both are used together.
• NSubstitute cannot proxy sealed classes. Use cases are sealed record or sealed class. Worker tests must build a real use-case instance backed by substituted interfaces rather than substituting the use case directly.
• BackgroundService workers are singletons; use cases are scoped. Always resolve scoped use cases via IServiceProvider.CreateAsyncScope() inside the worker loop — never inject them directly into the constructor.
• Cronos 6-field cron format. Pass CronFormat.IncludeSeconds to CronExpression.Parse when the expression has a seconds field (e.g., "0 0 */6 * * *"). Default Cronos parse expects 5-field (no seconds).
• ApplicationModule.AddMarathonApplication takes no IConfiguration — the Application layer has no config bindings of its own. Infrastructure and UI bind their own options sections.

Feature: Initial Implementation > Phase 0: Scraping Spike — Learnings

(Permanent learnings about marathonbet.by data shape, anti-bot, page structure. For full detail see spike/SCRAPE_FINDINGS.md and spike/SCHEMA_DRAFT.md.)

• Site is fully SSR (Server: nginx). Anonymous GET with browser User-Agent returns full HTML for /su/, /su/live, /su/popular/<Sport>, /su/betting/<event-path>. No Cloudflare, no JS challenge.
• Use HttpClient + AngleSharp + Polly v8 — no Playwright needed for read-only. Keep Scraping:UsePlaywright = false flag for future-proofing.
• Sport ID = data-sport-treeId = breadcrumb canonical ID. Confirmed: Basketball=6, Football=11, Tennis=22723, Hockey=43658. URL by ID: /su/betting/<Sport>+-+<id> (preferred over /su/popular/<Sport> because the ID is stable).
• EventCode = data-event-eventId (numeric, ~26-million range, stable). TreeId = data-event-treeId (URL-routing ID, less stable). Use EventCode as the entity primary key in SQLite.
• Selection key format: {eventId}@{MarketName}{LineIndex?}.{Outcome}. Outcomes: 1/draw/3 for 3-way, HB_H/HB_A for handicap, Under_<X>/ Over_<X> for totals. Total threshold is encoded in the outcome string; handicap value lives in <span class="middle-simple"> text.
• Tennis has no Draw outcome. Domain Bet_Match_Draw must be nullable; Excel exporter writes empty cell when null.
• Date parsing: listing shows HH:MM (today) or DD <ru-month> HH:MM (future). Anchor with initData.serverTime (Moscow TZ, format YYYY,MM,DD,HH,MM,SS) parsed from the embedded <script> blob on every scraped page.
• Live updates: site polls /su/liveupdate/popular/?treeIds=... every 3 s but response is just {"modified":[{"type":"refreshPage"}],...} — re-scrape the full event detail HTML for actual odds. Our analyzer cadence: pre-match 30 s, live 5–10 s.
• No public results / archive page (/su/results → 404). Final scores must be harvested by polling the event detail page until eventJsonInfo.matchIsComplete=true, then storing resultDescription. Phase 8 cannot back-fill from a public archive.
• Period scope vocabulary varies by sport: football=1st_Half, basketball= 1st_Half/1st_Quarter, tennis=1st_Set, hockey=1st_Period. Domain stores PeriodNumber:int and a sport-aware PeriodScopeMapper resolves the correct market token at parse time.

Feature: Initial Implementation > Phase 7: Anomaly UI — Learnings

• Severity buckets are a single-source rule in Marathon.UI.Services.AnomalySeverityRules.FromScore (Low <0.45, Medium <0.60, High ≥0.60). The badge pill, card border, feed filter chip, and stat strip all bind through it — never duplicate the thresholds.
• AnomalyBrowsingService is Scoped, AnomalyBrowsingState is Singleton — same lifetime split as EventBrowsingService / EventBrowsingState. State holds the immutable AnomalyFilter + LastSeenUtc + cached unread count.
• Anomaly.EvidenceJson is parsed once in the service layer via JsonSerializer.Deserialize<EvidenceDto>(json, PropertyNameCaseInsensitive=true) with private nested DTOs. Pages bind to AnomalyEvidenceSnapshot value-records — they never see the raw JSON. Malformed JSON is dropped silently from the feed.
• 2-way markets (tennis) carry pDraw=null / rateDraw=null. The AnomalyEvidence and AnomalyCard components key off the IsTwoWay flag on AnomalyListItem (computed when both pre/post pDraw are null) to omit the Draw row in BOTH columns — never per-column-individually.
• Signal-red is the load-bearing alert tone for Phase 7. Use var(--m-c-anomaly) exclusively (never raw #dc2626). Pulsing animation (m-pulse) MUST respect prefers-reduced-motion.

Feature: Analysis Hardening (H-series) — Learnings

• Anomaly detectors are a fan-out array in DetectAnomaliesUseCase — 4 now (SuspensionFlip, SteamMove, SuspensionFreeze, OverroundCompression). A new detector implements IAnomalyDetector, reuses MatchWinEvidence for the canonical evidence JSON (so the parser + outcome evaluator work unchanged), and is added to that array. Continuous sliding-window detectors (steam, overround) emit at every end and skip suspension-sized gaps so they never overlap the across-suspension flip/freeze detectors.
• AnomalyKind.IsDirectional() gates staking/grading — flip + steam are directional (predict a side); freeze + overround are informational and are excluded from the backtest (RunBacktestUseCase) and the outcome evaluator so they don't skew hit-rate/score calibration.
• SavedStrategy (backtest presets) use NOCASE name collation — the unique index AND GetByNameAsync both fold case (column-level UseCollation("NOCASE")), so save-by-name upserts rather than creating "Kelly"/"kelly" duplicates. Domain stores stake fractions; the form/VM speak percent — convert ×100/÷100 at the UI boundary.
• Paper-trading (forward-test) is a config-gated worker (PaperTrading:Enabled, default false; tunable on the Settings page). PaperTradingWorker opens flat-stake PaperBets on new directional anomalies (unique on AnomalyId; baseline since-marker advances only after a successful open pass; settle runs in its own catch so a settle failure can't strand the marker) and settles them against results (Won iff pick == winner). /paper-trading shows settled-only P&L. The ledger is FK-free (survives snapshot-retention pruning), like PlacedBets.