diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000000..33f927dcc75
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,98 @@
+---
+title: 'CLI Architecture'
+weight: 40
+---
+
+The AsyncAPI CLI uses oclif (Open CLI Framework) as its core framework, which allows customers to build powerful and scalable command-line applications. 
+
+**Structure of the Asyncapi CLI**: The CLI mainly divides into two components that is commands and the core part.
+
+1. **Command Component** : The Commands contains all the necessary commands that helps to developers to interact with multiple functionality like creating new Asyncapi projects, validating asyncapi file, formatting asyncapi file etc. 
+2. **Core Component**: The Core part of the CLI contains all teh 
+
+
+
+### **Detailed Explanation of Key Directories**
+
+#### **`src/commands/`**
+- **Purpose:** Implements the CLI commands available to the user.
+- **Subdirectories:**
+  - `config/`: Stores configuration-related files for commands.
+  - `generate/`: Implements logic for generating AsyncAPI-related artifacts.
+    - **Files:**
+      - `fromTemplate.ts`: Logic for generating files using templates.
+      - `models.ts`: Defines the models used in generation.
+  - `new/`: Logic for creating new AsyncAPI projects.
+    - **Files:**
+      - `file.ts`: Handles file creation logic.
+      - `glee.ts`: Related to Glee, a tool for event-driven microservices.
+      - `template.ts`: Deals with templates for new projects.
+  - `start/`: Implements starting functionalities like starting a local server or studio.
+    - **Files:**
+      - `studio.ts`: Integrates with the AsyncAPI Studio.
+
+- **Standalone Files:**
+  - `bundle.ts`: Bundles multiple AsyncAPI files.
+  - `convert.ts`: Converts AsyncAPI documents between different formats.
+  - `diff.ts`: Compares two AsyncAPI documents.
+  - `format.ts`: Formats AsyncAPI documents.
+  - `optimize.ts`: Optimizes AsyncAPI documents for performance.
+  - `pretty.ts`: Prettifies AsyncAPI documents.
+  - `validate.ts`: Validates AsyncAPI documents for correctness.
+
+---
+
+#### **`src/core/`**
+- **Purpose:** Provides foundational components and utilities for the CLI.
+- **Subdirectories:**
+  - `errors/`: Centralized error definitions.
+  - `flags/`: Defines CLI flags and their behavior.
+  - `hooks/`: Event hooks used for customization.
+  - `models/`: Core data models used across the application.
+  - `utils/`: Utility functions for common operations.
+
+- **Standalone Files:**
+  - `base.ts`: Base class or logic for CLI commands.
+  - `global.d.ts`: Global TypeScript definitions.
+  - `globals.ts`: Stores global variables and configurations.
+  - `parser.ts`: Parses AsyncAPI documents.
+
+---
+
+#### **`test/`**
+- **Purpose:** Implements the test suite for the CLI.
+- **Subdirectories:**
+  - `fixtures/`: Contains mock data or files for testing.
+  - `hooks/`: Tests related to hooks.
+  - `integration/`: Integration tests to verify end-to-end functionality.
+  - `system/`: System-level tests.
+  - `unit/`: Unit tests for individual modules or functions.
+
+---
+
+### **Use Cases**
+
+1. **Generate AsyncAPI Artifacts:**
+   - Use the `generate` command to create client/server code, documentation, or other artifacts based on AsyncAPI templates.
+
+2. **Create New Projects:**
+   - The `new` command helps users scaffold new AsyncAPI projects with predefined templates.
+
+3. **Validate AsyncAPI Documents:**
+   - The `validate` command ensures AsyncAPI documents conform to the specification.
+
+4. **Optimize and Format Documents:**
+   - The `optimize` and `pretty` commands provide tools for improving document readability and performance.
+
+5. **Compare Documents:**
+   - The `diff` command enables comparison between two AsyncAPI documents to track changes.
+
+6. **Integration with AsyncAPI Studio:**
+   - The `start` command integrates with the AsyncAPI Studio for editing and visualizing documents.
+
+7. **Convert Between Formats:**
+   - The `convert` command supports converting AsyncAPI documents between formats like YAML and JSON.
+
+
+
+This structure ensures the CLI is modular, scalable, and easy to maintain. Let me know if you need further clarification or additional details!
diff --git a/docs/context.md b/docs/context.md
index 30803782e55..2a64fab21ef 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -1,6 +1,6 @@
 ---
 title: 'Context concept'
-weight: 50
+weight: 60
 ---
 
 ## Overview
diff --git a/docs/metrics_collection.md b/docs/metrics_collection.md
index cd9a4c6f777..4df0dec069e 100644
--- a/docs/metrics_collection.md
+++ b/docs/metrics_collection.md
@@ -1,6 +1,6 @@
 ---
 title: 'Metrics Collection'
-weight: 60
+weight: 70
 ---
 
 # Metrics collection guideline
diff --git a/docs/usage.md b/docs/usage.md
index 22e0aafe071..5848de7aa2c 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,6 +1,6 @@
 ---
 title: 'Usage'
-weight: 40
+weight: 50
 ---
 
 <!--