Update docs

Author: mythz

MyApp/_pages/autoquery/autogen.md

@@ -2,7 +2,11 @@
 title: AutoQuery AutoGen CRUD Services
 ---
 
-Long time users of ServiceStack will know it's a staunch proponent of **code-first development** where your C# Types retains the master authority of your App's logic, although there are a number of times where you have to work with existing databases which would require significant effort to create the initial code-first Data Models. Historically we've pointed people to use [OrmLite's T4 Template Support](/ormlite/autogen-t4#t4-template-support) which provides a decent initial stab, however it's limited in its capability and offers a sub par development experience.
+Long time users of ServiceStack will know it's a staunch proponent of **code-first development** where your C# Types retains the master authority of your App's logic, although there are a number of times where you have to work with existing databases which would require significant effort to create the initial code-first Data Models.
+
+### AutoGen vs TypeScript Data Models
+
+AutoGen's approach relies on runtime C# reflection to inspect your RDBMS schema and dynamically register AutoQuery CRUD Services; if you prefer an alternative flow based on generating source code from exported DB metadata and TypeScript Data Models instead, see [Generate CRUD APIs and UIs for existing DBs](/autoquery/okai-db) which uses the `okai` tool.
 
 <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NaJ7TW-Q_pU" style="background-image: url('https://img.youtube.com/vi/NaJ7TW-Q_pU/maxresdefault.jpg')"></lite-youtube>
 
@@ -87,8 +91,8 @@ Then use the `x` dotnet tool to download all the AutoQuery & Crud Services for a
 `x csharp https://localhost:5001 -path /crud/all/csharp`
 :::
 
-If you're running a mix of autogenerated AutoGen AutoQuery APIs with existing typed AutoQuery APIs, you can just 
-generate the **new** Services with: 
+If you're running a mix of autogenerated AutoGen AutoQuery APIs with existing typed AutoQuery APIs, you can just
+generate the **new** Services with:
 
 :::sh
 x csharp https://localhost:5001 -path /crud/new/csharp
@@ -137,13 +141,13 @@ The generated `dtos.cs` includes AutoGen-specific options that can be used to ma
 ```csharp
 /* Options:
 //...
-//IncludeCrudOperations: 
+//IncludeCrudOperations:
 Schema: custom
-//NamedConnection: 
-//NoCache: 
-//IncludeTables: 
-//ExcludeTables: 
-//AuthSecret: 
+//NamedConnection:
+//NoCache:
+//IncludeTables:
+//ExcludeTables:
+//AuthSecret:
 */
 ```
 
@@ -246,9 +250,9 @@ public class ConfigureDb : IHostingStartup
             var dbFactory = new OrmLiteConnectionFactory(
                 context.Configuration.GetConnectionString("DefaultConnection"),
                 SqliteDialect.Provider);
-                
+
             services.AddSingleton<IDbConnectionFactory>(dbFactory);
-                
+
             services.AddPlugin(new AutoQueryFeature {
                 MaxLimit = 1000,
                 GenerateCrudServices = new GenerateCrudServices {
@@ -261,7 +265,7 @@ public class ConfigureDb : IHostingStartup
 }
 ```
 
-The [sqlite](https://gist.github.com/gistlyn/768d7b330b8c977f43310b954ceea668) gist registers an 
+The [sqlite](https://gist.github.com/gistlyn/768d7b330b8c977f43310b954ceea668) gist registers an
 [OrmLite.Sqlite](https://github.com/ServiceStack/ServiceStack.OrmLite) RDBMS connection with our App which we want to configure to connect to a **northwind.sqlite** database:
 
 ```csharp
@@ -312,7 +316,7 @@ Once running you can view your Apps metadata page at `https://localhost:5001` to
 
 #### Create Dart gRPC Console App
 
-It's also now accessible via [ServiceStack's gRPC endpoint](/grpc/) which opens your generated Services up to [Google's high-performance gRPC ecosystem](https://grpc.io) which enables typed, high-performance integrations into exciting platforms like [Flutter](https://flutter.dev) which uses the [Dart](https://dart.dev) programming language to create Reactive, high-performance native Android and iOS Apps. 
+It's also now accessible via [ServiceStack's gRPC endpoint](/grpc/) which opens your generated Services up to [Google's high-performance gRPC ecosystem](https://grpc.io) which enables typed, high-performance integrations into exciting platforms like [Flutter](https://flutter.dev) which uses the [Dart](https://dart.dev) programming language to create Reactive, high-performance native Android and iOS Apps.
 
 We can test Dart's gRPC integration and development workflow in a new Dart Console App we can create with:
 
@@ -329,7 +333,7 @@ dependencies:
   fixnum: ^0.10.11
   async: ^2.2.0
   protobuf: ^1.0.1
-  grpc: ^2.1.3    
+  grpc: ^2.1.3
 ```
 
 When you save **pubspec.yaml** Dart's VS Code extension will automatically fetch any new dependencies which can also be manually run with:
@@ -418,9 +422,9 @@ void main(List<String> args) async {
 
 Whilst the `AutoRegister = true` flag on its face may seem magical, it's simply an instruction that tells ServiceStack to register the **new** AutoQuery Services it already knows about and register them as if they were normal code-first Services that we had written ourselves.
 
-More accurately, behind-the-scenes it uses the Metadata Type structure it constructed in generating the Services & Types, i.e. the same Types used to project into its Add ServiceStack Reference's generated C#, TypeScript, (and other languages) which are also the same Types that are manipulated when customizing code-generation, gets used to generate .NET Types in memory on Startup with Reflection.Emit. 
+More accurately, behind-the-scenes it uses the Metadata Type structure it constructed in generating the Services & Types, i.e. the same Types used to project into its Add ServiceStack Reference's generated C#, TypeScript, (and other languages) which are also the same Types that are manipulated when customizing code-generation, gets used to generate .NET Types in memory on Startup with Reflection.Emit.
 
-Barring any issues with the projection into IL, externally the end result is indistinguishable to a normal code-first ServiceStack Service manually created by a developer - An important point as to why these solutions compose well with the rest of ServiceStack, just as an AutoQuery Service is a normal ServiceStack Service, these auto generated & auto registered ServiceStack Services are regular Auto Query Services. 
+Barring any issues with the projection into IL, externally the end result is indistinguishable to a normal code-first ServiceStack Service manually created by a developer - An important point as to why these solutions compose well with the rest of ServiceStack, just as an AutoQuery Service is a normal ServiceStack Service, these auto generated & auto registered ServiceStack Services are regular Auto Query Services.
 
 The primary difference is that they only exist in a .NET Assembly in memory created on Startup, not in code so they're not "statically visible" to a C# compiler, IDE, tools, etc. But otherwise they're regular typed ServiceStack Services and can take advantage of the ecosystem around Services including [Add ServiceStack Reference](/add-servicestack-reference) & other Metadata Pages and Services, etc.
 
@@ -462,8 +466,8 @@ Plugins.Add(new AutoQueryFeature {
 });
 ```
 
-These will generated Service Contracts & DTO Types with the Multitenancy [NamedConnection](/autoquery/rdbms#named-connection) & OrmLite `[Schema]` attribute required for routing AutoQuery Services to use the appropriate RDBMS connection of Schema. 
- 
+These will generated Service Contracts & DTO Types with the Multitenancy [NamedConnection](/autoquery/rdbms#named-connection) & OrmLite `[Schema]` attribute required for routing AutoQuery Services to use the appropriate RDBMS connection of Schema.
+
 Although there are potential conflicts if there are identical table names in each RDBMS/Schema as it has to go back and rewrite the Metadata References to use a non-ambiguous name, first tries using the NamedConnection, then the schema then a combination when both exists, if it's still ambiguous it gives up and ignores it. If you do run into conflicts, the recommendation is to "eject" the generated `.cs` sources and manually update them to use your preferred unique names.
 
 ### Customize Code Generation to include App Conventions
@@ -484,7 +488,7 @@ For an illustration of this in action, here's a typical scenario of how the Nort
 
  - Controlling which Tables **not to generate Services for** in `ignoreTables`
  - Which tables not to generate **Write Crud Services** for in `readOnlyTables`
- - Which tables to **restrict access** to in different roles in `protectTableByRole` 
+ - Which tables to **restrict access** to in different roles in `protectTableByRole`
  - Example of **additional validation** to existing tables in `tableRequiredFields`
    - Adds the `[ValidateNotEmpty]` attribute to Services accessing the table and the `[Required]` OrmLite attribute for the Data Model DTO Type.
 
@@ -506,12 +510,12 @@ Plugins.Add(new AutoQueryFeature {
     GenerateCrudServices = new GenerateCrudServices
     {
         DbFactory = dbFactory,
-        ServiceFilter = (op,req) => 
+        ServiceFilter = (op,req) =>
         {
             // Require all Write Access to Tables to be limited to Authenticated Users
             if (op.IsCrudWrite())
             {
-                op.Request.AddAttributeIfNotExists(new ValidateRequestAttribute("IsAuthenticated"), 
+                op.Request.AddAttributeIfNotExists(new ValidateRequestAttribute("IsAuthenticated"),
                     x => x.Validator == "IsAuthenticated");
             }
 
@@ -532,7 +536,7 @@ Plugins.Add(new AutoQueryFeature {
                 props.Each(x => x.AddAttribute(new ValidateNotEmptyAttribute()));
             }
         },
-        TypeFilter = (type, req) => 
+        TypeFilter = (type, req) =>
         {
             // Add OrmLite [Required] Attribute on Tables with Required Fields
             if (tableRequiredFields.TryGetValue(type.Name, out var requiredFields))
@@ -552,7 +556,7 @@ Plugins.Add(new AutoQueryFeature {
 Plugins.Add(new ValidationFeature()); // Enable Validation
 ```
 
-Additionally, the `TableSchemasFilter` can be used to modify the schema used by AutoGen to generate the types associated with your AutoQuery APIs. 
+Additionally, the `TableSchemasFilter` can be used to modify the schema used by AutoGen to generate the types associated with your AutoQuery APIs.
 This gives you the opportunity to filter or modify the schema after they are pulled from the database.
 For example, we could `Remove` tables based on naming, or alter column definitions to assist with any schema issues.
 
@@ -612,7 +616,7 @@ cd NorthwindCrud
 dotnet run
 ```
 
-This example App is also configured with other new features in incoming release including Crud Events in 
+This example App is also configured with other new features in incoming release including Crud Events in
 [Startup.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Startup.cs):
 
 ```csharp
@@ -621,26 +625,26 @@ container.AddSingleton<ICrudEvents>(c => new OrmLiteCrudEvents(c.Resolve<IDbConn
 container.Resolve<ICrudEvents>().InitSchema();
 ```
 
-As well as support for dynamically generated db rules in 
+As well as support for dynamically generated db rules in
 [Configure.Validation.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Configure.Validation.cs):
 
 ```csharp
-services.AddSingleton<IValidationSource>(c => 
+services.AddSingleton<IValidationSource>(c =>
     new OrmLiteValidationSource(c.Resolve<IDbConnectionFactory>()));
 
 appHost.Resolve<IValidationSource>().InitSchema();
 ```
 
-To be able to test the custom code generation the example is pre-populated with 3 users with different roles in 
+To be able to test the custom code generation the example is pre-populated with 3 users with different roles in
 [Configure.Auth.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Configure.Auth.cs):
 
 ```csharp
 // Register Users that don't exist
 void EnsureUser(string email, string name, string[] roles=null)
 {
-    if (authRepo.GetUserAuthByUserName(email) != null) 
+    if (authRepo.GetUserAuthByUserName(email) != null)
         return;
-    
+
     authRepo.CreateUserAuth(new UserAuth {
         Email = email,
         DisplayName = name,
@@ -657,7 +661,7 @@ Of which you can also find published on [NorthwindCrud's home page](https://gith
 
 ### AutoGen Customizations
 
-AutoGen's [Instantly Servicify existing Systems](/servicify) feature works by automatically generating the AutoQuery & Crud APIs and Data Models for all tables in the configured RDBMS's. Further customization of the DataModel Names, the user-defined Route Path they're hosted at & the name of individual AutoQuery APIs for each operation using the `GenerateOperationsFilter`. 
+AutoGen's [Instantly Servicify existing Systems](/servicify) feature works by automatically generating the AutoQuery & Crud APIs and Data Models for all tables in the configured RDBMS's. Further customization of the DataModel Names, the user-defined Route Path they're hosted at & the name of individual AutoQuery APIs for each operation using the `GenerateOperationsFilter`.
 
 So if you had an existing table name called `applications` the default convention based names would be:
  - Data Model: `Applications`
@@ -716,16 +720,16 @@ As NorthwindCrud is [configured to use JWT](https://github.com/NetCoreApps/North
 ```dart
 GrpcServicesClient createClient({CallOptions options}) {
   return GrpcServicesClient(ClientChannel('localhost', port:5054,
-    options:ChannelOptions(credentials: ChannelCredentials.insecure())), 
+    options:ChannelOptions(credentials: ChannelCredentials.insecure())),
     options:options);
 }
 
 void main(List<String> arguments) async {
     var authResponse = await createClient().postAuthenticate(
         Authenticate()..provider='credentials'..userName='[email protected]'..password='p@ss');
 
-    var authClient = createClient(options:CallOptions(metadata:{ 
-            'Authorization': 'Bearer ${authResponse.bearerToken}' 
+    var authClient = createClient(options:CallOptions(metadata:{
+            'Authorization': 'Bearer ${authResponse.bearerToken}'
         }));
 
     var response = await authClient.getQueryCategory(QueryCategory());

MyApp/_pages/autoquery/okai-db.md

@@ -2,17 +2,28 @@
 title: Generate CRUD APIs and UIs for existing DBs
 ---
 
-A core piece of functionality in the [Text to Blazor CRUD App](/autoquery/text-to-blazor) feature is distilling an AI Prompt into TypeScript classes that can be [further customized](/autoquery/okai-models#customize-data-models)
-to generate AutoQuery CRUD APIs and Admin UIs for managing the underlying RDBMS tables.
+### AutoGen vs TypeScript Data Models
 
-## TypeScript Data Models
+AutoGen's approach relies on runtime C# reflection to inspect your RDBMS schema and dynamically register AutoQuery CRUD Services; this page instead documents an alternative flow based on generating source code from exported DB metadata and TypeScript Data Models using the `okai` tool. If you prefer the reflection-based approach, see [AutoQuery AutoGen CRUD Services](/autoquery/autogen).
 
-Using TypeScript is an effortless way to define data models, offering a DSL-like minimal boilerplate format that's human-friendly to read and write which can leverage TypeScript's powerful Type System is validated against the referenced [api.d.ts](https://okai.servicestack.com/api.d.ts) schema to provide a rich authoring experience 
-with strong typing and intellisense - containing all the C# Types, interfaces, and attributes used in defining APIs, DTOs and Data Models.
+## Generate CRUD APIs from TypeScript Data Models
+
+A core feature of the [okai](/autoquery/okai-models) tool is the ability to convert [customized TypeScript Data Models](/autoquery/okai-models#customize-data-models) into C# AutoQuery CRUD APIs, RDBMS DataModel tables and DB Migrations.
+
+This enables a flexible way to generate AutoQuery CRUD APIs for existing RDBMS tables, by:
+
+1. Exporting the existing RDBMS metadata to json
+2. Use `okai` to convert the json metadata into TypeScript Data Models
+3. Perform any customizations to the TypeScript Data Model as needed
+4. Use `okai` to generate the AutoQuery CRUD APIs, RDBMS DataModel tables and DB Migrations
+
+### Why TypeScript?
+
+Using TypeScript is an effortless way to define data models, offering a DSL-like minimal boilerplate format that's human-friendly to read and write which can leverage TypeScript's powerful Type System is validated against the referenced [api.d.ts](https://okai.servicestack.com/api.d.ts) schema to provide a rich authoring experience with strong typing and intellisense - containing all the C# Types, interfaces, and attributes used in defining APIs, DTOs and Data Models.
 
 ### Blueprint for Code Generation
 
-The TypeScript Data Models serve as the blueprint for generating everything needed to support the feature 
+The TypeScript Data Models serve as the blueprint for generating everything needed to support the feature
 in your App, including the AutoQuery **CRUD APIs**, **Admin UIs** and **DB Migrations** that can re-create the necessary tables from scratch.
 
 ## 1. Generate RDBMS Metadata
@@ -34,7 +45,7 @@ This task can then be run from the command line with:
 dotnet run --AppTasks=App.json
 :::
 
-Which generates `App_Data/App.json` containing the table definition metadata for all tables in 
+Which generates `App_Data/App.json` containing the table definition metadata for all tables in
 the specified RDBMS, e.g:
 
 ```json
@@ -74,7 +85,7 @@ the specified RDBMS, e.g:
 
 ### Different Connection or DB Schema
 
-If you prefer to generate the metadata for a different connection or schema, you can create a new AppTask 
+If you prefer to generate the metadata for a different connection or schema, you can create a new AppTask
 with your preferred `namedConnection` and/or `schema`, e.g:
 
 ```csharp
@@ -92,11 +103,11 @@ dotnet run --AppTasks=Sales.json
 ## 2. Generate TypeScript Data Models
 
 The next step is to generate TypeScript Data Models from the captured metadata which can be done with the `okai` tool
-by running the `convert` command with the path to the `App.json` JSON table definitions which will generate the 
+by running the `convert` command with the path to the `App.json` JSON table definitions which will generate the
 TypeScript Data Models to stdout which can be redirected to a file in your **ServiceModel** project, e.g:
 
 :::sh
-npx okai convert App_Data/App.json > ../MyApp.ServiceModel/App.d.ts  
+npx okai convert App_Data/App.json > ../MyApp.ServiceModel/App.d.ts
 :::
 
 ## 3. Generate CRUD APIs and Admin UIs