# 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

```bash
# 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:
```csharp
// Inject IFeatureFlagWrapper, call named convenience method or generic:
await featureFlagWrapper.IsCiBenchmarkingEnabled();
await featureFlagWrapper.IsFeatureFlagOn(FeatureFlag.ChargeCodeBeta, clientId);
```

Frontend pattern:
```tsx
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