diff --git a/.github/CODEQL_SETUP.md b/.github/CODEQL_SETUP.md
new file mode 100644
index 0000000..f6aa7f3
--- /dev/null
+++ b/.github/CODEQL_SETUP.md
@@ -0,0 +1,134 @@
+# ⚠️ CRITICAL: CodeQL Setup Instructions
+
+## 🚨 ACTION REQUIRED - Repository Owner Must Complete This Step
+
+**The CodeQL workflow CANNOT run until you disable the default CodeQL setup.**
+
+### Current Error
+
+```
+Code Scanning could not process the submitted SARIF file:
+CodeQL analyses from advanced configurations cannot be processed 
+when the default setup is enabled
+```
+
+### What This Means
+
+Your repository has GitHub's **default CodeQL setup** enabled. This setting **completely blocks** any custom CodeQL workflows from working. The workflow configuration is correct, but GitHub will not process the results until you change this setting.
+
+---
+
+## 🔧 How to Fix (5 Minutes)
+
+### Step 1: Navigate to Code Scanning Settings
+
+1. Go to your repository on GitHub.com
+2. Click the **Settings** tab (top right)
+3. In the left sidebar, scroll down to **Security**
+4. Click **Code security and analysis**
+5. Scroll to the **Code scanning** section
+
+### Step 2: Disable Default Setup
+
+You'll see "CodeQL analysis" with a **"Default"** badge or label:
+
+1. Click the **"..."** menu (three dots) next to "CodeQL analysis"
+2. You'll see options:
+   - **"Switch to advanced"** (recommended) - Use this if you want to keep using CodeQL
+   - **"Disable CodeQL"** - Use this if you want to completely disable it
+
+3. Click **"Switch to advanced"**
+4. Confirm the action
+
+### Step 3: Verify It Works
+
+After switching to advanced:
+- The PR checks will automatically re-run
+- Or you can manually trigger them from the Actions tab
+- All three language analyses (Python, Swift, JavaScript/TypeScript) should complete successfully
+
+---
+
+## ✅ What Happens After You Fix This
+
+Once you complete the steps above:
+
+✅ **Python analysis** will scan your backend (`backend/`) and worker (`worker/`)  
+✅ **Swift analysis** will scan your iOS app and tests  
+✅ **JavaScript/TypeScript analysis** will scan your web frontend (`web/`)  
+✅ **Automated security scans** will run on every push and PR  
+✅ **Weekly security audits** will run automatically  
+
+---
+
+## 🤔 Why Can't Both Run?
+
+GitHub doesn't allow default and advanced (custom) CodeQL setups to run simultaneously because:
+- It would create duplicate analyses
+- Results would conflict
+- It would waste CI minutes
+
+You must choose one or the other.
+
+---
+
+## 📊 What You Get with This Custom Workflow
+
+The custom workflow (already configured) provides:
+
+### Advanced Query Suites
+- `security-extended` - Extended security vulnerability detection
+- `security-and-quality` - Code quality + security analysis
+
+### Multi-Language Coverage
+- **Python**: Backend API + background worker
+- **Swift**: iOS app + all test suites  
+- **JavaScript/TypeScript**: Next.js web frontend
+
+### Automated Triggers
+- Every push to `main` or `develop` branches
+- Every pull request
+- Weekly scheduled scans (Sunday midnight UTC)
+
+### Custom Build Configuration
+- Optimized Swift builds for CI
+- Generic simulator destination for compatibility
+- 360-minute timeout for complex builds
+
+---
+
+## ❓ Frequently Asked Questions
+
+### Q: Will this affect my repository's security?
+**A**: No! After switching, you'll have the same (or better) security coverage with the custom workflow.
+
+### Q: Can I switch back to default setup later?
+**A**: Yes, but you'll need to delete the custom workflow file first.
+
+### Q: What if I want to use the default setup instead?
+**A**: Delete the `.github/workflows/codeql.yml` file and keep the default setup enabled.
+
+### Q: How do I know if I've done it correctly?
+**A**: After switching to advanced, go to the Actions tab and look for the "CodeQL Analysis" workflow running. It should complete without the configuration error.
+
+### Q: Who can make this change?
+**A**: Only repository owners or administrators with "Write" or "Admin" permissions can change code scanning settings.
+
+---
+
+## 🆘 Still Having Issues?
+
+If you've completed the steps above and still see errors:
+
+1. **Check the Actions tab** for detailed error logs
+2. **Review** `.github/workflows/README.md` for troubleshooting
+3. **Verify** you have the correct permissions (Settings tab should be visible)
+4. **Wait** a few minutes after changing settings for GitHub to sync
+
+---
+
+## 📚 Additional Resources
+
+- [GitHub Code Scanning Documentation](https://docs.github.com/en/code-security/code-scanning)
+- [Switching to Advanced Setup](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository)
+- [CodeQL Action Documentation](https://github.com/github/codeql-action)
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
new file mode 100644
index 0000000..d4cf953
--- /dev/null
+++ b/.github/workflows/README.md
@@ -0,0 +1,68 @@
+# CodeQL Configuration
+
+This directory contains the CodeQL security scanning workflow for the Budget-AI project.
+
+## Workflow Overview
+
+The `codeql.yml` workflow performs automated security analysis on three languages:
+
+- **Python** - Backend API (`backend/`) and background worker (`worker/`)
+- **Swift** - iOS application (`BudgetAI/`, `BudgetAITests/`, `BudgetAIUITests/`, `testapp/`)
+- **JavaScript/TypeScript** - Next.js web frontend (`web/`)
+
+## Triggers
+
+- **Push/Pull Requests**: Runs on all pushes and PRs to `main` and `develop` branches
+- **Weekly Scan**: Scheduled to run every Sunday at midnight UTC
+
+## Query Suites
+
+The workflow uses two comprehensive query suites:
+- `security-extended` - Extended security queries
+- `security-and-quality` - Combined security and code quality checks
+
+## Important Setup Note
+
+⚠️ **GitHub Default CodeQL Setup Conflict**
+
+If you see errors like:
+```
+CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled
+```
+
+This means the repository has GitHub's default CodeQL setup enabled. To use this custom workflow:
+
+1. Go to repository **Settings** → **Security** → **Code scanning**
+2. Find "CodeQL analysis" with "Default" label
+3. Click the **"..."** menu → **"Disable CodeQL"** or **"Switch to advanced"**
+4. The custom workflow will then work without conflicts
+
+## Build Configuration
+
+- **Python & JavaScript/TypeScript**: No build required (interpreted languages)
+- **Swift**: Manual build using `xcodebuild` with:
+  - Generic iOS Simulator destination for compatibility
+  - Code signing disabled (`CODE_SIGNING_ALLOWED=NO`)
+  - 360-minute timeout to accommodate build time
+
+## Benefits
+
+✅ Comprehensive multi-language security scanning  
+✅ Detects vulnerabilities across entire codebase  
+✅ Automated weekly security audits  
+✅ Runs on every code change  
+✅ Uses advanced security query suites  
+
+## Troubleshooting
+
+### Swift Build Timeout
+If the Swift build times out, consider:
+- Using a faster macOS runner
+- Reducing the scope of files to analyze
+- Caching build dependencies
+
+### Analysis Failures
+Check the Actions tab for detailed logs. Common issues:
+- Build errors in Swift code
+- Syntax errors in source files
+- Configuration conflicts with default setup
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..d7fb9db
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,76 @@
+# ⚠️ CRITICAL: This workflow CANNOT run until default CodeQL setup is disabled
+# 
+# ERROR: "CodeQL analyses from advanced configurations cannot be processed 
+#         when the default setup is enabled"
+#
+# REQUIRED ACTION (Repository Owner):
+# 1. Go to: Settings → Security → Code security and analysis
+# 2. Find "CodeQL analysis" with "Default" label
+# 3. Click "..." menu → "Switch to advanced"
+# 4. See .github/CODEQL_SETUP.md for detailed instructions
+#
+# This workflow is correctly configured but GitHub blocks it when default 
+# setup is enabled. This is a repository setting that must be changed.
+
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sundays at midnight UTC
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: ${{ matrix.timeout }}
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Python analysis for backend and worker
+          - language: python
+            os: ubuntu-latest
+            timeout: 360
+            build-mode: none
+          # Swift analysis for iOS app
+          - language: swift
+            os: macos-latest
+            timeout: 360
+            build-mode: manual
+          # JavaScript/TypeScript analysis for web frontend
+          - language: javascript-typescript
+            os: ubuntu-latest
+            timeout: 360
+            build-mode: none
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        queries: security-extended,security-and-quality
+
+    # For Swift, we need to build the project
+    - name: Build Swift project
+      if: matrix.language == 'swift'
+      run: |
+        xcodebuild -project BudgetAI.xcodeproj -scheme BudgetAI -destination 'generic/platform=iOS Simulator' clean build CODE_SIGNING_ALLOWED=NO
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"
diff --git a/CODEQL_ACTION_REQUIRED.md b/CODEQL_ACTION_REQUIRED.md
new file mode 100644
index 0000000..6627baa
--- /dev/null
+++ b/CODEQL_ACTION_REQUIRED.md
@@ -0,0 +1,51 @@
+# ⚠️ ATTENTION: CodeQL Workflow Requires Your Action
+
+## The Error You're Seeing
+
+```
+CodeQL analyses from advanced configurations cannot be processed 
+when the default setup is enabled
+```
+
+## What This Means
+
+**YOU** (the repository owner) need to change a setting in your repository. I cannot do this for you because it's a repository configuration, not code.
+
+## How to Fix (2 Minutes)
+
+### Option 1: Use the Custom Workflow (Recommended)
+
+1. Open your repository on GitHub.com
+2. Click **Settings** → **Security** → **Code security and analysis**
+3. Find "CodeQL analysis" with a **"Default"** label
+4. Click the **"..."** menu → **"Switch to advanced"**
+5. Done! The workflow will now work.
+
+📖 **See `.github/CODEQL_SETUP.md` for detailed step-by-step instructions**
+
+### Option 2: Use GitHub's Default Setup
+
+If you don't want the custom workflow:
+1. Delete `.github/workflows/codeql.yml`
+2. Keep the default setup enabled
+3. Done!
+
+## Why This Happens
+
+- GitHub doesn't allow **both** default setup **and** custom workflows
+- You must choose one or the other
+- This is intentional to avoid duplicate analyses
+
+## Current Status
+
+| Item | Status |
+|------|--------|
+| Workflow code | ✅ Correct and ready |
+| Configuration | ✅ Valid |
+| **Your action needed** | ❌ **Repository setting** |
+
+**The workflow is perfectly configured. It just can't run until you change the repository setting.**
+
+---
+
+**Questions?** Read `.github/CODEQL_SETUP.md` or check the PR description for more details.