Feat/elim spof

.github/workflows/docs.yml

@@ -2,25 +2,29 @@ name: Build and Deploy Docs
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, main ]
     paths:
       - 'docs/**'
       - 'README.md'
+      - 'mkdocs.yml'
+  pull_request:
+    branches: [ master, main ]
+    paths:
+      - 'docs/**'
+      - 'README.md'
+      - 'mkdocs.yml'
   workflow_dispatch:
 
 jobs:
-  build-and-deploy:
+  # Build job - runs on all branches for validation
+  build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pages: write
-      id-token: write
-
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.x'
 
@@ -30,11 +34,53 @@ jobs:
           pip install mkdocs mkdocs-material
 
       - name: Build documentation
-        run: mkdocs build 
+        run: mkdocs build --strict --verbose
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: ./site
+
+  # Deploy job - only runs on main branches
+  deploy:
+    # Only deploy on main/master branches, not on PRs or feature branches
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+
+    runs-on: ubuntu-latest
+    needs: build
+
+    # Environment is required for GitHub Pages deployment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+    # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
 
-      - name: Deploy documentation
-        uses: peaceiris/actions-gh-pages@v3
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          force_orphan: true
+          name: docs-site
+          path: ./site
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/examples/applications.md

@@ -902,4 +902,4 @@ These examples demonstrate various patterns and configurations for different typ
 
 ---
 
-**Next Steps**: Explore [Deployment Scenarios](deployments.md) for different infrastructure patterns.
+**Next Steps**: Explore [Configuration Guide](../user-guide/configuration.md) for advanced deployment settings.

docs/index.md

@@ -0,0 +1,64 @@
+# AutoServe Documentation
+
+Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications.
+
+## Documentation Structure
+
+### For Users
+- [Quick Start Guide](user-guide/quick-start.md) - Get up and running in minutes
+- [CLI Reference](user-guide/cli-reference.md) - Complete command-line interface documentation
+- [Application Specification](user-guide/app-spec.md) - How to define your applications
+- [Configuration Guide](user-guide/configuration.md) - Environment and scaling configuration
+- [REST API Reference](user-guide/api-reference.md) - HTTP API endpoints and usage
+- [Troubleshooting](user-guide/troubleshooting.md) - Common issues and solutions
+
+### For Developers
+- [Architecture Overview](developer-guide/architecture.md) - System design and components
+- [Core Components](developer-guide/components.md) - Detailed component documentation
+- [Leader Election](developer-guide/leader-election.md) - Distributed controller and high availability
+- [Database Schema](developer-guide/database.md) - State management and persistence
+- [Scaling Algorithm](developer-guide/scaling.md) - Auto-scaling logic and policies
+- [Health Monitoring](developer-guide/health.md) - Health check system
+- [Load Balancing](developer-guide/load-balancing.md) - Nginx integration and routing
+- [Development Setup](developer-guide/development.md) - Contributing to AutoServe
+- [Extension Guide](developer-guide/extensions.md) - Adding new features
+
+### Examples
+- [Sample Applications](examples/applications.md) - Real-world application examples
+
+## What is AutoServe?
+
+AutoServe is a container orchestration platform that provides:
+
+- **Intelligent Auto-Scaling**: Automatically scales your applications based on CPU, memory, RPS, latency, and connection metrics
+- **Load Balancing**: Dynamic Nginx configuration with health-aware routing
+- **Health Monitoring**: Continuous health checks with automatic recovery
+- **Simple Deployment**: YAML-based application specifications
+- **RESTful API**: Complete programmatic control
+- **High Availability**: Distributed controller with leader election eliminates single points of failure
+- **Database HA**: PostgreSQL-based state management with primary-replica replication
+
+## Key Features
+
+- **Container Orchestration**: Docker-based application lifecycle management
+- **Multi-Metric Auto-Scaling**: CPU, memory, RPS, latency, and connection-based scaling
+- **Dynamic Load Balancing**: Nginx with health-aware routing and SSL termination
+- **Health Monitoring**: Continuous health checks with automatic recovery
+- **Distributed Architecture**: 3-node controller cluster with leader election
+- **High Availability**: Automatic failover and split-brain prevention
+- **CLI and REST API**: Complete programmatic and command-line interfaces
+- **Persistent State**: PostgreSQL with primary-replica setup
+- **Event Logging**: Complete audit trail and cluster event tracking
+- **Resource Management**: CPU/memory constraints and intelligent scaling policies 
+
+## Quick Links
+
+- [Installation](user-guide/quick-start.md#installation)
+- [Your First Application](user-guide/quick-start.md#deploying-your-first-app)
+- [CLI Commands](user-guide/cli-reference.md)
+- [API Endpoints](user-guide/api-reference.md)
+- [Architecture](developer-guide/architecture.md)
+
+---
+
+*AutoServe v1.0.0 - Built for simplicity, designed for scale*

docs/user-guide/quick-start.md

@@ -283,7 +283,7 @@ Now that you have AutoServe running:
 2. **Understand App Specs**: Read the [Application Specification](app-spec.md) guide
 3. **Explore the API**: See the [REST API Reference](api-reference.md)
 4. **Configure Scaling**: Dive into [Configuration Guide](configuration.md)
-5. **Monitor Applications**: Learn about [monitoring and metrics](monitoring.md)
+5. **Monitor Applications**: Learn about [health monitoring](../developer-guide/health.md)
 
 ## Getting Help
 

mkdocs.yml

@@ -1,12 +1,63 @@
-site_name: AutoServe
+site_name: AutoServe Documentation
 site_url: https://arjuuuuunnnnn.github.io/AutoServe/
-use_directory_urls: false
+site_description: AutoServe - Container Orchestration and Auto-Scaling Platform
+use_directory_urls: true
+repo_url: https://github.com/arjuuuuunnnnn/AutoServe
+repo_name: arjuuuuunnnnn/AutoServe
 
 nav:
-  - Home: README.md
+  - Home: index.md
+
+  - User Guide:
+    - Quick Start: user-guide/quick-start.md
+    - CLI Reference: user-guide/cli-reference.md
+    - Application Specification: user-guide/app-spec.md
+    - Configuration: user-guide/configuration.md
+    - API Reference: user-guide/api-reference.md
+    - Troubleshooting: user-guide/troubleshooting.md
+
+  - Developer Guide:
+    - Architecture Overview: developer-guide/architecture.md
+    - Core Components: developer-guide/components.md
+    - Leader Election: developer-guide/leader-election.md
+    - Database Schema: developer-guide/database.md
+    - Scaling Algorithm: developer-guide/scaling.md
+    - Health Monitoring: developer-guide/health.md
+    - Load Balancing: developer-guide/load-balancing.md
+    - Development Setup: developer-guide/development.md
+    - Extensions: developer-guide/extensions.md
+
+  - Examples:
+    - Sample Applications: examples/applications.md
 
 theme:
   name: material
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+
 site_dir: site
 
 plugins:
@@ -15,4 +66,26 @@ plugins:
 markdown_extensions:
   - toc:
       permalink: true
+      toc_depth: 3
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/arjuuuuunnnnn/AutoServe
+  version:
+    provider: mike