diff --git a/.github/workflows/claude-code-architecture-validation.yml b/.github/workflows/claude-code-architecture-validation.yml
new file mode 100644
index 000000000..233c2847c
--- /dev/null
+++ b/.github/workflows/claude-code-architecture-validation.yml
@@ -0,0 +1,404 @@
+name: "+ Claude Code / Architecture Doc Validation"
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+  workflow_dispatch:
+    inputs:
+      platform_environment:
+        description: 'Environment to use'
+        required: false
+        default: 'staging'
+        type: choice
+        options:
+          - staging
+          - production
+
+jobs:
+  architecture-validation:
+    uses: ./.github/workflows/_claude-code.yml
+    with:
+      platform_environment: ${{ inputs.platform_environment || 'staging' }}
+      mode: 'automation'
+      track_progress: ${{ github.event_name != 'workflow_dispatch' && true || false }}
+      allowed_tools: 'Read,Glob,Grep,LS,Bash(git:*),Bash(gh:*),Bash(find:*),Bash(diff:*),Bash(uv:*)'
+      prompt: |
+        # SOFTWARE ARCHITECTURE VALIDATION FOR PULL REQUEST
+
+        **REPO**: ${{ github.repository }}
+        **PR**: ${{ github.event.pull_request.number && format('#{0}', github.event.pull_request.number) || 'Manual Run' }}
+        **BRANCH**: ${{ github.event.pull_request.head.ref || github.ref_name }}
+
+        ## Context
+
+        This PR validation checks if `SOFTWARE_ARCHITECTURE.md` accurately reflects 
+        the current codebase structure, dependencies, and architectural patterns after 
+        the proposed changes in this PR.
+
+        ## Your Mission
+
+        Analyze the changes in this PR and validate that the Software Architecture 
+        document remains accurate, complete, and up-to-date.
+
+        ## Step 1: Understand PR Changes
+
+        ```bash
+        echo "=== Analyzing PR Changes ==="
+        echo ""
+        
+        # Check if this is a PR or manual run
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        
+        if [ -n "$PR_NUMBER" ]; then
+          echo "Changed files in this PR:"
+          gh pr view "$PR_NUMBER" --json files --jq '.files[].path' | sort
+          echo ""
+          echo "Detailed diff:"
+          gh pr diff "$PR_NUMBER"
+        else
+          echo "Manual run - comparing with main branch"
+          echo "Changed files:"
+          git diff --name-only origin/main...HEAD | sort
+          echo ""
+          echo "Detailed diff:"
+          git diff origin/main...HEAD
+        fi
+        ```
+
+        ## Step 2: Read Current Architecture Document
+
+        ```bash
+        echo "=== Reading Architecture Document ==="
+        echo ""
+        # Read the current SOFTWARE_ARCHITECTURE.md
+        cat SOFTWARE_ARCHITECTURE.md
+        ```
+
+        ## Step 3: Validate Architecture Accuracy
+
+        For each change in the PR, check if the architecture document needs updates:
+
+        ### Check 1: New Modules or Files
+
+        ```bash
+        # Look for new modules
+        echo "=== Checking for New Modules ==="
+        
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        
+        # Check if new directories were added in src/aignostics/
+        if [ -n "$PR_NUMBER" ]; then
+          NEW_MODULES=$(gh pr diff "$PR_NUMBER" | grep "^+++ b/src/aignostics/" | cut -d/ -f3 | sort -u)
+        else
+          NEW_MODULES=$(git diff origin/main...HEAD --name-only | grep "^src/aignostics/" | cut -d/ -f3 | sort -u)
+        fi
+        
+        if [ -n "$NEW_MODULES" ]; then
+          echo "New modules detected:"
+          echo "$NEW_MODULES"
+          
+          # Check if these are documented in SOFTWARE_ARCHITECTURE.md
+          for module in $NEW_MODULES; do
+            if grep -q "$module" SOFTWARE_ARCHITECTURE.md; then
+              echo "  ✅ $module is documented"
+            else
+              echo "  ❌ BLOCKING: $module NOT documented in architecture"
+            fi
+          done
+        fi
+        ```
+
+        ### Check 2: Dependency Changes
+
+        ```bash
+        echo "=== Checking Dependency Changes ==="
+        
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        
+        # Check if pyproject.toml was modified
+        if [ -n "$PR_NUMBER" ]; then
+          PYPROJECT_CHANGED=$(gh pr diff "$PR_NUMBER" --name-only | grep -q "pyproject.toml" && echo "yes" || echo "no")
+        else
+          PYPROJECT_CHANGED=$(git diff origin/main...HEAD --name-only | grep -q "pyproject.toml" && echo "yes" || echo "no")
+        fi
+        
+        if [ "$PYPROJECT_CHANGED" = "yes" ]; then
+          echo "⚠️  pyproject.toml was modified - check if dependencies section needs update"
+          
+          # Extract new dependencies from diff
+          if [ -n "$PR_NUMBER" ]; then
+            gh pr diff "$PR_NUMBER" -- pyproject.toml | grep "^+" | grep -E "(dependencies|extras)" || echo "No dependency changes detected"
+          else
+            git diff origin/main...HEAD -- pyproject.toml | grep "^+" | grep -E "(dependencies|extras)" || echo "No dependency changes detected"
+          fi
+        fi
+        ```
+
+        ### Check 3: Workflow/CI Changes
+
+        ```bash
+        echo "=== Checking CI/CD Changes ==="
+        
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        
+        # Check if workflows were added/modified
+        if [ -n "$PR_NUMBER" ]; then
+          WORKFLOW_FILES=$(gh pr diff "$PR_NUMBER" --name-only | grep ".github/workflows/" || echo "")
+        else
+          WORKFLOW_FILES=$(git diff origin/main...HEAD --name-only | grep ".github/workflows/" || echo "")
+        fi
+        
+        if [ -n "$WORKFLOW_FILES" ]; then
+          echo "⚠️  GitHub workflows modified - check if CI/CD section needs update"
+          echo "$WORKFLOW_FILES"
+        fi
+        ```
+
+        ### Check 4: Architecture Pattern Changes
+
+        ```bash
+        echo "=== Checking Architecture Patterns ==="
+        
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        
+        # Look for significant structural changes
+        if [ -n "$PR_NUMBER" ]; then
+          SIGNIFICANT_CHANGES=$(gh pr diff "$PR_NUMBER" --name-only | grep -E "(src/aignostics/.*/_service.py|src/aignostics/.*/_cli.py|src/aignostics/.*/_gui.py|src/aignostics/utils/)" || echo "")
+        else
+          SIGNIFICANT_CHANGES=$(git diff origin/main...HEAD --name-only | grep -E "(src/aignostics/.*/_service.py|src/aignostics/.*/_cli.py|src/aignostics/.*/_gui.py|src/aignostics/utils/)" || echo "")
+        fi
+        
+        if [ -n "$SIGNIFICANT_CHANGES" ]; then
+          echo "Significant architectural files changed:"
+          echo "$SIGNIFICANT_CHANGES"
+          
+          # Read these files to understand the changes
+          for file in $SIGNIFICANT_CHANGES; do
+            echo ""
+            echo "=== Reading: $file ==="
+            cat "$file" 2>/dev/null || echo "File not found or deleted"
+          done
+        fi
+        ```
+
+        ### Check 5: Module Structure Validation
+
+        ```bash
+        echo "=== Validating Module Structure ==="
+        
+        # List current modules
+        CURRENT_MODULES=$(find src/aignostics -maxdepth 1 -type d -not -name "__pycache__" -not -name "aignostics" | sed 's|src/aignostics/||' | sort)
+        
+        echo "Current modules in codebase:"
+        echo "$CURRENT_MODULES"
+        echo ""
+        
+        # Check which modules are documented in SOFTWARE_ARCHITECTURE.md
+        echo "Checking documentation coverage:"
+        for module in $CURRENT_MODULES; do
+          if [ -n "$module" ]; then
+            if grep -qi "$module" SOFTWARE_ARCHITECTURE.md; then
+              echo "  ✅ $module - documented"
+            else
+              echo "  ⚠️  $module - not found in architecture doc"
+            fi
+          fi
+        done
+        ```
+
+        ## Step 4: Generate PR Comment
+
+        After validation, post findings as a PR comment:
+
+        ```bash
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        BRANCH_NAME="${{ github.event.pull_request.head.ref || github.ref_name }}"
+        
+        # Build the comment with actual values
+        cat > /tmp/architecture-validation.md << EOF
+        # 🏗️ Software Architecture Validation
+
+        **PR**: $([ -n "$PR_NUMBER" ] && echo "#$PR_NUMBER" || echo "Manual Run")
+        **Branch**: $BRANCH_NAME
+        **Architecture Doc**: \`SOFTWARE_ARCHITECTURE.md\`
+
+        ---
+
+        ## ❌ BLOCKING ISSUES
+
+        [List any critical discrepancies that must be fixed before merge]
+
+        ### Example: New Module Not Documented
+
+        **Issue**: New module `example_module` added but not documented in architecture
+
+        - **Location**: `src/aignostics/example_module/`
+        - **Missing from**: `SOFTWARE_ARCHITECTURE.md` Section 1.5
+        - **Current State**: Module exists with `_service.py`, `_cli.py`, `_gui.py`
+        - **Required Action**: Add module description to Section 1.5 "Layers and Modules"
+        - **Suggested Content**:
+          ```markdown
+          **Example Module (`example_module/`)**
+          - **Service**: [Brief description of what this module does]
+          - **CLI**: [Command-line operations provided]
+          - **GUI**: [GUI interface features]
+          - **Settings**: [Configuration options]
+          ```
+
+        ---
+
+        ## ⚠️ SUGGESTIONS
+
+        [List recommended but non-critical updates]
+
+        ### Example: Dependency Update
+
+        **Suggestion**: Update dependency list in Section 1.3
+
+        - **Change**: `pyproject.toml` shows new dependency `new-library==1.0.0`
+        - **Current Doc**: Section 1.3 "Language and Frameworks" doesn't mention this
+        - **Recommendation**: Add to "Key Dependencies" section
+        - **Priority**: Medium (nice-to-have for completeness)
+
+        ### Example: Diagram Update
+
+        **Suggestion**: Update architecture diagram
+
+        - **Change**: New integration with external service
+        - **Current Doc**: Diagram in Section 1.2 doesn't show this integration
+        - **Recommendation**: Add connection to "External Services" layer in Mermaid diagram
+        - **Priority**: Low (diagram still conceptually accurate)
+
+        ---
+
+        ## ✅ VALIDATED SUCCESSFULLY
+
+        ### Code Changes That Don't Require Doc Updates
+
+        - ✅ **Bug fix in `application/_service.py`** - Internal implementation detail, no architectural impact
+        - ✅ **Test updates** - Test coverage improvements don't affect architecture
+        - ✅ **Minor refactoring** - Code organization changes within existing patterns
+
+        ### Architecture Doc Accuracy
+
+        - ✅ **Module structure** - All existing modules properly documented
+        - ✅ **Layer separation** - Presentation/Domain/Platform layers correctly described
+        - ✅ **Design principles** - Section 2 accurately reflects implementation patterns
+
+        ---
+
+        ## 📊 Summary
+
+        - **Files Changed**: X
+        - **New Modules Added**: Y
+        - **Blocking Issues**: N
+        - **Suggestions**: M
+        - **Architecture Doc Status**: [Accurate / Needs Updates]
+
+        ---
+
+        ## 🎯 Action Required
+
+        **Before merging this PR:**
+
+        1. Update `SOFTWARE_ARCHITECTURE.md` Section X.Y with [specific changes]
+        2. Add Mermaid diagram update for [new component/integration]
+        3. Update dependency list in Section 1.3
+
+        **Commands to verify current structure:**
+
+        ```bash
+        # List all modules
+        find src/aignostics -maxdepth 1 -type d
+
+        # Check dependencies
+        cat pyproject.toml | grep -A 50 "dependencies ="
+
+        # View architecture doc sections
+        grep "^##" SOFTWARE_ARCHITECTURE.md
+        ```
+
+        ---
+
+        **Remember**: Architecture documentation is the blueprint for understanding and 
+        maintaining this codebase. Keeping it accurate helps onboarding, compliance, and 
+        long-term maintainability.
+
+        *Generated by Claude Code Architecture Validation*
+        EOF
+
+        # Post comment if this is a PR, otherwise just output to logs
+        if [ -n "$PR_NUMBER" ]; then
+          echo "Posting comment to PR #$PR_NUMBER"
+          gh pr comment "$PR_NUMBER" --body-file /tmp/architecture-validation.md
+        else
+          echo "Manual run - validation results:"
+          cat /tmp/architecture-validation.md
+        fi
+        ```
+
+        ## Validation Criteria
+
+        ### BLOCKING Issues (Must Fix):
+        - New modules not documented in Section 1.5
+        - Major architectural pattern changes not reflected in Section 1.2
+        - New external integrations missing from Section 3
+        - Significant dependency additions not listed in Section 1.3
+
+        ### SUGGESTIONS (Nice-to-Have):
+        - Diagram updates for new components
+        - Minor dependency additions
+        - Updated version numbers
+        - Enhanced descriptions for existing components
+        - Formatting improvements
+
+        ### VALIDATED (No Action Needed):
+        - Internal implementation changes within existing patterns
+        - Bug fixes that don't change architecture
+        - Test coverage improvements
+        - Documentation fixes in other files
+        - Minor refactoring within same module
+
+        ## Important Guidelines
+
+        1. **Understand the changes** - Read the actual PR diff thoroughly
+        2. **Read the architecture doc** - Don't assume what's documented
+        3. **Be practical** - Not every code change requires doc updates
+        4. **Be specific** - Provide exact sections and suggested content
+        5. **Be helpful** - Suggest actual text to add, not just "update section X"
+        6. **Check current state** - Verify modules exist before claiming they're undocumented
+
+        ## What to Look For
+
+        ### New Modules
+        - Any new directory under `src/aignostics/` with `_service.py`, `_cli.py`, or `_gui.py`
+        - Check if documented in Section 1.5 "Layers and Modules"
+
+        ### Dependency Changes
+        - New entries in `pyproject.toml` dependencies or optional-dependencies
+        - Check if major dependencies are listed in Section 1.3
+
+        ### CI/CD Changes
+        - New or modified workflows in `.github/workflows/`
+        - Check if Section 1.4 "Build Chain and CI/CD" is accurate
+
+        ### Integration Changes
+        - New external API integrations
+        - Check if documented in Section 3 "Integration Patterns"
+
+        ### Pattern Changes
+        - Changes to core patterns in `utils/` or base classes
+        - Check if Section 2 "Design Principles" needs updates
+
+        ---
+
+        **Focus**: Keep the architecture document as a living, accurate representation 
+        of the codebase structure and design decisions.
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      AIGNOSTICS_CLIENT_ID_DEVICE_STAGING: ${{ secrets.AIGNOSTICS_CLIENT_ID_DEVICE_STAGING }}
+      AIGNOSTICS_REFRESH_TOKEN_STAGING: ${{ secrets.AIGNOSTICS_REFRESH_TOKEN_STAGING }}
+      GCP_CREDENTIALS_STAGING: ${{ secrets.GCP_CREDENTIALS_STAGING }}
+      AIGNOSTICS_CLIENT_ID_DEVICE_PRODUCTION: ${{ secrets.AIGNOSTICS_CLIENT_ID_DEVICE_PRODUCTION }}
+      AIGNOSTICS_REFRESH_TOKEN_PRODUCTION: ${{ secrets.AIGNOSTICS_REFRESH_TOKEN_PRODUCTION }}
+      GCP_CREDENTIALS_PRODUCTION: ${{ secrets.GCP_CREDENTIALS_PRODUCTION }}