fix: documentation improvement and nvigation

Author: opemipodisu

docs/content/docs/(getting-started)/architecture.mdx

@@ -0,0 +1,155 @@
+---
+title: Platform Architecture
+description: ByteChef is an open-source, enterprise-ready platform for API integration and workflow automation.
+---
+
+ByteChef is built on a scalable, modular architecture designed to handle enterprise-grade workflow automation and integrations. The platform provides a flexible foundation that supports multiple deployment models, from cloud-hosted to on-premises deployments.
+
+## System Architecture Overview
+
+The ByteChef platform is composed of several interconnected layers that work together to deliver workflow automation capabilities.
+
+**API & Integration Layer** : This layer handles communication with external services and applications. It provides comprehensive REST and GraphQL APIs that allow seamless integration with over 500+ pre-built connectors and custom integrations through our component system.
+
+**Workflow Engine** : The core execution engine processes workflow definitions, manages task execution, handles data transformations, and orchestrates component interactions. It supports parallel execution, conditional branching, looping, and error handling.
+
+**Component System** : A modular framework for building integrations. Each component encapsulates actions, triggers, and connections to external services. Components can be pre-built (Slack, GitHub, Salesforce, etc.) or custom-built using our developer framework.
+
+**Data & State Management** : Manages workflow execution state, handles data persistence, processes data mappings and transformations, and maintains audit logs for compliance and debugging.
+
+**Runtime & Execution** : Provides execution environments for workflows, manages job scheduling and queueing, handles resource allocation, and enables both synchronous and asynchronous execution patterns.
+
+## Multi-Tier Deployment Architecture
+
+ByteChef supports flexible deployment options to meet different organizational needs.
+
+**Cloud Deployment** : ByteChef Cloud is our managed, hosted solution. Users access the platform via a web-based interface with zero infrastructure management. Ideal for teams wanting quick time-to-value without managing their own infrastructure. Includes automatic scaling, security patches, and regular updates.
+
+**Self-Hosted Deployment** : Organizations can deploy ByteChef on their own infrastructure using Docker, Kubernetes, AWS, Azure, Google Cloud, or DigitalOcean. Provides complete control over data, infrastructure, and customization. Suitable for enterprises with specific compliance, security, or data residency requirements.
+
+## Core Components
+
+**Web Interface** : User-friendly workflow builder with drag-and-drop component configuration, real-time execution monitoring, and workflow management capabilities. Built with React and TypeScript for a responsive, modern experience.
+
+**API Server** : Handles all API requests, manages authentication and authorization, processes workflow definitions, and orchestrates execution. Provides REST endpoints for programmatic access to all platform features.
+
+**Workflow Engine** : Processes workflow definitions in JSON format, manages execution state and transitions between tasks, handles error recovery and retries, and supports complex control flow patterns including branches, loops, and parallel execution.
+
+**Component Registry** : Centralizes all available components and their metadata, manages component versioning and updates, and provides discovery and configuration interfaces for users.
+
+**Data Storage** : Persists workflow definitions, execution history, audit logs, and user data. Supports multiple database backends (PostgreSQL, MySQL, etc.) and file storage options.
+
+**Message Queue** : Handles asynchronous task processing, manages job scheduling and prioritization, and enables decoupled processing for improved scalability and reliability.
+
+## Workflow Execution Flow
+
+When you trigger a workflow, the platform executes it through a well-defined pipeline.
+
+1. **Trigger Activation** : A webhook, schedule, or manual trigger initiates workflow execution
+2. **Workflow Parsing** : The engine loads and parses the workflow definition
+3. **Input Processing** : Trigger data is prepared and validated
+4. **Component Execution** : Tasks execute sequentially or in parallel based on workflow configuration
+5. **Data Transformation** : Data flows between components using mapping expressions
+6. **Conditional Logic** : Branches are evaluated and appropriate paths are taken
+7. **Output Generation** : Final results are formatted and returned
+8. **State Persistence** : Execution state and logs are saved for monitoring and debugging
+
+## Integration Architecture
+
+ByteChef connects applications through a standardized component model.
+
+**Connection Management** : Securely stores API credentials, OAuth tokens, and authentication details. Supports multiple authentication methods (API keys, OAuth 2.0, Basic Auth, custom).
+
+**Component Interface** : Standardized interface that all components implement, ensuring consistency across 500+ integrations. Each component defines its actions, triggers, and required properties.
+
+**Data Mapping** : Powerful expression engine allows transforming and mapping data between components. Supports JavaScript expressions, field references, and utility functions for data manipulation.
+
+**Error Handling** : Components can define retry strategies, timeout behaviors, and error recovery patterns. The engine supports both component-level and workflow-level error handling.
+
+## Scalability & Performance
+
+ByteChef is designed to handle enterprise-scale automation demands.
+
+**Horizontal Scaling** : The stateless design of the API server and execution engine allows deploying multiple instances behind a load balancer for handling increased load.
+
+**Asynchronous Processing** : Heavy operations are queued and processed asynchronously, preventing blocking and ensuring responsive APIs.
+
+**Resource Management** : Execution is optimized for efficiency with configurable timeouts, concurrent execution limits, and resource allocation policies.
+
+**Data Efficiency** : Large payloads are handled efficiently with streaming support, compression options, and smart caching strategies.
+
+## Security Architecture
+
+Security is built into every layer of the platform.
+
+**Authentication** : Supports multiple authentication methods including OAuth 2.0, API keys, and single sign-on (SSO) integration.
+
+**Authorization** : Fine-grained RBAC (Role-Based Access Control) allows controlling what users can access and modify at the project and workflow levels.
+
+**Data Protection** : Credentials are encrypted at rest and in transit. Sensitive data in logs is masked. Audit logs track all actions for compliance.
+
+**API Security** : Rate limiting, input validation, and CORS protection prevent abuse. All API endpoints require authentication.
+
+## Monitoring & Observability
+
+Complete visibility into workflow execution and system health.
+
+**Execution Tracking** : Real-time monitoring of workflow runs with detailed execution logs showing each step, data transformations, and timing information.
+
+**Performance Metrics** : Track workflow execution duration, error rates, and component performance. Identify bottlenecks and optimization opportunities.
+
+**Audit Logging** : Comprehensive logs of all system activities for compliance, debugging, and security investigation.
+
+**Alerting** : Configurable alerts for workflow failures, performance issues, and security events enable proactive issue management.
+
+## Development & Extensibility
+
+Build custom integrations and extend the platform.
+
+**Component Development** : Developer SDK for building custom components in TypeScript/JavaScript. Create actions, triggers, and connections for proprietary or niche systems.
+
+**API Access** : Full API access enables building custom applications on top of ByteChef or integrating it into existing systems.
+
+**Webhooks** : Send workflow data to external systems in real-time using webhooks. Enables two-way integrations and event-driven architectures.
+
+**Configuration as Code** : Define workflows in JSON format, enabling version control, CI/CD integration, and infrastructure-as-code practices.
+
+## Data Flow & Processing
+
+Understanding how data flows through ByteChef helps design efficient workflows.
+
+Data enters through triggers (webhooks, schedules, manual), flows through components where it's transformed and processed, and exits through actions that update external systems or return results. At each step, data can be validated, filtered, and transformed using expressions. The platform maintains execution context throughout the workflow, allowing components to reference outputs from previous steps.
+
+## Technology Stack
+
+ByteChef leverages proven, open-source technologies.
+
+**Backend** : Java/Spring Boot for the core platform, providing stability, performance, and extensive ecosystem support.
+
+**Frontend** : React with TypeScript for a modern, responsive user interface.
+
+**Database** : PostgreSQL as the primary data store, with support for other databases.
+
+**Message Queue** : RabbitMQ or similar for asynchronous job processing and reliable message delivery.
+
+**Container** : Docker for containerization, enabling deployment flexibility across cloud and on-premises environments.
+
+## Architecture Benefits
+
+The modular, layered architecture provides several advantages.
+
+**Scalability** : Add more nodes to handle increased load without redesigning the system.
+
+**Reliability** : Separated concerns and async processing prevent cascading failures.
+
+**Flexibility** : Modular design allows customization at every level without touching core platform code.
+
+**Maintainability** : Clear separation of concerns makes the system easier to understand and maintain.
+
+**Security** : Multiple layers of security controls with defense in depth approach.
+
+**Performance** : Optimized data flow, caching strategies, and async processing ensure fast execution.
+
+---
+
+For information on deploying ByteChef in your specific environment, see the [Deployment](/deployment/environment_variables) section. For details on building custom integrations, visit the [Developer Guide](/developer-guide).

docs/content/docs/automation/glossary.mdx …tent/docs/(getting-started)/glossary.mdxdocs/content/docs/automation/glossary.mdx renamed to docs/content/docs/(getting-started)/glossary.mdx docs/content/docs/automation/glossary.mdx renamed to docs/content/docs/(getting-started)/glossary.mdx

@@ -3,6 +3,8 @@ title: Glossary
 description: Terms used in ByteChef platform.
 ---
 
+In this document, you will find a list of terms used in ByteChef's platform. Here are the definitions:
+
 ## Projects
 
 Projects are containers that hold one or more workflows. Projects help organize and manage workflows, making it easier to group related automation processes together. Users can create, edit, duplicate, import, and delete projects to streamline their automation efforts.
@@ -15,7 +17,7 @@ Workflows are a series of actions and triggers that automate processes within th
 
 In ByteChef, a component is a modular building block that encapsulates specific functionalities within the platform. Each component is designed to interact with external services or perform particular tasks, making it an essential part of creating workflows.
 
-Components are composed of two main elements actions and triggers.
+Components are composed of two main elements: actions and triggers.
 
 By combining actions and triggers, components enable users to automate complex processes and integrate various services seamlessly. Components are designed to be reusable and extendable, allowing users to customize and expand their workflows according to their needs.
 
@@ -29,4 +31,4 @@ These are events that initiate a workflow. Triggers listen for specific occurren
 
 ## Actions
 
-These are operations that a component can perform. Actions typically involve sending data to an external service, retrieving information, or manipulating data within the workflow. For example, an action might send an email, update a database record, or fetch user details from an API.
+These are operations that a component can perform. Actions typically involve sending data to an external service, retrieving information, or manipulating data within the workflow. For example, an action might send an email, update a database record, or fetch user details from an API.

…content/docs/(platform)/introduction.mdx …/docs/(getting-started)/introduction.mdxdocs/content/docs/(platform)/introduction.mdx renamed to docs/content/docs/(getting-started)/introduction.mdx docs/content/docs/(platform)/introduction.mdx renamed to docs/content/docs/(getting-started)/introduction.mdx

@@ -1,14 +1,16 @@
 ---
 title: Introduction
-description: Introducing ByteChef, an open-source platform for AI agents, workflow automation, and app integration.
+description: This is the documentation for ByteChef, an open-source workflow automation platform that connects your entire tech stack with AI-powered intelligence.
 icon: Album
 ---
 
 import {Card, Cards} from "fumadocs-ui/components/card";
 import {Blocks, LayoutTemplate, Terminal, Workflow} from "lucide-react";
 import {Callout} from "fumadocs-ui/components/callout";
 
-ByteChef has different parts:
+This documentation covers everything from setup to usage and development. It's a work in progress but all contributions are welcome. 
+
+## Pick Your Path
 
 <Cards>
   <Card icon={<Workflow className="text-purple-300" />} title='Automation' href="/automation">
@@ -29,7 +31,7 @@ ByteChef has different parts:
 </Cards>
 
 <Callout title="Want to learn more?">
-  Read our in-depth [Platform Overview](/platform-overview) introduction.
+  Read our in-depth [Platform documentation](/platform/overview).
 </Callout>
 
 ## Community support
@@ -38,7 +40,7 @@ For help, you can use one of these channels to ask a question:
 
 - [Discord](https://discord.gg/VKvNxHjpYx) - Discussions with the community and the team.
 - [GitHub](https://github.com/bytechefhq/bytechef/issues) - For bug reports and feature requests.
-- [Twitter](https://twitter.com/bytechefhq) - Get the product updates easily.
+- [X/Twitter](https://twitter.com/bytechefhq) - Get the product updates easily.
 
 ## Roadmap
 

docs/content/docs/(getting-started)/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "Getting Started",
+  "description": "Get started with ByteChef",
+  "icon": "Rocket",
+  "pages": [
+    "---Getting Started---",
+    "introduction",
+    "what-is-bytechef",
+    "quickstart",
+    "architecture",
+    "glossary"
+  ]
+}

docs/content/docs/(getting-started)/quickstart.mdx

@@ -0,0 +1,135 @@
+---
+title: "Quick Start"
+description: "This guide walks you through the basics of ByteChef in a few minutes. You'll learn how to build a workflow quickly, so no much configuration needed."
+---
+
+In this tutorial, you'll learn:
+
+- How to build a workflow quickly with ByteChef's Workflow Builder
+- How to add and configure a component with data expressions
+- How to execute workflow automations
+
+
+## Pick Your Platform
+
+You have two ways to use ByteChef:
+
+- **[ByteChef Cloud](https://app.bytechef.io/)**: We host it. Zero installation. Best for testing and getting familiar with the platform. We'll use this for this guide.
+
+- **Your own infrastructure (Self-Hosted)**: Deploy and run ByteChef yourself. Supported on:
+
+  - [Docker](/self-hosting/docker)
+  - [Kubernetes](/self-hosting/kubernetes)
+  - [AWS EC2](/self-hosting/aws-ec2)
+  - [AWS ECS](/self-hosting/aws-ecs)
+  - [Azure Container Instance](/self-hosting/azure-container-instance)
+  - [Google Cloud Run](/self-hosting/google-cloud-run)
+  - [DigitalOcean](/self-hosting/digitalocean)
+
+If you're ready to selfhost, you can pick any of the platforms above for detailed setup instructions.
+
+In this quickstart guide, we'll be working with the Cloud instance so you can dive in immediately. You can switch to self-hosted instance anytime after you finish this guide.
+
+## Step 1: Create a Project
+
+- Go to your ByteChef dashboard on the [Cloud](https://app.bytechef.io/) or Self-hosted instance
+- Click on `Create Project`
+- Enter your project's name and description click `Create`
+
+## Step 2: Create Your First Workflow
+
+Inside your project:
+
+- Click the <img 
+    src="/addworkflow.png" 
+    alt="add workflow" 
+    width="100"
+    height="20"
+    style={{
+      display: 'inline',
+      verticalAlign: 'middle',
+      margin: '0 4px'
+    }}
+  /> button in the project pane
+- Give it a label (e.g., "Send Welcome Email")
+- Click `Save`.
+
+Now, you now have a blank canvas in your workflow; let's build something.
+
+## Step 3: Add a Trigger
+
+Every workflow in ByteChef starts with a trigger, it's the event that kicks off your automation.
+
+- Click the **+** button on the canvas
+- Search for and select Manual Trigger (this lets you start the workflow by testing or deploying)
+- Click to confirm
+
+<div style={{ width: '300px' }}>
+  <img src="/manualtrigger.png" alt="manual trigger" style={{ width: '100%', height: 'auto' }} />
+</div>
+
+## Step 4: Add and Configure Your First Component
+
+Now, let's add a component that does something. Let's use the Spotify component to create a playlist and share with your teammates on Slack. 
+
+- Click the + icon after the Manual Trigger
+- Search for Spotify
+- Select **Spotify** and click to add it
+- Select an action from the dropdown (the **Create Playlist** action)
+- Configure the component:
+  - Make a connection with the component by providing your Spotify Client ID and Client Secret
+  - In the properties panel, provide the playlist name and description
+  - Select if you want the playlist to be public or private
+  - Select if you want the playlist to be collaborative or not
+- Add the **Slack** component and select the **Send Channel Message** action
+- Configure the component:
+  - Make a connection with the component by providing your Slack Bot User OAuth Access Token
+  - In the properties panel, provide the channel ID and message. 
+  - In the message section of the Slack properties panel, click on the message tab and enter this expression:
+
+```
+🎵 New playlist created: Slack Shared Songs
+Playlist:${spotify_1.external_urls.spotify}
+Start adding your favorite songs!
+```
+
+## Step 5: Test Your Workflow
+
+Click the test button at the top right corner of the workflow. ByteChef runs your workflow:
+
+- The Manual Trigger activates the workflow
+- The Spotify component creates a playlist
+- The Slack component sends a message to a channel
+
+You'll see the execution results below:
+
+![worklow execution](/workflowexecution.png)
+
+Check your configured Slack channel to see a message in Slack:
+
+<div style={{ width: '400px' }}>
+  <img src="/spotifyslackmessage.png" alt="slack message" style={{ width: '100%', height: 'auto' }} />
+</div>
+
+## What You've Built
+
+Your workflow now looks like:
+
+```
+Manual Trigger → Spotify (Create Playlist) → Slack (Send Message)
+```
+
+The demo in this quickstart demonstrates the core concept of automation:
+
+- **Trigger**: Something starts the workflow
+- **Components**: Do the actual work (create, fetch, send)
+- **Expressions**: Pull data between components using `{{ $json.fieldName }}`
+
+## Next Steps
+
+Here are a few things you can explore next:
+
+- [Build Workflows](/automation/build-workflows)
+- [Browse 200+ Components](/reference/components)
+- [Deploy your workflow](/automation/deploy)
+- [Monitor Executions](/automation/monitor)