wip

Author: ryukzak

examples/README.md

@@ -6,44 +6,66 @@ This directory contains working examples demonstrating the capabilities of Atomi
 
 ### TypeScript Generation
 
-- **[typescript-r4/](typescript-r4/)** - FHIR R4 core type generation
-  - `generate.ts` - Generates TypeScript interfaces for FHIR R4 specification
-  - `demo.ts` - Demonstrates resource creation, profile usage (bodyweight), and bundle composition
-  - Shows how to use `attach` and `extract` functions for FHIR profiles
+- **[typescript-r4/](typescript-r4/)** - FHIR R4 core type generation ✅ Code included
+  - Full FHIR R4 resource type definitions with profiles and bundles
+  - Demonstrates `attach` and `extract` functions for FHIR profiles
+  - Includes demo showing resource creation and bundle composition
 
-- **[typescript-ccda/](typescript-ccda/)** - C-CDA on FHIR type generation
-  - `generate.ts` - Generates types from HL7 CDA UV Core package (`hl7.cda.uv.core@2.0.1-sd`)
-  - Exports TypeSchema files and dependency tree
+- **[typescript-ccda/](typescript-ccda/)** - C-CDA on FHIR type generation ✅ Code included
+  - HL7 CDA UV Core package (`hl7.cda.uv.core@2.0.1-sd`)
+  - Document structure and clinical content models
 
-- **[typescript-sql-on-fhir/](typescript-sql-on-fhir/)** - SQL on FHIR ViewDefinition types
-  - `generate.ts` - Generates types from remote TGZ package
-  - Demonstrates tree shaking to include only specific resources
+- **[typescript-sql-on-fhir/](typescript-sql-on-fhir/)** - SQL on FHIR ViewDefinition types ✅ Code included
+  - Remote TGZ package loading from build.fhir.org
+  - Demonstrates tree shaking to include only ViewDefinition
+  - Shows SQL-on-FHIR view definition patterns
 
-### Multi-Language Generation
+- **[local-package-folder/](local-package-folder/)** - Custom FHIR packages from local files ✅ Code included
+  - Load unpublished StructureDefinitions from disk
+  - Combine local and published packages
+  - Dependency resolution with FHIR R4 core
+  - Tree shaking for custom logical models
 
-- **[python/](python/)** - Python/Pydantic model generation
-  - `generate.ts` - Generates Python models with configurable field formats
-  - Supports `snake_case` or `camelCase` field naming
-  - Configurable extra field validation
+### Python Generation
 
-- **[csharp/](csharp/)** - C# class generation
-  - `generate.ts` - Generates C# classes with custom namespace
-  - Includes static files for base functionality
-  - Includes integration tests with Aidbox FHIR server
+- **[python/](python/)** - Python/Pydantic model generation ✅ Code included
+  - Full FHIR R4 as Pydantic models
+  - Configurable field formats (`snake_case` or `camelCase`)
+  - Automatic validation and serialization with Pydantic
+  - Virtual environment setup instructions
 
-### Local Package Support
+### C# Generation
 
-- **[local-package-folder/](local-package-folder/)** - Working with unpublished FHIR packages
-  - `generate.ts` - Loads local StructureDefinitions from disk
-  - Demonstrates dependency resolution with FHIR R4 core
-  - Shows tree shaking for custom logical models
+- **[csharp/](csharp/)** - C# class generation ✅ Code included
+  - Full FHIR R4 as C# classes
+  - Custom namespace support
+  - Integration tests with Aidbox FHIR server
 
-## Running Examples
+## Prerequisites
 
-Each example contains a `generate.ts` script that can be run with:
+- **Bun 1.0+** or Node.js 18+
+- **RAM**: 1GB+ minimum, 2GB+ recommended for full R4 package generation
+- **Python 3.10+** (for Python example only)
+- **.NET 6.0+** (for C# example only)
+- **Docker & Docker Compose** (optional, for C# Aidbox integration tests)
+
+## Quick Start
+
+### Setup
+
+From the project root:
+
+```bash
+cd codegen
+bun install
+```
+
+### Generate Types
+
+Run any example with:
 
 ```bash
-# Using Bun
+# Using Bun (recommended)
 bun run examples/typescript-r4/generate.ts
 
 # Using Node with tsx
@@ -53,23 +75,52 @@ npx tsx examples/typescript-r4/generate.ts
 npx ts-node examples/typescript-r4/generate.ts
 ```
 
-To run the TypeScript R4 demo after generation:
+Replace `typescript-r4` with any example name:
+- `typescript-ccda`
+- `typescript-sql-on-fhir`
+- `local-package-folder`
+- `python`
+- `csharp`
 
-```bash
-bun run examples/typescript-r4/demo.ts
+## Generated Output Structure
+
+Each example generates output following this pattern:
+
+```
+example/
+├── README.md                    # Example-specific guide
+├── generate.ts                  # Generation script
+├── generated/                   # Output (created after generation)
+│   ├── index.ts/py/cs          # Main exports
+│   ├── resources/               # FHIR resources
+│   ├── types/                   # Complex types
+│   └── enums/                   # Value set enums
+└── [language-specific files]    # requirements.txt, .csproj, etc.
 ```
 
-## Prerequisites for C# Example
+## Integration Examples
 
-The C# example includes integration tests with Aidbox FHIR server. To run the tests:
+Add to your build pipeline
 
 ```bash
-# Start Aidbox server
-docker compose up
+#!/bin/bash
+# scripts/generate-fhir-types.sh
+cd codegen
+bun run examples/typescript-r4/generate.ts
+```
 
-# In another terminal, run the C# tests
-cd examples/csharp
-dotnet test
+```json
+{
+  "scripts": {
+    "generate:types": "bash scripts/generate-fhir-types.sh",
+    "prebuild": "npm run generate:types"
+  }
+}
 ```
 
-See [examples/csharp/README.md](csharp/README.md) for detailed setup instructions.
+## Support
+
+For issues or questions:
+- Check main [README.md](../README.md)
+- Review [CONTRIBUTING.md](../CONTRIBUTING.md)
+- Open an issue on GitHub

examples/csharp/README.md

@@ -4,26 +4,16 @@ Type-safe C# class generation with Aidbox FHIR server integration and comprehens
 
 ## Overview
 
-This example demonstrates how to generate C# classes from the FHIR R4 specification using the Atomic EHR Codegen toolkit. It includes:
+This example demonstrates how to generate C# classes from the FHIR R4 specification. It includes:
 
 - Full FHIR R4 resource type definitions as C# classes
 - Namespace organization for clean code structure
 - Integration tests with Aidbox FHIR server
-- Synchronous client for server communication
 - Type-safe resource operations (Create, Read, Update, Delete)
 
 ## Setup
 
-### Prerequisites
-
-- .NET 6.0+
-- Docker and Docker Compose (for Aidbox integration tests)
-- Bun 1.0+ or Node.js 18+ (for generation)
-- 2GB+ available RAM (for full R4 package generation)
-
-### Installation
-
-#### 1. Generate C# Types
+### Generate C# Types
 
 From the project root:
 
@@ -33,66 +23,64 @@ bun install
 bun run examples/csharp/generate.ts
 ```
 
-This will:
-1. Download the `hl7.fhir.r4.core@4.0.1` package
-2. Transform it to TypeSchema format
-3. Generate C# classes with namespace `FhirTypes`
-4. Output to `./examples/csharp/generated/`
+This will output to `./examples/csharp/generated/`
 
-#### 2. Install .NET Dependencies
+### Install .NET Dependencies
 
 ```bash
 cd examples/csharp
 dotnet restore
 ```
 
-#### 3. Start Aidbox Server (for testing)
+### Start Aidbox Server (for testing)
 
 ```bash
-# From examples/csharp directory
 curl -JO https://aidbox.app/runme && docker compose up
 ```
 
-This will:
-- Start Aidbox FHIR server on `http://localhost:8080`
-- Open license setup at `http://localhost:8888` (first run only)
-- Wait until "Aidbox is ready!" message appears
+This will start Aidbox FHIR server on `http://localhost:8080`
 
-#### 4. Get Aidbox Credentials
+## Configuration
 
-After Aidbox starts:
+Edit `generate.ts` to customize:
 
-```bash
-# Find the root client secret in docker-compose.yaml
-grep "BOX_ROOT_CLIENT_SECRET" docker-compose.yaml
+```typescript
+.csharp({
+    rootNamespace: "FhirTypes",
+})
 ```
 
-Update `TestSdk.cs` with the credential:
+### Tree Shaking
 
-```csharp
-private const string Password = "your-secret-here";
+To generate only specific resources:
+
+```typescript
+.treeShake({
+  "hl7.fhir.r4.core#4.0.1": {
+    "http://hl7.org/fhir/StructureDefinition/Patient": {},
+    "http://hl7.org/fhir/StructureDefinition/Observation": {},
+  }
+})
 ```
 
-## Testing Code using Aidbox
+## Testing with Aidbox
 
 ### Configuration
 
-1. **Get your Aidbox credentials** from `docker-compose.yaml`:
+1. Get your Aidbox credentials from `docker-compose.yaml`:
    - Look for `BOX_ROOT_CLIENT_SECRET` value
    - Update the password in `TestSdk.cs`:
 
 ```csharp
 private const string Password = "your-secret-here";
 ```
 
-2. **Ensure Aidbox is running**:
+2. Ensure Aidbox is running:
 
 ```bash
 docker compose up
 ```
 
-   - FHIR server should be accessible at `http://localhost:8080`
-
 ### Running Tests
 
 Run all tests:
@@ -103,7 +91,7 @@ dotnet test
 
 ### Available Tests
 
-The test suite includes comprehensive CRUD operations:
+The test suite includes CRUD operations:
 
 - **TestCreatePatient** - Creates a new patient resource
 - **TestReadPatient** - Retrieves an existing patient by ID
@@ -112,52 +100,11 @@ The test suite includes comprehensive CRUD operations:
 - **TestSearchPatient** - Searches for patients by name
 - **TestJsonSerialization** - Validates JSON serialization/deserialization
 - **TestResourceMapping** - Verifies resource type mapping
-- **TestEnumFields** - Tests enum field definitions across resources
-
-## Usage
+- **TestEnumFields** - Tests enum field definitions
 
-### SDK Generation Configuration
+## Using Generated Types
 
-The `generate.ts` script configures code generation using APIBuilder:
-
-```typescript
-const builder = new APIBuilder()
-    .fromPackage("hl7.fhir.r4.core", "4.0.1")
-    .csharp({
-        rootNamespace: "FhirTypes",
-    })
-    .outputTo("./examples/csharp/generated")
-    .cleanOutput(true);
-
-const report = await builder.generate();
-```
-
-### Customization Options
-
-Modify `generate.ts` to customize generation:
-
-```typescript
-.csharp({
-    rootNamespace: "YourNamespace",    // Root namespace for generated classes
-})
-```
-
-### Advanced: Tree Shaking
-
-To generate only specific resources (reduces output size):
-
-```typescript
-.treeShake({
-  "hl7.fhir.r4.core#4.0.1": {
-    "http://hl7.org/fhir/StructureDefinition/Patient": {},
-    "http://hl7.org/fhir/StructureDefinition/Observation": {},
-  }
-})
-```
-
-### Working with FHIR Resources
-
-The SDK provides strongly-typed classes for all FHIR resources. Here's an example of creating a Patient:
+### Create Resources
 
 ```csharp
 using FhirTypes;
@@ -194,21 +141,6 @@ var json = JsonSerializer.Serialize(patient, options);
 var deserialized = JsonSerializer.Deserialize<Patient>(json, options);
 ```
 
-## File Structure
-
-```
-csharp/
-├── README.md                    # This file
-├── generate.ts                  # Type generation script
-├── csharp.csproj               # C# project file
-├── TestSdk.cs                  # Integration tests with Aidbox
-├── docker-compose.yaml         # Aidbox configuration
-├── generated/                  # Generated types (created after generation)
-│   ├── FhirTypes/             # Generated C# classes
-│   └── ...                     # Other generated files
-└── obj/                        # Build artifacts
-```
-
 ## Development
 
 ### Build the Project
@@ -217,21 +149,13 @@ csharp/
 dotnet build
 ```
 
-### Run Tests
-
-```bash
-dotnet test
-```
-
 ### Run Tests with Output
 
 ```bash
 dotnet test --verbosity normal
 ```
 
-## Support
+## Next Steps
 
-For issues or questions:
-- Check [README.md](../../README.md) for general information
-- Review [CONTRIBUTING.md](../../CONTRIBUTING.md) for development setup
-- Open an issue on [GitHub](https://github.com/atomic-ehr/codegen/issues)
+- See [examples/](../) overview for other language examples
+- Check [../../CLAUDE.md](../../CLAUDE.md) for architecture details