|
1 | | -- NEVER THROW EXCEPTIONS!!!!!! Always return a result type for methods that could fail. Anything that can fail is wrapped in a try/catch |
2 | | -- You are building a code generation. Don't generate code yourself that is the responsibility of the generator |
3 | | -- AVOID DUPLICATION. Always check for the existence of types, methods and variables before creating them |
4 | | -- No interfaces! Use Action<T> or Func<T> for abstractions |
5 | | -- AVOID ASSIGNMENTS!!!! Use EXPRESSIONS where possible |
6 | | -- NO CONSECUTIVE Console.WriteLine calls. Use string interpolation on a sinle line |
7 | | -- DO NOT USE GIT - Unless explicitly requested |
8 | | -- Static extension methods on IDbConnection and ITransaction only! No classes for getting data |
9 | | -- No singletons! Inject Func into static methods |
10 | | -- NO CLASSES. Records and Static Methods!!! - FP style code wherever with pure static methods |
11 | | -- Turn all warnings up to ERRORS and include as many Roslyn analyzer rules as possible, especially for null safety |
12 | | -- Keep files under 450 LOC |
13 | | -- Run dotnet csharpier . on the root folder of the repo every now and then |
14 | | -- No placeholders! If you don't have time to implement something properly, leave a LOUD compilation error with a TODO instead |
15 | | -- All public members MUST have XMLDOC documentation, except on tests |
16 | | -- DON'T use Regex! Parse the SQL with the official Antlr .g4 or a well tested existing parsing library |
17 | | -- Use a build props for everything and remove duplicate config from the csproj, especially Roslyn/code rule config. |
18 | | -- Keep the readme updated |
19 | | -- Don't put temp files or anything in the root folder |
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +# Rules |
| 6 | + |
| 7 | +## Multi-Agent Coordination (Too Many Cooks) |
| 8 | +- Keep your key! It's critical. Do not lose it! |
| 9 | +- Check messages regularly, lock files before editing, unlock after |
| 10 | +- Don't edit locked files; signal intent via plans and messages |
| 11 | +- Coordinator: keep delegating via messages. Worker: keep asking for tasks via messages |
| 12 | +- Telegraph EVERYTHING with messages and plan updates |
| 13 | +- Clean up expired locks routinely |
| 14 | + |
| 15 | +## Coding Rules |
| 16 | + |
| 17 | +- **NEVER THROW EXCEPTIONS** - Always return `Result<T>` for fallible operations. Wrap anything that can fail in try/catch |
| 18 | +- **No casting or using ! for nulls** - Only pattern matching on type |
| 19 | +- **DO NOT USE GIT** <-- ⛔️ Source control is illegal for you 🙅🏼 |
| 20 | +- **Do not supress analyzer warnings/errors** <-- Illegal |
| 21 | +- **No direct CREATE TABLE or other SQL to create schema** - Use the DataProvider Migrations! |
| 22 | +- **No direct SQL inserts/Updates!** - Generate extensions for inserts/updates with DataProvider |
| 23 | +- **NO CLASSES** - Use records and static methods. FP style with pure static methods |
| 24 | +- **Copious logging with ILogger** - Especially in the sync projects |
| 25 | +- **NO INTERFACES** - Use `Action<T>` or `Func<T>` for abstractions |
| 26 | +- **AVOID ASSIGNMENTS** - Use expressions where possible |
| 27 | +- **You MUST close type hierarchies** - Make the constructor restricted so it is not possible to create new implementations from the base type. Eg: |
| 28 | +```csharp |
| 29 | +public abstract partial record Result<TSuccess, TFailure> |
| 30 | +{ |
| 31 | + // [...] |
| 32 | + /// </summary> |
| 33 | + private Result() { } |
| 34 | + // [...] |
| 35 | +} |
| 36 | +`` |
| 37 | +- **Static extension methods on IDbConnection and IDbTransaction only** - No classes for data access |
| 38 | +- **Don't use statements like if** - use pattern matching switch expressions on type |
| 39 | +⛔️ wrong |
| 40 | +```csharp |
| 41 | +if (triggerResult is Result<bool, SyncError>.Error<bool, SyncError> triggerErr) |
| 42 | +``` |
| 43 | +- **Skipping tests = ⛔️ ILLEGAL** - Failing tests = OK. Aggressively unskip tests |
| 44 | +- **Test at the highest level** - Avoid mocks. Only full integration testing |
| 45 | +- **Always use type aliases (using) for result types** - Don't write like this: `new Result<string, SqlError>.Ok` |
| 46 | +- **No singletons** - Inject `Func` into static methods |
| 47 | +- **Immutable types!** - Use records. Don't use `List<T>`. Use `ImmutableList` `FrozenSet` or `ImmutableArray` |
| 48 | +- **NO REGEX** - Parse SQL with ANTLR .g4 grammars or SqlParserCS library |
| 49 | +- **All public members require XMLDOC** - Except in test projects |
| 50 | +- **Keep files under 450 LOC** |
| 51 | +- **One type per file** (except small records) |
| 52 | +- **No commented-out code** - Delete it |
| 53 | +- **No consecutive Console.WriteLine** - Use single string interpolation |
| 54 | +- **No placeholders** - If incomplete, leave LOUD compilation error with TODO |
| 55 | +- **Never use Fluent Assertions** |
| 56 | + |
| 57 | +## Testing |
| 58 | +- Use e2e tests with zero mocking where possible |
| 59 | +- Fall back on unit testing only when absolutely necessary |
| 60 | +- Create MEANINGFUL tests that test REAL WORLD use cases |
| 61 | +- All projects must have 100% test coverage and a Stryker Mutator testing score of 70% or above. Use [Stryker Mutator](https://stryker-mutator.io/docs/stryker-net/getting-started/) as the ultimate arbiter of test quality |
| 62 | + |
| 63 | +## Architecture Overview |
| 64 | + |
| 65 | +This repository contains four major components: |
| 66 | + |
| 67 | +**DataProvider** - Source generator creating compile-time safe extension methods from SQL files |
| 68 | +- Core library in `DataProvider/DataProvider/` - base types, config records, code generation |
| 69 | +- Database-specific implementations: `DataProvider.SQLite/`, `DataProvider.SqlServer/` |
| 70 | +- Uses ANTLR grammars for SQL parsing (`Parsing/*.g4` files) |
| 71 | +- Generates extension methods on `IDbConnection` and `IDbTransaction` |
| 72 | +- Routinely format all C# code with `dotnet csharpier .` |
| 73 | + |
| 74 | +**LQL (Lambda Query Language)** - Functional DSL that transpiles to SQL |
| 75 | +- Core transpiler in `Lql/Lql/` - ANTLR grammar, pipeline steps, AST |
| 76 | +- Database dialects: `Lql.SQLite/`, `Lql.SqlServer/`, `Lql.Postgres/` |
| 77 | +- CLI tool: `LqlCli.SQLite/` |
| 78 | +- Browser playground: `Lql.Browser/` |
| 79 | + |
| 80 | +**Sync Framework** - Offline-first bidirectional synchronization |
| 81 | +- Core engine in `Sync/Sync/` - SyncCoordinator, ConflictResolver, BatchManager |
| 82 | +- Database implementations: `Sync.SQLite/`, `Sync.Postgres/` |
| 83 | +- HTTP layer: `Sync.Http/` - REST endpoints with SSE subscriptions |
| 84 | +- Key components: TriggerGenerator, ChangeApplier, MappingEngine |
| 85 | +- Comprehensive tests: `Sync.Tests/`, `Sync.SQLite.Tests/`, `Sync.Postgres.Tests/` |
| 86 | + |
| 87 | +**Gatekeeper** - Authentication and authorization microservice |
| 88 | +- API in `Gatekeeper/Gatekeeper.Api/` - WebAuthn passkey auth, RBAC, record-level permissions |
| 89 | +- Schema in `Gatekeeper/Gatekeeper.Migration/` - Uses DataProvider migrations |
| 90 | +- Key files: `TokenService.cs`, `AuthorizationService.cs`, `Program.cs` |
| 91 | +- Tests: `Gatekeeper/Gatekeeper.Api.Tests/` |
| 92 | + |
| 93 | +**Shared Libraries** in `Other/`: |
| 94 | +- `Results/` - `Result<TValue, TError>` type for functional error handling |
| 95 | +- `Selecta/` - SQL parsing and AST utilities |
| 96 | + |
| 97 | +**Samples** - Healthcare microservices demonstrating the suite |
| 98 | +- `Samples/Clinical/` - FHIR-compliant clinical API (Patient, Encounter, Condition) |
| 99 | +- `Samples/Scheduling/` - FHIR-compliant scheduling API (Practitioner, Appointment) |
| 100 | +- `Samples/Dashboard/` - React/H5 dashboard |
| 101 | +- Medical: All medical data MUST conform to the [FHIR spec](https://build.fhir.org/resourcelist.html). |
| 102 | + |
| 103 | +## Project Configuration |
| 104 | + |
| 105 | +- .NET 9.0, C# latest with nullable enabled |
| 106 | +- All warnings as errors (TreatWarningsAsErrors=true) |
| 107 | +- Central config in `Directory.Build.props` - don't duplicate in .csproj files |
| 108 | +- xUnit for testing with Moq |
| 109 | + |
| 110 | +## Code Generation Note |
| 111 | + |
| 112 | +This is a code generation project. Don't generate code manually that is the responsibility of the generator. Check for existing types/methods before creating new ones. |
0 commit comments