continuousimprovement/CLAUDE.md

Strata Continuous Improvement — Claude Code Guide

About

Healthcare finance analytics microservice owned by The-Outliers team. Helps hospitals identify cost-saving opportunities across encounter, charge code, general ledger, payroll, utilization variation, quality variation, network, and strategic opportunity domains.

Tech stack: .NET 8 (C# 12) + React 17 + TypeScript 4.9 + PostgreSQL + SQL Server + Snowflake

Shell / repo navigation

• Claude is launched from the repo root (C:/git/microservices/continuousimprovement). Do not cd to the repo in commands.
• Avoid compound commands that combine cd with pipes/redirection (e.g., cd ... && ... 2>/dev/null | head ...) because they trigger manual-approval warnings.
• Prefer:
  • find . ... (when already in repo root), or
  • find "C:/git/microservices/continuousimprovement" ... (when an explicit path is needed).
• If output limiting is needed, prefer | head -50 without 2>/dev/null, or run redirection in a separate step.

Commands

# Backend
dotnet restore
dotnet build
dotnet test

# Frontend (run from src/Strata.ContinuousImprovement.Web/continuousimprovement/)
npm install
npm start          # Dev server
npm test           # Interactive test runner
npm run test-ci    # CI test runner (no watch)

Coding Standards

Follow .github/copilot-instructions.md for naming, capitalization, project organization, API routes, DTOs, and principles. Key points:

• Booleans: is, has, can prefix
• Methods/properties/constants: PascalCase; variables: camelCase
• No full acronyms (EntityIdsCsv not EntityIdsCSV)
• Organize by business domain, not by type
• RESTful routes: plural nouns, kebab-case
• DTOs: no DTO suffix, only create when restricting/combining models

Architecture

Backend (C#/.NET 8)

Project	Purpose	Path
Api	ASP.NET Core Web API host, controllers	src/Strata.ContinuousImprovement.Api/
Biz	All business logic, services, DI registration	src/Strata.ContinuousImprovement.Biz/
Client	HTTP client wrapper (IContinuousImprovementService)	src/Strata.ContinuousImprovement.Client/
Service	Windows/hosted service, Hangfire worker host	src/Strata.ContinuousImprovement.Service/
Dashboard	Separate web host (Startup + Program)	src/Strata.ContinuousImprovement.Dashboard/
DecisionSupport.Biz	Encounter query services, Snowflake queries	src/Strata.DecisionSupport.Biz/
DecisionSupport.Models	Shared encounter/Jazz/Snowflake DTOs	src/Strata.DecisionSupport.Models/

Frontend (React 17 + TypeScript)

Root: src/Strata.ContinuousImprovement.Web/continuousimprovement/

Feature modules live directly under src/ (not a features/ folder):

• charge-code/, encounter/, exploration/, free-form/, general-ledger/, initiatives/, network/, opportunities/, payroll/, quality-variation/, strategic-opportunities/, utilization-variation/, configuration/

Each module follows: page component + /components + /hooks + /data + /utils

Shared module: src/shared/ — components, hooks, data services, contexts, constants

Key Constraints

• React 17 — do NOT use React 18 features (useId, automatic batching, etc.)
• react-router v5 — use Switch/Route/Redirect, NOT v6 patterns
• Create React App (react-scripts ^5.0.1) — not Vite

Strata Ecosystem (Proprietary — No Public Docs)

These packages are internal to Strata. No public documentation exists. Read source/types when needed:

Package	Purpose
@strata/tempo	Design system (v6.33+). Import: @strata/tempo/lib/<component>. Query Tempo MCP server for docs.
@strata/core	Auth (useOidcSession), HTTP (getSecureService), URL helpers
@strata/charts	Charting library
@strata/jazz	Jazz platform integration
@strata/logging	Client-side logging
@strata/navbar	Shared navigation bar
@strata/score	Score calculations
@strata/signalr	SignalR client wrapper
@strata/settings	Settings service
@strata/intl	Internationalization
Strata.CS.Jazz.*	Backend Jazz platform libraries (DI, EF, auth, caching)
Riok.Mapperly	Compile-time object mapping source generator
EasyCaching	In-memory caching (provider: continuousImprovement_cache)

Commit Requirements

Format: type(scope): subject — enforced by .commitlintrc.js

Types: build, feat, fix, docs, style, refactor, test, chore Scopes: api, biz, client, dashboard, service, web, ds-web, ds-models

Rules:

• Subject max 72 chars, no period, no sentence/start/pascal/upper case
• Scope required (warning), lowercase only
• Body and footer must have leading blank line
• Footer: Refs: JAZZ-XXXX (Jira ticket reference)

Example:

feat(biz): add case type family drill-down for exploration

Refs: JAZZ-12345

Testing

Backend (NUnit + Moq)

• Unit tests: tests/Strata.ContinuousImprovement.*.Test.Unit/
• Integration tests: tests/Strata.ContinuousImprovement.*.Test.Integration/
• Jazz EF stub: tests/Strata.ContinuousImprovement.JazzEntityFrameworkStub/
• Pattern: [TestFixture], [Test], [SetUp]/[OneTimeSetUp], Mock<IService>
• Run: dotnet test

Frontend (Jest + Testing Library)

• Test files: <Component>.test.tsx co-located with components
• Custom render wrapper: src/test-utils/testUtils.tsx (wraps MemoryRouter + contexts)
• Pattern: render(), screen.findByRole(), jest.spyOn(service, 'method')
• Run: npm test (from continuousimprovement/ dir) or npm run test-ci for CI

E2E (Playwright)

• Located in separate test infrastructure

Feature Flags

Backend pattern:

// Inject IFeatureFlagWrapper, call named convenience method or generic:
await featureFlagWrapper.IsCiBenchmarkingEnabled();
await featureFlagWrapper.IsFeatureFlagOn(FeatureFlag.ChargeCodeBeta, clientId);

Frontend pattern:

const { isBenchmarkingEnabled } = useFeatureFlags();

Centralized definitions: Biz/Utilities/FeatureFlag.cs (enum) + FeatureFlagLookup.cs (key mapping)

See docs/FeatureFlagUsage.md for full flag inventory.

Key Patterns

• Interface-based DI — All services have IXxxService interface, registered in Biz/Configurations/ContinuousImprovementServiceExtensions.cs via services.AddScoped<IXxxService, XxxService>()
• Primary constructor DI (C# 12) — Services use public class XxxService(IDep1 dep1, IDep2 dep2) : IXxxService
• Riok.Mapperly — Compile-time mapping via [Mapper] attribute on static partial classes (in DecisionSupport.Biz/Mapperly/)
• Embedded SQL resources — .sql files as embedded resources, loaded via Assembly.GetExecutingAssembly().ReadResource("QueryName.sql") (see Biz/Utilities/ResourceExtensions.cs)
• EasyCaching — In-memory provider named continuousImprovement_cache
• SignalR — Typed hub NotificationHub : Hub<INotificationHub>, mapped at /api/NotificationHub
• Multi-database — PostgreSQL (CentralDbContext), SQL Server (JazzDbContext via async factory), Snowflake (SnowflakeDatabaseContext)
• API versioning — [ApiVersion("1.0")] + [Route("api/v{api-version:apiVersion}/[controller]")] + SlugifyParameterTransformer
• Frontend data services — getSecureService() from @strata/core/lib providing typed HTTP helpers, exported as plain objects implementing interfaces
• Frontend state — React Context pattern (FeatureFlagContext, ConfigurationsContext, UserSettingsContext) + custom hooks

MCP Servers

• Tempo — Query @strata/tempo component docs, props, examples. Always check before using Tempo components.
• Jira/Atlassian — Fetch ticket details, search issues, manage PRs via mcp__atlassian__* tools.

Reference Docs

• .claude/docs/backend-patterns.md — Biz module anatomy, DI, controllers, EF, SQL, testing
• .claude/docs/frontend-patterns.md — Feature modules, hooks, data services, Tempo, testing
• .claude/docs/agent-workflow.md — AI-assisted development pipeline and context management
• .claude/docs/adversarial-prompts.md — Review criteria templates