docs(Common): Update architecture documentation to reflect final naming and structure

Updated `Deep Dive.md` and `README.md` to align with the finalized architecture and naming conventions established in recent refactors. Key changes include:

- Renamed core traits (`FsReader` → `FileSystemReader`, `AppRuntime` → `ApplicationRunTime`) to improve clarity
- Updated module references (`effect/` → `Effect/`, `dto/` → `DTO/`) to match actual source structure
- Revised `ActionEffect` type parameters (`RuntimeAccess`→`TCapability`) to emphasize capability-focused design
- Simplified effect constructor examples by removing generic runtime constraints
- Corrected directory paths throughout to reflect current project layout
- Enhanced explanations of dependency injection and service provider patterns

These updates ensure documentation accurately reflects the abstract core architecture defined in `Common`, which serves as the foundation for `Mountain`'s implementation and `Cocoon`'s gRPC contracts. The changes support all implemented workflows by providing clear guidance for extending capabilities through the established `ActionEffect` and DI systems.

Author: NikolaRHristov

README.md

@@ -31,10 +31,10 @@ implementing the traits and consuming the effects defined in this crate.
     definition of an operation and its execution.
 2.  **Provide a Declarative Effect System:** Introduces the `ActionEffect` type,
     which describes an asynchronous operation as a value, allowing logic to be
-    composed, tested, and executed in a controlled `AppRuntime`.
+    composed, tested, and executed in a controlled `ApplicationRunTime`.
 3.  **Standardize Data Contracts:** Defines all Data Transfer Objects (DTOs) and
     a universal `CommonError` enum, ensuring consistent data structures and
-    error handling across the entire native ecosystem, including the gRPC API.
+    error handling across the entire native ecosystem.
 4.  **Maximize Testability and Reusability:** Because this crate is pure and
     abstract, any component that depends on it can be tested with mock
     implementations of its traits, leading to fast and reliable unit tests.
@@ -50,8 +50,8 @@ implementing the traits and consuming the effects defined in this crate.
   the `Environment` and `Requires` traits, allowing components to declare their
   dependencies without being tied to a specific implementation.
 - **Asynchronous Service Traits:** All core application services (e.g.,
-  `FsReader`, `UiProvider`, `CommandExecutor`) are defined as `async trait`s,
-  providing a fully asynchronous-first architecture.
+  `FileSystemReader`, `UserInterfaceProvider`, `CommandExecutor`) are defined as
+  `async trait`s, providing a fully asynchronous-first architecture.
 - **Comprehensive DTO Library:** Contains definitions for all data structures
   used for IPC communication with `Cocoon` and internal state management in
   `Mountain`. All types are `serde`-compatible.
@@ -66,9 +66,9 @@ implementing the traits and consuming the effects defined in this crate.
 | Principle          | Description                                                                                                                                    | Key Components Involved                    |
 | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- |
 | **Abstraction**    | Define every application capability as an abstract `async trait`. Never include concrete implementation logic.                                 | All `*Provider.rs` and `*Manager.rs` files |
-| **Declarativism**  | Represent every operation as an `ActionEffect` value. The crate provides constructor functions for these effects.                              | `effect/*`, all `*Effect.rs` files         |
-| **Composability**  | The `ActionEffect` system and trait-based DI are designed to be composed, allowing complex workflows to be built from simple, reusable pieces. | `environment/*`, `effect/*`                |
-| **Contract-First** | Define all data structures (`dto/*`) and error types (`error/*`) first. These form the stable contract for all other components.               | `dto/`, `error/`                           |
+| **Declarativism**  | Represent every operation as an `ActionEffect` value. The crate provides constructor functions for these effects.                              | `Effect/*`, all effect constructor files   |
+| **Composability**  | The `ActionEffect` system and trait-based DI are designed to be composed, allowing complex workflows to be built from simple, reusable pieces. | `Environment/*`, `Effect/*`                |
+| **Contract-First** | Define all data structures (`DTO/*`) and error types (`Error/*`) first. These form the stable contract for all other components.               | `DTO/`, `Error/`                           |
 | **Purity**         | This crate has minimal dependencies and is completely independent of Tauri, gRPC, or any specific application logic.                           | `Cargo.toml`                               |
 
 ---
@@ -82,21 +82,24 @@ _returns a description of that effect_.
 **Traditional (Imperative) Approach:**
 
 ```rust
-async fn read_my_file(fs: &impl Fs) -> Result<Vec<u8>, Error> {
+async fn read_my_file(fs: &impl FileSystem) -> Result<Vec<u8>, Error> {
     fs.read("/path/to/file").await // The side effect happens here.
 }
 ```
 
 **The `Common` (Declarative) Approach:**
 
 ```rust
-use Common::fs;
+use Common::FileSystem;
+use std::sync::Arc;
 
 // 1. Create a description of the desired effect. No I/O happens here.
-let read_effect = fs::ReadFile(PathBuf::from("/path/to/file"));
+//    The effect's type signature explicitly declares its dependency: `Arc<dyn FileSystemReader>`.
+let read_effect: ActionEffect<Arc<dyn FileSystemReader>, _, _> = FileSystem::ReadFile(PathBuf::from("/path/to/file"));
 
 // 2. Later, in a separate part of the system (the runtime), execute it.
-//    The runtime provides the concrete implementation of the `FsReader` trait.
+//    The runtime will see that the effect needs a FileSystemReader, provide one from its
+//    environment, and run the operation.
 let file_content = runtime.Run(read_effect).await?;
 ```
 
@@ -112,15 +115,17 @@ its trait definitions, DTOs, and effect constructors.
 ```
 Common/
 └── Source/
-    ├── lib.rs                      # Crate root, declares all modules.
-    ├── environment/                # The core DI system (Environment, Requires traits).
-    ├── effect/                     # The ActionEffect system (ActionEffect, AppRuntime traits).
-    ├── error/                      # The universal CommonError enum.
-    └── command/                    # Example service domain:
-        ├── mod.rs                  # Module aggregator.
-        ├── CommandExecutor.rs      # The abstract `trait` definition.
-        └── ExecuteCommand.rs       # The `ActionEffect` constructor function.
-    └── (Other service domains like fs/, ui/, terminal/, etc. follow the same pattern)
+    ├── Library.rs                      # Crate root, declares all modules.
+    ├── Environment/                    # The core DI system (Environment, Requires traits).
+    ├── Effect/                         # The ActionEffect system (ActionEffect, ApplicationRunTime traits).
+    ├── Error/                          # The universal CommonError enum.
+    ├── DTO/                            # Shared Data Transfer Objects.
+    └── Command/                        # Example service domain:
+        ├── mod.rs                      # Module aggregator.
+        ├── CommandExecutor.rs          # The abstract `trait` definition.
+        ├── DTO/                        # (if any service-specific DTOs are needed)
+        └── ExecuteCommand.rs           # The `ActionEffect` constructor function.
+    └── (Other service domains like FileSystem/, UserInterface/, etc. follow the same pattern)
 ```
 
 ---
@@ -149,9 +154,9 @@ graph LR
 
     subgraph "The `Common` Crate"
         direction LR
-        Traits["Abstract Traits (e.g., `FsReader`)"]:::common
+        Traits["Abstract Traits (e.g., `FileSystemReader`)"]:::common
         Effects["ActionEffects (e.g., `ReadFile`)"]:::common
-        DTOs["Data Transfer Objects (e.g., `FileTypeDto`)"]:::common
+        DTOs["Data Transfer Objects (e.g., `FileTypeDTO`)"]:::common
 
         Effects -- Depend on --> Traits
     end
@@ -188,34 +193,33 @@ Common = { path = "../Common" }
 A developer working within the `Mountain` codebase would use `Common` as
 follows:
 
-1.  **Implement a Trait:** In `Mountain/Source/environment/`, provide the
+1.  **Implement a Trait:** In `Mountain/Source/Environment/`, provide the
     concrete implementation for a `Common` trait.
 
     ```rust
-    // In Mountain/Source/environment/FsProvider.rs
-    use Common::fs::{FsReader, FsWriter};
+    // In Mountain/Source/Environment/FileSystemProvider.rs
+    use Common::FileSystem::{FileSystemReader, FileSystemWriter};
 
     #[async_trait]
-    impl FsReader for MountainEnvironment {
+    impl FileSystemReader for MountainEnvironment {
         async fn ReadFile(&self, Path: &PathBuf) -> Result<Vec<u8>, CommonError> {
-            // Delegate to the handler which contains the actual `tokio::fs` call.
-            handlers::fs::ReadFileLogic(&self.AppHandle, Path).await
+            // ... actual `tokio::fs` call ...
         }
         // ...
     }
     ```
 
-2.  **Create and Execute an Effect:** In a command handler or other logic file,
-    create and run an effect.
+2.  **Create and Execute an Effect:** In business logic, create and run an
+    effect.
 
     ```rust
-    // In a Mountain handler
-    use Common::fs;
-    use Common::effect::AppRuntime;
+    // In a Mountain service or command
+    use Common::FileSystem;
+    use Common::Effect::ApplicationRunTime;
 
-    async fn some_logic(runtime: Arc<impl AppRuntime>) {
+    async fn some_logic(runtime: Arc<impl ApplicationRunTime>) {
         let path = PathBuf::from("/my/file.txt");
-        let read_effect = fs::ReadFile(path);
+        let read_effect = FileSystem::ReadFile(path);
 
         match runtime.Run(read_effect).await {
             Ok(content) => info!("File content length: {}", content.len()),

docs/Deep Dive.md

@@ -22,8 +22,8 @@ The architecture of the `Common` crate is built on two fundamental principles:
 
 1.  **Separation of Concerns (The "What" vs. The "How"):** `Common` is strictly
     concerned with defining **what** the application can do. It does this by
-    defining abstract `trait`s (e.g., `trait FsReader`). It has absolutely no
-    knowledge of **how** these actions are performed. The concrete
+    defining abstract `trait`s (e.g., `trait FileSystemReader`). It has
+    absolutely no knowledge of **how** these actions are performed. The concrete
     implementation (the "how") is the responsibility of another crate,
     `Mountain`, which might use `tokio::fs` or a network client to fulfill the
     contract. This is a form of the "Ports and Adapters" architecture.
@@ -39,23 +39,23 @@ The architecture of the `Common` crate is built on two fundamental principles:
 
 ## Detailed Component Breakdown
 
-### 1. The `ActionEffect` System (`effect/`)
+### 1. The `ActionEffect` System (`Effect/`)
 
 This is the most important concept in the `Common` crate.
 
-- **`ActionEffect<RuntimeAccess, Error, Output>` Struct:**
+- **`ActionEffect<TCapability, TError, TOutput>` Struct:**
 
     - This struct does not contain logic. It simply wraps an
       `Arc<dyn Fn(...) -> Future>`.
     - The function it wraps is the "potential" operation. The `Arc` makes the
       effect cheap to clone and pass around.
     - The type parameters define the contract:
-        - `RuntimeAccess`: The type of capability the effect needs to run (e.g.,
-          `Arc<dyn FsReader>`).
-        - `Error`: The type of error it can fail with (always `CommonError`).
-        - `Output`: The type of value it will produce on success.
+        - `TCapability`: The type of capability the effect's closure needs to
+          run (e.g., `Arc<dyn FileSystemReader>`).
+        - `TError`: The type of error it can fail with (always `CommonError`).
+        - `TOutput`: The type of value it will produce on success.
 
-- **`AppRuntime` Trait:**
+- **`ApplicationRunTime` Trait:**
     - This trait defines the contract for an "executor". Its primary method is
       `Run`.
     - The `Run` method is what takes an `ActionEffect` value, provides it with
@@ -67,53 +67,53 @@ This is the most important concept in the `Common` crate.
 ```rust
 // 1. A constructor function in `Common` creates an effect.
 //    No I/O happens here. It just creates a struct.
-let read_effect = Common::fs::ReadFile(path);
+let read_effect = Common::FileSystem::ReadFile(path);
 
 // 2. The effect is passed to a runtime.
 let result = my_runtime.Run(read_effect).await;
 
 // 3. Inside the runtime's Run method:
-//    a. It gets its environment.
-//    b. It asks the environment for the required capability: `env.Require::<Arc<dyn FsReader>>()`.
-//    c. It calls the effect's internal function with the capability.
+//    a. It gets its environment using self.GetEnvironment().
+//    b. It asks the environment for the required capability: `env.Require::<Arc<dyn FileSystemReader>>()`.
+//    c. It calls the effect's internal function, passing in the required capability.
 //    d. The function is awaited, and the actual tokio::fs::read() call is finally made.
 ```
 
-### 2. The Dependency Injection System (`environment/`)
+### 2. The Dependency Injection System (`Environment/`)
 
 - **`Environment` Trait:** A simple marker trait. Any struct that can act as a
   dependency container for our application must implement this trait.
 - **`Requires<Capability>` Trait:** This is the core of the DI system. A struct
   implementing `Requires<T>` guarantees that it can provide an instance of `T`.
 - **Usage:** Our `MountainEnvironment` will implement
-  `Requires<Arc<dyn FsReader>>`, `Requires<Arc<dyn UiProvider>>`, etc., for
-  every service trait. The `AppRuntime` uses these implementations to provide
-  the necessary dependencies to the effects it runs. This decouples the effects
-  from the concrete environment.
+  `Requires<Arc<dyn FileSystemReader>>`,
+  `Requires<Arc<dyn UserInterfaceProvider>>`, etc., for every service trait. The
+  `ApplicationRunTime` uses these implementations to provide the necessary
+  dependencies to the effects it runs. This decouples the effects from the
+  concrete environment.
 
 ### 3. The Service Provider Pattern
 
-Every functional domain in `Common` (e.g., `fs`, `ui`, `command`) follows a
-strict pattern:
+Every functional domain in `Common` (e.g., `FileSystem`, `UserInterface`,
+`Command`) follows a strict pattern:
 
 1.  **A Trait Definition (`MyService/MyServiceProvider.rs`):** An `async trait`
     that defines the high-level capabilities of the service (e.g.,
-    `trait FsReader { async fn ReadFile(...); }`).
-2.  **DTOs (`MyService/dto/`):** A submodule containing all `serde`-compatible
+    `trait FileSystemReader { async fn ReadFile(...); }`).
+2.  **DTOs (`MyService/DTO/`):** A submodule containing all `serde`-compatible
     `struct`s and `enum`s that are used as parameters or return types for the
-    service's methods. These DTOs form the stable data contract for gRPC and
-    internal use.
+    service's methods. These DTOs form the stable data contract.
 3.  **Effect Constructors (`MyService/MyEffect.rs`):** A set of public
     functions, one for each method in the service trait. Each function takes the
     same arguments as the trait method but returns an `ActionEffect` instead of
     executing the logic directly.
 
-### 4. The Universal Error (`error/CommonError.rs`)
+### 4. The Universal Error (`Error/CommonError.rs`)
 
 - To maintain predictability, every `ActionEffect` returns a
   `Result<T, CommonError>`.
 - `CommonError` is a single, comprehensive `enum` that covers all possible
-  failure domains (Filesystem, IPC, UI, etc.).
+  failure domains (FileSystem, IPC, UI, etc.).
 - This pattern allows consumers of effects to handle all possible errors with a
   single `match` statement, while still providing specific, tagged error
   variants for precise handling when needed. It uses `thiserror::Error` for
@@ -125,55 +125,56 @@ strict pattern:
 
 Adding a new capability to the application follows a clear, repeatable recipe:
 
-1.  **Create the Module:** Create a new directory in `src/`, for example,
-    `src/new_service/`. Create a `mod.rs` inside it.
+1.  **Create the Module:** Create a new directory, e.g., `Source/NewService/`,
+    and a `mod.rs` inside it.
 
-2.  **Define the Trait:** In `src/new_service/NewServiceProvider.rs`, define the
-    new `async trait`:
+2.  **Define the Trait:** In `Source/NewService/NewServiceProvider.rs`, define
+    the new `async trait`:
 
     ```rust
     #[async_trait]
     pub trait NewServiceProvider: Environment {
-        async fn DoSomething(&self, Options: MyOptionsDto) -> Result<MyResultDto, CommonError>;
+        async fn DoSomething(&self, Options: MyOptionsDTO) -> Result<MyResultDTO, CommonError>;
     }
     ```
 
-3.  **Define the DTOs:** In `src/new_service/dto/`, create files for
+3.  **Define the DTOs:** In `Source/NewService/DTO/`, create files for
     `MyOptionsDto.rs` and `MyResultDto.rs` with
     `#[derive(Serialize, Deserialize)]`.
 
-4.  **Update `CommonError`:** In `src/error/CommonError.rs`, add a new variant
-    for failures related to your service:
+4.  **Update `CommonError`:** In `Source/Error/CommonError.rs`, add a new
+    variant for failures related to your service:
 
     ```rust
     #[error("NewService failed: {Reason}")]
     NewServiceError { Reason: String },
     ```
 
-5.  **Create the Effect Constructor:** In `src/new_service/DoSomething.rs`,
-    create the function that returns the `ActionEffect`:
+5.  **Create the Effect Constructor:** In `Source/NewService/DoSomething.rs`,
+    create the function that returns the `ActionEffect`. Note its signature:
+    it's no longer generic, and its dependency is explicit.
 
     ```rust
-    pub fn DoSomething<Runtime>(
-        Options: MyOptionsDto,
-    ) -> ActionEffect<Arc<Runtime>, CommonError, MyResultDto>
-    where
-        Runtime: AppRuntime + Send + Sync + 'static,
-        Runtime::EnvironmentType: Requires<Arc<dyn NewServiceProvider>>,
-    {
-        ActionEffect::New(Arc::new(move |Runtime: Arc<Runtime>| {
+    use std::sync::Arc;
+    use crate::Effect::ActionEffect;
+    use crate::Error::CommonError;
+    use super::NewServiceProvider;
+
+    pub fn DoSomething(
+        Options: MyOptionsDTO,
+    ) -> ActionEffect<Arc<dyn NewServiceProvider>, CommonError, MyResultDTO> {
+        ActionEffect::New(Arc::new(move |Provider: Arc<dyn NewServiceProvider>| {
             let OptionsClone = Options.clone();
             Box::pin(async move {
-                let Environment = Runtime.GetEnvironment();
-                let Provider: Arc<dyn NewServiceProvider> = Environment.Require();
                 Provider.DoSomething(OptionsClone).await
             })
         }))
     }
     ```
 
-6.  **Export from Modules:** Update `src/new_service/mod.rs` and `src/lib.rs` to
-    publicly export the new trait, DTOs, and effect constructor.
+6.  **Export from Modules:** Update `Source/NewService/mod.rs` and
+    `Source/Library.rs` to publicly export the new trait, DTOs, and effect
+    constructor.
 
 ---
 
@@ -182,12 +183,12 @@ Adding a new capability to the application follows a clear, repeatable recipe:
 - **`Mountain`:** `Mountain` is the primary **implementor** of the traits in
   `Common`. The `MountainEnvironment` struct will have
   `impl NewServiceProvider for MountainEnvironment` blocks that contain the
-  concrete logic, which in turn delegate to `handlers`. `Mountain` is also the
-  home of the `AppRuntime` that **executes** the effects.
-- **`Cocoon`:** `Cocoon` is a remote **consumer**. The gRPC methods defined in
-  `vine.proto` are designed to directly correspond to the effect constructors
-  and DTOs in `Common`. When `Cocoon` sends a request, `Mountain`'s `Track`
-  dispatcher creates the corresponding `ActionEffect` from `Common` and runs it.
+  concrete logic. `Mountain` is also the home of the `ApplicationRunTime` that
+  **executes** the effects.
+- **`Cocoon`:** `Cocoon` is a remote **consumer**. When `Cocoon` sends a
+  request, `Mountain`'s `Track` dispatcher creates the corresponding
+  `ActionEffect` from `Common` and runs it. The DTOs defined in `Common` serve
+  as the data contract for this communication.
 
 This clear separation ensures that `Common` remains the universal, abstract
 blueprint for all native backend functionality.