Update core architecture docs (#164120)

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: amyjtechwriter <61687663+amyjtechwriter@users.noreply.github.com>

docs/developer/architecture/core/application_service.asciidoc

@@ -29,7 +29,7 @@ export class MyPlugin implements Plugin {
   }
 }
 ----
-<1> See {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.applicationsetup.register.md[application.register interface]
+<1> Refer to {kib-repo}/blob/8.9/packages/core/application/core-application-browser/src/contracts.ts[application.register interface]
 <2> Application specific URL.
 <3> `mount` callback is invoked when a user navigates to the application-specific URL.
 <4> `core.getStartServices` method provides API available during `start` lifecycle.

docs/developer/architecture/core/configuration-service.asciidoc

@@ -17,7 +17,7 @@ const basePath = core.http.basePath.get(request);
 To have access to your plugin config, you _should_:
 
 * Declare plugin-specific `configPath` (will fallback to plugin `id`
-if not specified) in {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md[`kibana.json`] manifest file.
+if not specified) in your plugin definition.
 * Export schema validation for the config from plugin's main file. Schema is
 mandatory. If a plugin reads from the config without schema declaration,
 `ConfigService` will throw an error.

docs/developer/architecture/core/http-service.asciidoc

@@ -12,7 +12,7 @@ The service allows plugins to:
 * to execute custom logic on an incoming request or server response.
 * implement custom authentication and authorization strategy.
 
-See {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.httpservicesetup.md[HTTP service API docs]
+Refer to {kib-repo}/blob/8.9/packages/core/http/core-http-server/src/http_contract.ts[HTTP service contract types].
 
 [source,typescript]
 ----
@@ -64,4 +64,4 @@ async function fetchData<ResponseType>(core: CoreStart) {
   ); 
 }
 ----
-See {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.httpsetup.md[for all available API].
+Refer to {kib-repo}/blob/8.9/packages/core/http/core-http-browser/src/types.ts[the client-side APIs].

docs/developer/architecture/core/index.asciidoc

@@ -27,6 +27,8 @@ export class MyPlugin {
 }
 ----
 
+
+
 The services that core provides are:
 
 * <<application-service, Application service>>
@@ -36,3 +38,5 @@ The services that core provides are:
 * <<logging-service, Logging service>>
 * <<saved-objects-service, Saved Objects service>>
 * <<ui-settings-service, UI settings service>>
+
+NOTE: Core provides the {kib} building blocks for plugins and is implemented as a collection of <<core-packages, packages>>.

docs/developer/architecture/core/packages.asciidoc

@@ -0,0 +1,26 @@
+[[core-packages]]
+== Core packages
+
+experimental[]
+
+Core packages have well defined boundaries, have a single responsibility, and are organized by domain. Core packages follow a specific naming schema, according to what they contain:
+
+For example, core capapability packages are:
+
+* `core-capabilities-browser-internal`
+* `core-capabilities-browser-mocks`
+* `core-capabilities-common`
+* `core-capabilities-server`
+* `core-capabilities-server-internal`
+* `core-capabilities-server-mocks`
+
+Each domain has a specific package for public types, which can be imported and used throughout the Kibana codebase including in its implementation and unit tests. These packages are internal to core and not intended for public use, but they can be used by plugins to create mock versions for unit testing.
+
+In addition, domains contain separate packages for the client-side and server-side and, in some cases, a base, that 
+supports both client and server needs. When a domain shares code between the server and client, that code lives in
+a `common` package. Mocks have their own dedicated package.
+
+All of core's public API's have inline `jsdocs` that include examples as nescessary.
+
+
+

docs/developer/architecture/core/patterns-scoped-services.asciidoc

@@ -7,9 +7,7 @@ should perform a check whether an end-user has access to the data.
 The Kibana Platform introduced a handler interface on the server-side to perform that association
 internally. Core services, that require impersonation with an incoming
 request, are exposed via `context` argument of
-{kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.requesthandler.md[the
-request handler interface.]
-as
+{kib-repo}/blob/8.9/packages/core/http/core-http-server/src/router/request_handler.ts[the request handler interface].
 
 [source,js]
 ----
@@ -18,13 +16,11 @@ async function handler(context, req, res) {
 }
 ----
 
-The
-{kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.requesthandlercontext.md[request
-handler context] exposes the following scoped *core* services:
+The {kib-repo}/blob/8.9/packages/core/http/core-http-server/src/router/request_handler.ts[request handler context] exposes the following scoped *core* services:
 
-* {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.savedobjectsclient.md[`context.savedObjects.client`]
-* {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.iscopedclusterclient.md[`context.elasticsearch.client`]
-* {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.iuisettingsclient.md[`context.uiSettings.client`]
+* {kib-repo}/blob/8.9/packages/core/saved-objects/core-saved-objects-api-server/src/saved_objects_client.ts[`context.savedObjects.client`]
+* {kib-repo}/blob/8.9/packages/core/elasticsearch/core-elasticsearch-server/src/client/scoped_cluster_client.ts[`context.elasticsearch.client`]
+* {kib-repo}/blob/8.9/packages/core/ui-settings/core-ui-settings-server/src/ui_settings_client.ts[`context.uiSettings.client`]
 
 ==== Declare a custom scoped service
 

docs/developer/architecture/core/uisettings-service.asciidoc

@@ -38,9 +38,10 @@ uiSettings:
 
 [[client-side-usage]]
 === Client side usage
-On the client, the `uiSettings` service is exposed directly from `core` and the {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[client] provides plugins access to the `config` entries stored in {es}.
+On the client, the `uiSettings` service is exposed directly from `core` and the {kib-repo}/blob/8.9/packages/core/ui-settings/core-ui-settings-server/src/ui_settings_client.ts[client]
+provides plugins access to the `config` entries stored in {es}.
 
-In the interest of performance, `uiSettings` are cached. Any changes that require cache refreshes should register an instruction to reload the page when settings are configured in Advanced Settings using the `requiresPageReload` {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.uisettingsparams.md[parameter].
+In the interest of performance, `uiSettings` are cached. Any changes that require cache refreshes should register an instruction to reload the page when settings are configured in Advanced Settings using the `requiresPageReload` {kib-repo}/blob/8.9/packages/core/ui-settings/core-ui-settings-common/src/ui_settings.ts[parameter].
 
 [source,typescript]
 ----
@@ -77,7 +78,7 @@ export class MyPlugin implements Plugin<MyPluginSetup, MyPluginStart> {
 === Server side usage
 On the server, `uiSettings` are exposed directly from `core`.
 
-The following example shows how to {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[register] a new `custom` setting with a default value of '42'. When registering a new setting, you must provide a schema against which validations are performed on read and write. All the other {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[parameters] are optional.
+The following example shows how to register a new `custom` setting with a default value of '42'. When registering a new setting, you must provide a schema against which validations are performed on read and write. All the other {kib-repo}/blob/8.9/packages/core/ui-settings/core-ui-settings-common/src/ui_settings.ts[parameters] are optional.
 
 [source,typescript]
 ----
@@ -114,7 +115,7 @@ export class MyPlugin implements Plugin {
 Migrations for 3rd party plugin advanced settings are not currently supported. If a 3rd party plugin registers an advanced setting, the setting is essentially permanent and cannot be fixed without manual intervention.
 ==============================================
 
-To change or remove a `uiSetting`, the whole `config` Saved Object needs to be migrated. `uiSettings` {kib-repo}blob/{branch}/src/core/server/ui_settings/saved_objects/migrations.ts[migrations] are declared directly in the service.
+To change or remove a `uiSetting`, the whole `config` Saved Object needs to be migrated.
 
 For example, if we wanted to remove a `custom` setting, or rename `my_setting:fourtyTwo` to `my_other_setting:fourtyTwo`, we'd need two migration entries, one for each change targeting the version in which these changes apply:
 

docs/developer/architecture/index.asciidoc

@@ -48,6 +48,8 @@ include::core/uisettings-service.asciidoc[leveloffset=+1]
 
 include::core/patterns-scoped-services.asciidoc[leveloffset=+1]
 
+include::core/packages.asciidoc[leveloffset=+1]
+
 include::security/index.asciidoc[leveloffset=+1]
 
 include::add-data-tutorials.asciidoc[leveloffset=+1]