1  # GUNRPG.Infrastructure
  2  
  3  Infrastructure layer for GUNRPG, providing concrete implementations of persistence and external service abstractions.
  4  
  5  ## Overview
  6  
  7  This project contains implementation details for storage and external integrations that are abstracted in the Application layer. It follows Clean Architecture principles by keeping infrastructure concerns separate from domain and application logic.
  8  
  9  ## Components
 10  
 11  ### Persistence
 12  
 13  #### LiteDbCombatSessionStore
 14  
 15  Embedded document database implementation of `ICombatSessionStore` using LiteDB.
 16  
 17  **Features:**
 18  - Persist combat session snapshots to disk
 19  - Support for save, load, update, delete, and list operations
 20  - Thread-safe for concurrent requests
 21  - Automatic enum serialization to strings for readability
 22  - No annotations required on domain objects
 23  - Schema migration support via LiteDB.Migration
 24  
 25  #### LiteDbMigrations
 26  
 27  Manages database schema migrations using the [LiteDB.Migration](https://github.com/JKamsker/LiteDB.Migration) library.
 28  
 29  **Features:**
 30  - Automatic migration application on startup
 31  - Schema version tracking
 32  - Forward-only migrations
 33  - Supports complex data transformations
 34  
 35  **Current Schema Version:** 1 (initial baseline)
 36  
 37  **Adding Migrations:**
 38  
 39  When the snapshot schema evolves, add migrations in `LiteDbMigrations.ApplyMigrations`:
 40  
 41  ```csharp
 42  var migrations = new MigrationContainer(config =>
 43  {
 44      config.Collection<CombatSessionSnapshotV2>("combat_sessions", collectionConfig =>
 45      {
 46          collectionConfig
 47              .StartWithModel<CombatSessionSnapshotV1>()
 48              .WithMigration(v1 => new CombatSessionSnapshotV2
 49              {
 50                  Id = v1.Id,
 51                  // ... map existing properties
 52                  NewProperty = "default-value" // Add new property
 53              })
 54              .UseLatestVersion();
 55      });
 56  });
 57  migrations.Apply(database);
 58  ```
 59  
 60  Update `CurrentSchemaVersion` constant after adding migrations.
 61  
 62  **Configuration:**
 63  
 64  ```json
 65  {
 66    "Storage": {
 67      "Provider": "LiteDB"
 68    }
 69  }
 70  ```
 71  
 72  If `LiteDbConnectionString` is omitted, the default `~/.gunrpg/combat_sessions.db` under the current user's home directory is used. You can set it explicitly to override the location.
 73  
 74  **Usage:**
 75  
 76  The store is automatically registered via the `AddCombatSessionStore` extension method:
 77  
 78  ```csharp
 79  builder.Services.AddCombatSessionStore(builder.Configuration);
 80  ```
 81  
 82  To switch to in-memory storage for testing:
 83  
 84  ```json
 85  {
 86    "Storage": {
 87      "Provider": "InMemory"
 88    }
 89  }
 90  ```
 91  
 92  ## Design Principles
 93  
 94  1. **Separation of Concerns**: LiteDB types never leak into Core or Application layers
 95  2. **Configuration-Driven**: Store selection via appsettings.json
 96  3. **Dependency Injection**: Singleton lifetime for database connection
 97  4. **Clean Architecture**: Infrastructure depends on Application, never the reverse
 98  5. **Thread Safety**: All operations are safe for concurrent use
 99  
100  ## Dependencies
101  
102  - `LiteDB` (5.0.21): Embedded NoSQL document database
103  - `LiteDB.Migration` (0.0.10): Schema migration framework for LiteDB
104  - `Microsoft.Extensions.Configuration.Abstractions`: Configuration support
105  - `Microsoft.Extensions.DependencyInjection.Abstractions`: DI support
106  - `Microsoft.Extensions.Options.ConfigurationExtensions`: Options pattern support
107  
108  ## Testing
109  
110  Tests are located in `GUNRPG.Tests/LiteDbCombatSessionStoreTests.cs` and verify:
111  - Basic CRUD operations
112  - Nested object serialization
113  - Enum handling
114  - Concurrent access
115  - Update semantics
116  
117  ## Future Enhancements
118  
119  Potential future additions to this project:
120  - Database migration utilities
121  - Backup and restore tools
122  - Session replay functionality
123  - Export/import capabilities
124  - Alternative storage providers (SQL, cloud storage)