fix tax log

- Replace local backend.log reading with Superset API /log/ fetch
- Update DashboardValidationPlugin to use SupersetClient
- Filter logs by dashboard_id and last 24 hours
- Update spec FR-006 to reflect API usage

.gitignore

@@ -10,8 +10,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
 parts/
 sdist/
 var/
@@ -59,9 +57,14 @@ Thumbs.db
 *.ps1
 keyring passwords.py
 *github*
-*git*
+
 *tech_spec*
 dashboards
 backend/mappings.db
 
 
+backend/tasks.db
+backend/logs
+backend/auth.db
+semantics/reports
+backend/tasks.db

.kilocode/rules/specify-rules.md

@@ -22,6 +22,19 @@ Auto-generated from all feature plans. Last updated: 2025-12-19
 - SQLite (for job history/results, connection configs), Filesystem (for temporary file uploads) (010-refactor-cli-to-web)
 - Python 3.9+ + FastAPI, Pydantic, requests, pyyaml (migrated from superset_tool) (012-remove-superset-tool)
 - SQLite (tasks.db, migrations.db), Filesystem (012-remove-superset-tool)
+- Filesystem (local git repo), SQLite (for GitServerConfig, Environment) (011-git-integration-dashboard)
+- Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API (011-git-integration-dashboard)
+- SQLite (for config/history), Filesystem (local Git repositories) (011-git-integration-dashboard)
+- Node.js 18+ (Frontend Build), Svelte 5.x + SvelteKit, Tailwind CSS, `date-fns` (existing) (013-unify-frontend-css)
+- LocalStorage (for language preference) (013-unify-frontend-css)
+- Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI (Backend), SvelteKit (Frontend) (014-file-storage-ui)
+- Local Filesystem (for artifacts), Config (for storage path) (014-file-storage-ui)
+- Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI (Backend), SvelteKit + Tailwind CSS (Frontend) (015-frontend-nav-redesign)
+- N/A (UI reorganization and API integration) (015-frontend-nav-redesign)
+- SQLite (`auth.db`) for Users, Roles, Permissions, and Mappings. (016-multi-user-auth)
+- SQLite (existing `tasks.db` for results, `auth.db` for permissions, `mappings.db` or new `plugins.db` for provider config/metadata) (017-llm-analysis-plugin)
+- Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing) (019-superset-ux-redesign)
+- SQLite (tasks.db, auth.db, migrations.db) - no new database tables required (019-superset-ux-redesign)
 
 - Python 3.9+ (Backend), Node.js 18+ (Frontend Build) (001-plugin-arch-svelte-ui)
 
@@ -42,9 +55,9 @@ cd src; pytest; ruff check .
 Python 3.9+ (Backend), Node.js 18+ (Frontend Build): Follow standard conventions
 
 ## Recent Changes
-- 012-remove-superset-tool: Added Python 3.9+ + FastAPI, Pydantic, requests, pyyaml (migrated from superset_tool)
+- 019-superset-ux-redesign: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy, WebSocket (existing)
-- 010-refactor-cli-to-web: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, Tailwind CSS, Pydantic, SQLAlchemy, `superset_tool` (internal lib)
+- 017-llm-analysis-plugin: Added Python 3.9+ (Backend), Node.js 18+ (Frontend)
-- 009-backup-scheduler: Added Python 3.9+, Node.js 18+ + FastAPI, APScheduler, SQLAlchemy, SvelteKit, Tailwind CSS
+- 016-multi-user-auth: Added Python 3.9+ (Backend), Node.js 18+ (Frontend)
 
 
 <!-- MANUAL ADDITIONS START -->

.kilocode/workflows/read_semantic.md

@@ -0,0 +1,4 @@
+---
+description: USE SEMANTIC
+---
+Прочитай semantic_protocol.md. ОБЯЗАТЕЛЬНО используй его при разработке

.kilocode/workflows/speckit.analyze.md

@@ -63,6 +63,7 @@ Load only the minimal necessary context from each artifact:
 **From constitution:**
 
 - Load `.specify/memory/constitution.md` for principle validation
+- Load `semantic_protocol.md` for technical standard validation
 
 ### 3. Build Semantic Models
 

.kilocode/workflows/speckit.fix.md

@@ -0,0 +1,199 @@
+---
+
+description: Fix failing tests and implementation issues based on test reports
+
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Analyze test failure reports, identify root causes, and fix implementation issues while preserving semantic protocol compliance.
+
+## Operating Constraints
+
+1. **USE CODER MODE**: Always switch to `coder` mode for code fixes
+2. **SEMANTIC PROTOCOL**: Never remove semantic annotations ([DEF], @TAGS). Only update code logic.
+3. **TEST DATA**: If tests use @TEST_DATA fixtures, preserve them when fixing
+4. **NO DELETION**: Never delete existing tests or semantic annotations
+5. **REPORT FIRST**: Always write a fix report before making changes
+
+## Execution Steps
+
+### 1. Load Test Report
+
+**Required**: Test report file path (e.g., `specs/<feature>/tests/reports/2026-02-19-report.md`)
+
+**Parse the report for**:
+- Failed test cases
+- Error messages
+- Stack traces
+- Expected vs actual behavior
+- Affected modules/files
+
+### 2. Analyze Root Causes
+
+For each failed test:
+
+1. **Read the test file** to understand what it's testing
+2. **Read the implementation file** to find the bug
+3. **Check semantic protocol compliance**:
+   - Does the implementation have correct [DEF] anchors?
+   - Are @TAGS (@PRE, @POST, @UX_STATE, etc.) present?
+   - Does the code match the TIER requirements?
+4. **Identify the fix**:
+   - Logic error in implementation
+   - Missing error handling
+   - Incorrect API usage
+   - State management issue
+
+### 3. Write Fix Report
+
+Create a structured fix report:
+
+```markdown
+# Fix Report: [FEATURE]
+
+**Date**: [YYYY-MM-DD]
+**Report**: [Test Report Path]
+**Fixer**: Coder Agent
+
+## Summary
+
+- Total Failed Tests: [X]
+- Total Fixed: [X]
+- Total Skipped: [X]
+
+## Failed Tests Analysis
+
+### Test: [Test Name]
+
+**File**: `path/to/test.py`
+**Error**: [Error message]
+
+**Root Cause**: [Explanation of why test failed]
+
+**Fix Required**: [Description of fix]
+
+**Status**: [Pending/In Progress/Completed]
+
+## Fixes Applied
+
+### Fix 1: [Description]
+
+**Affected File**: `path/to/file.py`
+**Test Affected**: `[Test Name]`
+
+**Changes**:
+```diff
+<<<<<<< SEARCH
+[Original Code]
+=======
+[Fixed Code]
+>>>>>>> REPLACE
+```
+
+**Verification**: [How to verify fix works]
+
+**Semantic Integrity**: [Confirmed annotations preserved]
+
+## Next Steps
+
+- [ ] Run tests to verify fix: `cd backend && .venv/bin/python3 -m pytest`
+- [ ] Check for related failing tests
+- [ ] Update test documentation if needed
+```
+
+### 4. Apply Fixes (in Coder Mode)
+
+Switch to `coder` mode and apply fixes:
+
+1. **Read the implementation file** to get exact content
+2. **Apply the fix** using apply_diff
+3. **Preserve all semantic annotations**:
+   - Keep [DEF:...] and [/DEF:...] anchors
+   - Keep all @TAGS (@PURPOSE, @LAYER, @TIER, @RELATION, @PRE, @POST, @UX_STATE, @UX_FEEDBACK, @UX_RECOVERY)
+4. **Only update code logic** to fix the bug
+5. **Run tests** to verify the fix
+
+### 5. Verification
+
+After applying fixes:
+
+1. **Run tests**:
+   ```bash
+   cd backend && .venv/bin/python3 -m pytest -v
+   ```
+   or
+   ```bash
+   cd frontend && npm run test
+   ```
+
+2. **Check test results**:
+   - Failed tests should now pass
+   - No new tests should fail
+   - Coverage should not decrease
+
+3. **Update fix report** with results:
+   - Mark fixes as completed
+   - Add verification steps
+   - Note any remaining issues
+
+## Output
+
+Generate final fix report:
+
+```markdown
+# Fix Report: [FEATURE] - COMPLETED
+
+**Date**: [YYYY-MM-DD]
+**Report**: [Test Report Path]
+**Fixer**: Coder Agent
+
+## Summary
+
+- Total Failed Tests: [X]
+- Total Fixed: [X] ✅
+- Total Skipped: [X]
+
+## Fixes Applied
+
+### Fix 1: [Description] ✅
+
+**Affected File**: `path/to/file.py`
+**Test Affected**: `[Test Name]`
+
+**Changes**: [Summary of changes]
+
+**Verification**: All tests pass ✅
+
+**Semantic Integrity**: Preserved ✅
+
+## Test Results
+
+```
+[Full test output showing all passing tests]
+```
+
+## Recommendations
+
+- [ ] Monitor for similar issues
+- [ ] Update documentation if needed
+- [ ] Consider adding more tests for edge cases
+
+## Related Files
+
+- Test Report: [path]
+- Implementation: [path]
+- Test File: [path]
+```
+
+## Context for Fixing
+
+$ARGUMENTS

.kilocode/workflows/speckit.implement.md

@@ -1,5 +1,10 @@
 ---
 description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+handoffs: 
+  - label: Verify Changes
+    agent: speckit.test
+    prompt: Verify the implementation of...
+    send: true
 ---
 
 ## User Input
@@ -46,6 +51,7 @@ You **MUST** consider the user input before proceeding (if not empty).
      - Automatically proceed to step 3
 
 3. Load and analyze the implementation context:
+   - **REQUIRED**: Read `semantic_protocol.md` for strict coding standards and contract requirements
    - **REQUIRED**: Read tasks.md for the complete task list and execution plan
    - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
    - **IF EXISTS**: Read data-model.md for entities and relationships
@@ -111,6 +117,8 @@ You **MUST** consider the user input before proceeding (if not empty).
    - **Validation checkpoints**: Verify each phase completion before proceeding
 
 7. Implementation execution rules:
+   - **Strict Adherence**: Apply `semantic_protocol.md` rules - every file must start with [DEF] header, include @TIER, and define contracts.
+   - **CRITICAL Contracts**: If a task description contains a contract summary (e.g., `CRITICAL: PRE: ..., POST: ...`), these constraints are **MANDATORY** and must be strictly implemented in the code using guards/assertions (if applicable per protocol).
    - **Setup first**: Initialize project structure, dependencies, configuration
    - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
    - **Core development**: Implement models, services, CLI commands, endpoints

.kilocode/workflows/speckit.plan.md

@@ -22,7 +22,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
-2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+2. **Load context**: Read FEATURE_SPEC, `ux_reference.md`, `semantic_protocol.md` and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
 
 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
    - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
@@ -64,17 +64,32 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 **Prerequisites:** `research.md` complete
 
+0. **Validate Design against UX Reference**:
+   - Check if the proposed architecture supports the latency, interactivity, and flow defined in `ux_reference.md`.
+   - **Linkage**: Ensure key UI states from `ux_reference.md` map to Component Contracts (`@UX_STATE`).
+   - **CRITICAL**: If the technical plan compromises the UX (e.g. "We can't do real-time validation"), you **MUST STOP** and warn the user.
+
 1. **Extract entities from feature spec** → `data-model.md`:
-   - Entity name, fields, relationships
+   - Entity name, fields, relationships, validation rules.
-   - Validation rules from requirements
-   - State transitions if applicable
 
-2. **Generate API contracts** from functional requirements:
+2. **Design & Verify Contracts (Semantic Protocol)**:
-   - For each user action → endpoint
+   - **Drafting**: Define [DEF] Headers and Contracts for all new modules based on `semantic_protocol.md`.
-   - Use standard REST/GraphQL patterns
+   - **TIER Classification**: Explicitly assign `@TIER: [CRITICAL|STANDARD|TRIVIAL]` to each module.
-   - Output OpenAPI/GraphQL schema to `/contracts/`
+   - **CRITICAL Requirements**: For all CRITICAL modules, define full `@PRE`, `@POST`, and (if UI) `@UX_STATE` contracts.
+   - **Self-Review**:
+     - *Completeness*: Do `@PRE`/`@POST` cover edge cases identified in Research?
+     - *Connectivity*: Do `@RELATION` tags form a coherent graph?
+     - *Compliance*: Does syntax match `[DEF:id:Type]` exactly?
+   - **Output**: Write verified contracts to `contracts/modules.md`.
 
-3. **Agent context update**:
+3. **Simulate Contract Usage**:
+   - Trace one key user scenario through the defined contracts to ensure data flow continuity.
+   - If a contract interface mismatch is found, fix it immediately.
+
+4. **Generate API contracts**:
+   - Output OpenAPI/GraphQL schema to `/contracts/` for backend-frontend sync.
+
+5. **Agent context update**:
    - Run `.specify/scripts/bash/update-agent-context.sh kilocode`
    - These scripts detect which AI agent is in use
    - Update the appropriate agent-specific context file

.kilocode/workflows/speckit.specify.md

@@ -70,7 +70,22 @@ Given that feature description, do this:
 
 3. Load `.specify/templates/spec-template.md` to understand required sections.
 
-4. Follow this execution flow:
+4. **Generate UX Reference**:
+   
+   a. Load `.specify/templates/ux-reference-template.md`.
+   
+   b. **Design the User Experience**:
+      - **Imagine you are the user**: Visualize the interface and interaction.
+      - **Persona**: Define who is using this.
+      - **Happy Path**: Write the story of the perfect interaction.
+      - **Mockups**: Create concrete CLI text blocks or UI descriptions.
+      - **Errors**: Define how the system guides the user out of failure.
+   
+   c. Write the `ux_reference.md` file in the feature directory.
+   
+   d. **CRITICAL**: This UX Reference is now the source of truth for the "feel" of the feature. The technical spec MUST support this experience.
+
+5. Follow this execution flow:
 
     1. Parse user description from Input
        If empty: ERROR "No feature description provided"
@@ -116,6 +131,12 @@ Given that feature description, do this:
       - [ ] Written for non-technical stakeholders
       - [ ] All mandatory sections completed
 
+      ## UX Consistency
+      
+      - [ ] Functional requirements fully support the 'Happy Path' in ux_reference.md
+      - [ ] Error handling requirements match the 'Error Experience' in ux_reference.md
+      - [ ] No requirements contradict the defined User Persona or Context
+      
       ## Requirement Completeness
       
       - [ ] No [NEEDS CLARIFICATION] markers remain
@@ -190,7 +211,7 @@ Given that feature description, do this:
 
    d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
 
-7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+7. Report completion with branch name, spec file path, ux_reference file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
 
 **NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
 

.kilocode/workflows/speckit.tasks.md

@@ -24,7 +24,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
 2. **Load design documents**: Read from FEATURE_DIR:
-   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities), ux_reference.md (experience source of truth)
    - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
    - Note: Not all projects have all documents. Generate tasks based on what's available.
 
@@ -70,6 +70,12 @@ The tasks.md should be immediately executable - each task must be specific enoug
 
 **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
 
+### UX Preservation (CRITICAL)
+
+- **Source of Truth**: `ux_reference.md` is the absolute standard for the "feel" of the feature.
+- **Violation Warning**: If any task would inherently violate the UX (e.g. "Remove progress bar to simplify code"), you **MUST** flag this to the user immediately.
+- **Verification Task**: You **MUST** add a specific task at the end of each User Story phase: `- [ ] Txxx [USx] Verify implementation matches ux_reference.md (Happy Path & Errors)`
+
 ### Checklist Format (REQUIRED)
 
 Every task MUST strictly follow this format:
@@ -113,7 +119,10 @@ Every task MUST strictly follow this format:
      - If tests requested: Tests specific to that story
    - Mark story dependencies (most stories should be independent)
 
-2. **From Contracts**:
+2. **From Contracts (CRITICAL TIER)**:
+   - Identify components marked as `@TIER: CRITICAL` in `contracts/modules.md`.
+   - For these components, **MUST** append the summary of `@PRE`, `@POST`, and `@UX_STATE` contracts directly to the task description.
+   - Example: `- [ ] T005 [P] [US1] Implement Auth (CRITICAL: PRE: token exists, POST: returns User) in src/auth.py`
    - Map each contract/endpoint → to the user story it serves
    - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
 

.kilocode/workflows/speckit.test.md

@@ -0,0 +1,178 @@
+---
+
+description: Generate tests, manage test documentation, and ensure maximum code coverage
+
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Execute full testing cycle: analyze code for testable modules, write tests with proper coverage, maintain test documentation, and ensure no test duplication or deletion.
+
+## Operating Constraints
+
+1. **NEVER delete existing tests** - Only update if they fail due to bugs in the test or implementation
+2. **NEVER duplicate tests** - Check existing tests first before creating new ones
+3. **Use TEST_DATA fixtures** - For CRITICAL tier modules, read @TEST_DATA from semantic_protocol.md
+4. **Co-location required** - Write tests in `__tests__` directories relative to the code being tested
+
+## Execution Steps
+
+### 1. Analyze Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS.
+
+Determine:
+- FEATURE_DIR - where the feature is located
+- TASKS_FILE - path to tasks.md
+- Which modules need testing based on task status
+
+### 2. Load Relevant Artifacts
+
+**From tasks.md:**
+- Identify completed implementation tasks (not test tasks)
+- Extract file paths that need tests
+
+**From semantic_protocol.md:**
+- Read @TIER annotations for modules
+- For CRITICAL modules: Read @TEST_DATA fixtures
+
+**From existing tests:**
+- Scan `__tests__` directories for existing tests
+- Identify test patterns and coverage gaps
+
+### 3. Test Coverage Analysis
+
+Create coverage matrix:
+
+| Module | File | Has Tests | TIER | TEST_DATA Available |
+|--------|------|-----------|------|-------------------|
+| ... | ... | ... | ... | ... |
+
+### 4. Write Tests (TDD Approach)
+
+For each module requiring tests:
+
+1. **Check existing tests**: Scan `__tests__/` for duplicates
+2. **Read TEST_DATA**: If CRITICAL tier, read @TEST_DATA from semantic_protocol.md
+3. **Write test**: Follow co-location strategy
+   - Python: `src/module/__tests__/test_module.py`
+   - Svelte: `src/lib/components/__tests__/test_component.test.js`
+4. **Use mocks**: Use `unittest.mock.MagicMock` for external dependencies
+
+### 4a. UX Contract Testing (Frontend Components)
+
+For Svelte components with `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY` tags:
+
+1. **Parse UX tags**: Read component file and extract all `@UX_*` annotations
+2. **Generate UX tests**: Create tests for each UX state transition
+   ```javascript
+   // Example: Testing @UX_STATE: Idle -> Expanded
+   it('should transition from Idle to Expanded on toggle click', async () => {
+     render(Sidebar);
+     const toggleBtn = screen.getByRole('button', { name: /toggle/i });
+     await fireEvent.click(toggleBtn);
+     expect(screen.getByTestId('sidebar')).toHaveClass('expanded');
+   });
+   ```
+3. **Test @UX_FEEDBACK**: Verify visual feedback (toast, shake, color changes)
+4. **Test @UX_RECOVERY**: Verify error recovery mechanisms (retry, clear input)
+5. **Use @UX_TEST fixtures**: If component has `@UX_TEST` tags, use them as test specifications
+
+**UX Test Template:**
+```javascript
+// [DEF:__tests__/test_Component:Module]
+// @RELATION: VERIFIES -> ../Component.svelte
+// @PURPOSE: Test UX states and transitions
+
+describe('Component UX States', () => {
+  // @UX_STATE: Idle -> {action: click, expected: Active}
+  it('should transition Idle -> Active on click', async () => { ... });
+  
+  // @UX_FEEDBACK: Toast on success
+  it('should show toast on successful action', async () => { ... });
+  
+  // @UX_RECOVERY: Retry on error
+  it('should allow retry on error', async () => { ... });
+});
+```
+
+### 5. Test Documentation
+
+Create/update documentation in `specs/<feature>/tests/`:
+
+```
+tests/
+├── README.md           # Test strategy and overview
+├── coverage.md         # Coverage matrix and reports
+└── reports/
+    └── YYYY-MM-DD-report.md
+```
+
+### 6. Execute Tests
+
+Run tests and report results:
+
+**Backend:**
+```bash
+cd backend && .venv/bin/python3 -m pytest -v
+```
+
+**Frontend:**
+```bash
+cd frontend && npm run test
+```
+
+### 7. Update Tasks
+
+Mark test tasks as completed in tasks.md with:
+- Test file path
+- Coverage achieved
+- Any issues found
+
+## Output
+
+Generate test execution report:
+
+```markdown
+# Test Report: [FEATURE]
+
+**Date**: [YYYY-MM-DD]
+**Executed by**: Tester Agent
+
+## Coverage Summary
+
+| Module | Tests | Coverage % |
+|--------|-------|------------|
+| ... | ... | ... |
+
+## Test Results
+
+- Total: [X]
+- Passed: [X]
+- Failed: [X]
+- Skipped: [X]
+
+## Issues Found
+
+| Test | Error | Resolution |
+|------|-------|------------|
+| ... | ... | ... |
+
+## Next Steps
+
+- [ ] Fix failed tests
+- [ ] Add more coverage for [module]
+- [ ] Review TEST_DATA fixtures
+```
+
+## Context for Testing
+
+$ARGUMENTS

.kilocodemodes

@@ -1,32 +1,31 @@
 customModes:
   - slug: tester
     name: Tester
-    description: QA and Plan Verification Specialist
+    description: QA and Test Engineer - Full Testing Cycle
     roleDefinition: |-
-      You are Kilo Code, acting as a QA and Verification Specialist. Your primary goal is to validate that the project implementation aligns strictly with the defined specifications and task plans.
+      You are Kilo Code, acting as a QA and Test Engineer. Your primary goal is to ensure maximum test coverage, maintain test quality, and preserve existing tests.
-      Your responsibilities include: - Reading and analyzing task plans and specifications (typically in the `specs/` directory). - Verifying that implemented code matches the requirements. - Executing tests and validating system behavior via CLI or Browser. - Updating the status of tasks in the plan files (e.g., marking checkboxes [x]) as they are verified. - Identifying and reporting missing features or bugs.
+      Your responsibilities include:
-    whenToUse: Use this mode when you need to audit the progress of a project, verify completed tasks against the plan, run quality assurance checks, or update the status of task lists in specification documents.
+      - WRITING TESTS: Create comprehensive unit tests following TDD principles, using co-location strategy (`__tests__` directories).
+      - TEST DATA: For CRITICAL tier modules, you MUST use @TEST_DATA fixtures defined in semantic_protocol.md. Read and apply them in your tests.
+      - DOCUMENTATION: Maintain test documentation in `specs/<feature>/tests/` directory with coverage reports and test case specifications.
+      - VERIFICATION: Run tests, analyze results, and ensure all tests pass.
+      - PROTECTION: NEVER delete existing tests. NEVER duplicate tests - check for existing tests first.
+    whenToUse: Use this mode when you need to write tests, run test coverage analysis, or perform quality assurance with full testing cycle.
     groups:
       - read
       - edit
       - command
       - browser
       - mcp
-    customInstructions: 1. Always begin by loading the relevant plan or task list from the `specs/` directory. 2. Do not assume a task is done just because it is checked; verify the code or functionality first if asked to audit. 3. When updating task lists, ensure you only mark items as complete if you have verified them.
+    customInstructions: |
-  - slug: product-manager
+      1. CO-LOCATION: Write tests in `__tests__` subdirectories relative to the code being tested (Fractal Strategy).
-    name: Product Manager
+      2. TEST DATA MANDATORY: For CRITICAL modules, read @TEST_DATA from semantic_protocol.md and use fixtures in tests.
-    description: Executes SpecKit workflows for feature management
+      3. UX CONTRACT TESTING: For Svelte components with @UX_STATE, @UX_FEEDBACK, @UX_RECOVERY tags, create comprehensive UX tests.
-    roleDefinition: |-
+      4. NO DELETION: Never delete existing tests - only update if they fail due to legitimate bugs.
-      You are Kilo Code, acting as a Product Manager. Your purpose is to rigorously execute the workflows defined in `.kilocode/workflows/`.
+      5. NO DUPLICATION: Check existing tests in `__tests__/` before creating new ones. Reuse existing test patterns.
-      You act as the orchestrator for: - Specification (`speckit.specify`, `speckit.clarify`) - Planning (`speckit.plan`) - Task Management (`speckit.tasks`, `speckit.taskstoissues`) - Quality Assurance (`speckit.analyze`, `speckit.checklist`) - Governance (`speckit.constitution`) - Implementation Oversight (`speckit.implement`)
+      6. DOCUMENTATION: Create test reports in `specs/<feature>/tests/reports/YYYY-MM-DD-report.md`.
-      For each task, you must read the relevant workflow file from `.kilocode/workflows/` and follow its Execution Steps precisely.
+      7. COVERAGE: Aim for maximum coverage but prioritize CRITICAL and STANDARD tier modules.
-    whenToUse: Use this mode when you need to run any /speckit.* command or when dealing with high-level feature planning, specification writing, or project management tasks.
+      8. RUN TESTS: Execute tests using `cd backend && .venv/bin/python3 -m pytest` or `cd frontend && npm run test`.
-    groups:
-      - read
-      - edit
-      - command
-      - mcp
-    customInstructions: 1. Always read the specific workflow file in `.kilocode/workflows/` before executing a command. 2. Adhere strictly to the "Operating Constraints" and "Execution Steps" in the workflow files.
   - slug: semantic
     name: Semantic Agent
     roleDefinition: |-
@@ -43,3 +42,41 @@ customModes:
       - browser
       - mcp
     source: project
+  - slug: product-manager
+    name: Product Manager
+    roleDefinition: |-
+      Your purpose is to rigorously execute the workflows defined in `.kilocode/workflows/`.
+      You act as the orchestrator for: - Specification (`speckit.specify`, `speckit.clarify`) - Planning (`speckit.plan`) - Task Management (`speckit.tasks`, `speckit.taskstoissues`) - Quality Assurance (`speckit.analyze`, `speckit.checklist`, `speckit.test`, `speckit.fix`) - Governance (`speckit.constitution`) - Implementation Oversight (`speckit.implement`)
+      For each task, you must read the relevant workflow file from `.kilocode/workflows/` and follow its Execution Steps precisely.
+    whenToUse: Use this mode when you need to run any /speckit.* command or when dealing with high-level feature planning, specification writing, or project management tasks.
+    description: Executes SpecKit workflows for feature management
+    customInstructions: 1. Always read the specific workflow file in `.kilocode/workflows/` before executing a command. 2. Adhere strictly to the "Operating Constraints" and "Execution Steps" in the workflow files.
+    groups:
+      - read
+      - edit
+      - command
+      - mcp
+    source: project
+  - slug: coder
+    name: Coder
+    roleDefinition: You are Kilo Code, acting as an Implementation Specialist. Your primary goal is to write code that strictly follows the Semantic Protocol defined in `semantic_protocol.md`.
+    whenToUse: Use this mode when you need to implement features, write code, or fix issues based on test reports.
+    description: Implementation Specialist - Semantic Protocol Compliant
+    customInstructions: |
+      1. SEMANTIC PROTOCOL: ALWAYS use semantic_protocol.md as your single source of truth.
+      2. ANCHOR FORMAT: Use #[DEF:filename:Type] at start and #[/DEF:filename] at end.
+      3. TAGS: Add @PURPOSE, @LAYER, @TIER, @RELATION, @PRE, @POST, @UX_STATE, @UX_FEEDBACK, @UX_RECOVERY.
+      4. TIER COMPLIANCE:
+        - CRITICAL: Full contract + all UX tags + strict logging
+        - STANDARD: Basic contract + UX tags where applicable
+        - TRIVIAL: Only anchors + @PURPOSE
+      5. CODE SIZE: Keep modules under 300 lines. Refactor if exceeding.
+      6. ERROR HANDLING: Use if/raise or guards, never assert.
+      7. TEST FIXES: When fixing failing tests, preserve semantic annotations. Only update code logic.
+      8. RUN TESTS: After fixes, run tests to verify: `cd backend && .venv/bin/python3 -m pytest` or `cd frontend && npm run test`.
+    groups:
+      - read
+      - edit
+      - command
+      - mcp
+    source: project

.specify/memory/constitution.md

@@ -1,11 +1,11 @@
 <!--
 SYNC IMPACT REPORT
-Version: 1.7.1 (Simplified Workflow)
+Version: 2.3.0 (Tailwind CSS & Scoped CSS Minimization)
 Changes:
-- Simplified Generation Workflow to a single phase: Code Generation from `tasks.md`.
+- Updated Principle III: Added mandatory requirement for Tailwind CSS usage and minimization of scoped `<style>` blocks in Svelte components.
-- Removed multi-phase Architecture/Implementation split to streamline development.
+- Version bump: 2.2.0 -> 2.3.0 (Minor: New material guidance added).
 Templates Status:
-- .specify/templates/plan-template.md: ✅ Aligned (Dynamic check).
+- .specify/templates/plan-template.md: ✅ Aligned.
 - .specify/templates/spec-template.md: ✅ Aligned.
 - .specify/templates/tasks-template.md: ✅ Aligned.
 -->
@@ -14,54 +14,43 @@ Templates Status:
 ## Core Principles
 
 ### I. Semantic Protocol Compliance
-The file `semantic_protocol.md` is the **authoritative technical standard** for this project. All code generation, refactoring, and architecture must strictly adhere to the standards, syntax, and workflows defined therein.
+The file `semantic_protocol.md` is the **sole and authoritative technical standard** for this project.
-- **Syntax**: `[DEF]` anchors, `@RELATION` tags, and metadata must match the Protocol specification.
+- **Law**: All code must adhere to the Axioms (Meaning First, Contract First, etc.) defined in the Protocol.
-- **Structure**: File layouts and headers must follow the "File Structure Standard".
+- **Syntax & Structure**: Anchors (`[DEF]`), Tags (`@KEY`), and File Structures must strictly match the Protocol.
-- **Workflow**: The technical steps for generating code must align with the Protocol.
+- **Compliance**: Any deviation from `semantic_protocol.md` constitutes a build failure.
 
-### II. Causal Validity (Contracts First)
+### II. Everything is a Plugin & Centralized Config
-As defined in the Protocol, Semantic definitions (Contracts) must ALWAYS precede implementation code. Logic is downstream of definition. We define the structure and constraints (`[DEF]`, `@PRE`, `@POST`) before writing the executable logic.
+All functional extensions, tools, or major features must be implemented as modular Plugins inheriting from `PluginBase`.
+- **Modularity**: Logic should not reside in standalone services or scripts unless strictly necessary for core infrastructure. This ensures a unified execution model via the `TaskManager`.
+- **Configuration Discipline**: All configuration access (environments, settings, paths) MUST use the `ConfigManager`. In the backend, the singleton instance MUST be obtained via dependency injection (`get_config_manager()`). Hardcoding environment IDs (e.g., "1") or paths is STRICTLY FORBIDDEN.
 
-### III. Immutability of Architecture
+### III. Unified Frontend Experience
-Architectural decisions in the Module Header (`@LAYER`, `@INVARIANT`, `@CONSTRAINT`) are treated as immutable constraints. Changes to these require an explicit refactoring step, not ad-hoc modification during implementation.
+To ensure a consistent and accessible user experience, all frontend implementations must strictly adhere to the unified design and localization standards.
+- **Component Reusability**: All UI elements MUST utilize the standardized Svelte component library (`src/lib/ui`) and centralized design tokens.
+- **Tailwind CSS First**: All styling MUST be implemented using Tailwind CSS utility classes. The use of scoped `<style>` blocks in Svelte components MUST be minimized and reserved only for complex animations or third-party overrides that cannot be achieved via Tailwind.
+- **Internationalization (i18n)**: All user-facing text MUST be extracted to the translation system (`src/lib/i18n`).
+- **Backend Communication**: All API requests MUST use the `requestApi` wrapper (or its derivatives like `fetchApi`, `postApi`) from `src/lib/api.js`. Direct use of the native `fetch` API for backend communication is FORBIDDEN to ensure consistent authentication (JWT) and error handling.
 
-### IV. Design by Contract (DbC)
+### IV. Security & Access Control
-Contracts are the Source of Truth. Functions and Classes must define their purpose, specifications, and constraints in the metadata block before implementation, strictly following the **Contracts (Section IV)** standard in `semantic_protocol.md`.
+To support the Role-Based Access Control (RBAC) system, all functional components must define explicit permissions.
+- **Granular Permissions**: Every Plugin MUST define a unique permission string (e.g., `plugin:name:execute`) required for its operation.
+- **Registration**: These permissions MUST be registered in the system database (`auth.db`) during initialization.
 
-### V. Belief State Logging
+### V. Independent Testability
-Agents must maintain belief state logs for debugging and coherence checks, strictly following the **Logging Standard (Section V)** defined in `semantic_protocol.md`.
+Every feature specification MUST define "Independent Tests" that allow the feature to be verified in isolation.
+- **Decoupling**: Features should be designed such that they can be tested without requiring the full application state or external dependencies where possible.
+- **Verification**: A feature is not complete until its Independent Test scenarios pass.
 
-### VI. Fractal Complexity Limit
+### VI. Asynchronous Execution
-To maintain semantic coherence, code must adhere to the complexity limits (Module/Function size) defined in the **Fractal Complexity Limit (Section VI)** of `semantic_protocol.md`.
+All long-running or resource-intensive operations (migrations, analysis, backups, external API calls) MUST be executed as asynchronous tasks via the `TaskManager`.
-
+- **Non-Blocking**: HTTP API endpoints MUST NOT block on these operations; they should spawn a task and return a Task ID.
-### VII. Everything is a Plugin
+- **Observability**: Tasks MUST emit real-time status updates via the WebSocket infrastructure.
-All functional extensions, tools, or major features must be implemented as modular Plugins inheriting from `PluginBase`. Logic should not reside in standalone services or scripts unless strictly necessary for core infrastructure. This ensures a unified execution model via the `TaskManager`, consistent logging, and modularity.
-
-## File Structure Standards
-Refer to **Section III (File Structure Standard)** in `semantic_protocol.md` for the authoritative definitions of:
-- Python Module Headers (`.py`)
-- Svelte Component Headers (`.svelte`)
-
-## Generation Workflow
-The development process follows a streamlined single-phase workflow:
-
-### 1. Code Generation Phase (Mode: `code`)
-**Input**: `tasks.md`
-**Responsibility**:
-- Select task from `tasks.md`.
-- Generate Scaffolding (`[DEF]` anchors, Headers, Contracts) AND Implementation in one pass.
-- Ensure strict adherence to Protocol Section IV (Contracts) and Section VII (Generation Workflow).
-- **Output**: Working code with passing tests.
-
-### 2. Validation
-If logic conflicts with Contract -> Stop -> Report Error.
 
 ## Governance
 This Constitution establishes the "Semantic Code Generation Protocol" as the supreme law of this repository.
 
-- **Authoritative Source**: `semantic_protocol.md` defines the specific implementation rules for these Principles.
+- **Authoritative Source**: `semantic_protocol.md` defines the specific implementation rules for Principle I.
-- **Automated Enforcement**: Tools must validate adherence to the `semantic_protocol.md` syntax.
 - **Amendments**: Changes to core principles require a Constitution amendment. Changes to technical syntax require a Protocol update.
 - **Compliance**: Failure to adhere to the Protocol constitutes a build failure.
 
-**Version**: 1.7.1 | **Ratified**: 2025-12-19 | **Last Amended**: 2026-01-13
+**Version**: 2.3.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2026-02-18

.specify/templates/plan-template.md

@@ -18,7 +18,7 @@
 -->
 
 **Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
-**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, Tailwind CSS, SvelteKit or NEEDS CLARIFICATION]
 **Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
 **Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
 **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
@@ -102,3 +102,14 @@ directories captured above]
 |-----------|------------|-------------------------------------|
 | [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
 | [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
+
+## Test Data Reference
+
+> **For CRITICAL tier components, reference test fixtures from spec.md**
+
+| Component | TIER | Fixture Name | Location |
+|-----------|------|--------------|----------|
+| [e.g., DashboardAPI] | CRITICAL | valid_dashboard | spec.md#test-data-fixtures |
+| [e.g., TaskDrawer] | CRITICAL | task_states | spec.md#test-data-fixtures |
+
+**Note**: Tester Agent MUST use these fixtures when writing unit tests for CRITICAL modules. See `semantic_protocol.md` for @TEST_DATA syntax.

.specify/templates/spec-template.md

@@ -1,6 +1,7 @@
 # Feature Specification: [FEATURE NAME]
 
 **Feature Branch**: `[###-feature-name]`  
+**Reference UX**: `[ux_reference.md]` (See specific folder)
 **Created**: [DATE]  
 **Status**: Draft  
 **Input**: User description: "$ARGUMENTS"
@@ -113,3 +114,52 @@
 - **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
 - **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
 - **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+---
+
+## Test Data Fixtures *(recommended for CRITICAL components)*
+
+<!--
+  Define reference/fixture data for testing CRITICAL tier components.
+  This data will be used by the Tester Agent when writing unit tests.
+  Format: JSON or YAML that matches the component's data structures.
+-->
+
+### Fixtures
+
+```yaml
+# Example fixture format
+fixture_name:
+  description: "Description of this test data"
+  data:
+    # JSON or YAML data structure
+```
+
+### Example: Dashboard API
+
+```yaml
+valid_dashboard:
+  description: "Valid dashboard object for API responses"
+  data:
+    id: 1
+    title: "Sales Report"
+    slug: "sales"
+    git_status:
+      branch: "main"
+      sync_status: "OK"
+    last_task:
+      task_id: "task-123"
+      status: "SUCCESS"
+
+empty_dashboards:
+  description: "Empty dashboard list response"
+  data:
+    dashboards: []
+    total: 0
+    page: 1
+
+error_not_found:
+  description: "404 error response"
+  data:
+    detail: "Dashboard not found"
+```

.specify/templates/tasks-arch-template.md

@@ -1,35 +0,0 @@
----
-
-description: "Architecture task list template (Contracts & Scaffolding)"
----
-
-# Architecture Tasks: [FEATURE NAME]
-
-**Role**: Architect Agent
-**Goal**: Define the "What" and "Why" (Contracts, Scaffolding, Models) before implementation.
-**Input**: Design documents from `/specs/[###-feature-name]/`
-**Output**: Files with `[DEF]` anchors, `@PRE`/`@POST` contracts, and `@RELATION` mappings. No business logic.
-
-## Phase 1: Setup & Models
-
-- [ ] A001 Create/Update data models in [path] with `[DEF]` and contracts
-- [ ] A002 Define API route structure/contracts in [path]
-- [ ] A003 Define shared utilities/interfaces
-
-## Phase 2: User Story 1 - [Title]
-
-- [ ] A004 [US1] Define contracts for [Component/Service] in [path]
-- [ ] A005 [US1] Define contracts for [Endpoint] in [path]
-- [ ] A006 [US1] Define contracts for [Frontend Component] in [path]
-
-## Phase 3: User Story 2 - [Title]
-
-- [ ] A007 [US2] Define contracts for [Component/Service] in [path]
-- [ ] A008 [US2] Define contracts for [Endpoint] in [path]
-
-## Handover Checklist
-
-- [ ] All new files created with `[DEF]` anchors
-- [ ] All functions/classes have `@PURPOSE`, `@PRE`, `@POST` tags
-- [ ] No "naked code" (logic outside of anchors)
-- [ ] `tasks-dev.md` is ready for the Developer Agent

.specify/templates/tasks-dev-template.md

@@ -1,35 +0,0 @@
----
-
-description: "Developer task list template (Implementation Logic)"
----
-
-# Developer Tasks: [FEATURE NAME]
-
-**Role**: Developer Agent
-**Goal**: Implement the "How" (Logic, State, Error Handling) inside the defined contracts.
-**Input**: `tasks-arch.md` (completed), Scaffolding files with `[DEF]` anchors.
-**Output**: Working code that satisfies `@PRE`/`@POST` conditions.
-
-## Phase 1: Setup & Models
-
-- [ ] D001 Implement logic for [Model] in [path]
-- [ ] D002 Implement logic for [API Route] in [path]
-- [ ] D003 Implement shared utilities
-
-## Phase 2: User Story 1 - [Title]
-
-- [ ] D004 [US1] Implement logic for [Component/Service] in [path]
-- [ ] D005 [US1] Implement logic for [Endpoint] in [path]
-- [ ] D006 [US1] Implement logic for [Frontend Component] in [path]
-- [ ] D007 [US1] Verify semantic compliance and belief state logging
-
-## Phase 3: User Story 2 - [Title]
-
-- [ ] D008 [US2] Implement logic for [Component/Service] in [path]
-- [ ] D009 [US2] Implement logic for [Endpoint] in [path]
-
-## Polish & Quality Assurance
-
-- [ ] DXXX Verify all tests pass
-- [ ] DXXX Check error handling and edge cases
-- [ ] DXXX Ensure code style compliance

.specify/templates/tasks-template.md

@@ -93,7 +93,8 @@ Examples of foundational tasks (adjust based on your project):
 - [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
 - [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
 - [ ] T016 [US1] Add validation and error handling
-- [ ] T017 [US1] Add logging for user story 1 operations
+- [ ] T017 [US1] [P] Implement UI using Tailwind CSS (minimize scoped styles)
+- [ ] T018 [US1] Add logging for user story 1 operations
 
 **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
 

.specify/templates/test-docs-template.md

@@ -0,0 +1,152 @@
+---
+
+description: "Test documentation template for feature implementation"
+
+---
+
+# Test Documentation: [FEATURE NAME]
+
+**Feature**: [Link to spec.md]
+**Created**: [DATE]
+**Updated**: [DATE]
+**Tester**: [Agent/User Name]
+
+---
+
+## Overview
+
+[Brief description of what this feature does and why testing is important]
+
+**Test Strategy**:
+- [ ] Unit Tests (co-located in `__tests__/` directories)
+- [ ] Integration Tests (if needed)
+- [ ] E2E Tests (if critical user flows)
+- [ ] Contract Tests (for API endpoints)
+
+---
+
+## Test Coverage Matrix
+
+| Module | File | Unit Tests | Coverage % | Status |
+|--------|------|------------|------------|--------|
+| [Module Name] | `path/to/file.py` | [x] | [XX%] | [Pass/Fail] |
+| [Module Name] | `path/to/file.svelte` | [x] | [XX%] | [Pass/Fail] |
+
+---
+
+## Test Cases
+
+### [Module Name]
+
+**Target File**: `path/to/module.py`
+
+| ID | Test Case | Type | Expected Result | Status |
+|----|-----------|------|------------------|--------|
+| TC001 | [Description] | [Unit/Integration] | [Expected] | [Pass/Fail] |
+| TC002 | [Description] | [Unit/Integration] | [Expected] | [Pass/Fail] |
+
+---
+
+## Test Execution Reports
+
+### Report [YYYY-MM-DD]
+
+**Executed by**: [Tester]
+**Duration**: [X] minutes
+**Result**: [Pass/Fail]
+
+**Summary**:
+- Total Tests: [X]
+- Passed: [X]
+- Failed: [X]
+- Skipped: [X]
+
+**Failed Tests**:
+| Test | Error | Resolution |
+|------|-------|-------------|
+| [Test Name] | [Error Message] | [How Fixed] |
+
+---
+
+## Anti-Patterns & Rules
+
+### ✅ DO
+
+1. Write tests BEFORE implementation (TDD approach)
+2. Use co-location: `src/module/__tests__/test_module.py`
+3. Use MagicMock for external dependencies (DB, Auth, APIs)
+4. Include semantic annotations: `# @RELATION: VERIFIES -> module.name`
+5. Test edge cases and error conditions
+6. **Test UX states** for Svelte components (@UX_STATE, @UX_FEEDBACK, @UX_RECOVERY)
+
+### ❌ DON'T
+
+1. Delete existing tests (only update if they fail)
+2. Duplicate tests - check for existing tests first
+3. Test implementation details, not behavior
+4. Use real external services in unit tests
+5. Skip error handling tests
+6. **Skip UX contract tests** for CRITICAL frontend components
+
+---
+
+## UX Contract Testing (Frontend)
+
+### UX States Coverage
+
+| Component | @UX_STATE | @UX_FEEDBACK | @UX_RECOVERY | Tests |
+|-----------|-----------|--------------|--------------|-------|
+| [Component] | [states] | [feedback] | [recovery] | [status] |
+
+### UX Test Cases
+
+| ID | Component | UX Tag | Test Action | Expected Result | Status |
+|----|-----------|--------|-------------|-----------------|--------|
+| UX001 | [Component] | @UX_STATE: Idle | [action] | [expected] | [Pass/Fail] |
+| UX002 | [Component] | @UX_FEEDBACK | [action] | [expected] | [Pass/Fail] |
+| UX003 | [Component] | @UX_RECOVERY | [action] | [expected] | [Pass/Fail] |
+
+### UX Test Examples
+
+```javascript
+// Testing @UX_STATE transition
+it('should transition from Idle to Loading on submit', async () => {
+  render(FormComponent);
+  await fireEvent.click(screen.getByText('Submit'));
+  expect(screen.getByTestId('form')).toHaveClass('loading');
+});
+
+// Testing @UX_FEEDBACK
+it('should show error toast on validation failure', async () => {
+  render(FormComponent);
+  await fireEvent.click(screen.getByText('Submit'));
+  expect(screen.getByRole('alert')).toHaveTextContent('Validation error');
+});
+
+// Testing @UX_RECOVERY
+it('should allow retry after error', async () => {
+  render(FormComponent);
+  // Trigger error state
+  await fireEvent.click(screen.getByText('Submit'));
+  // Click retry
+  await fireEvent.click(screen.getByText('Retry'));
+  expect(screen.getByTestId('form')).not.toHaveClass('error');
+});
+```
+
+---
+
+## Notes
+
+- [Additional notes about testing approach]
+- [Known issues or limitations]
+- [Recommendations for future testing]
+
+---
+
+## Related Documents
+
+- [spec.md](./spec.md)
+- [plan.md](./plan.md)
+- [tasks.md](./tasks.md)
+- [contracts/](./contracts/)

.specify/templates/ux-reference-template.md

@@ -0,0 +1,67 @@
+# UX Reference: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`
+**Created**: [DATE]
+**Status**: Draft
+
+## 1. User Persona & Context
+
+*   **Who is the user?**: [e.g. Junior Developer, System Administrator, End User]
+*   **What is their goal?**: [e.g. Quickly deploy a hotfix, Visualize complex data]
+*   **Context**: [e.g. Running a command in a terminal on a remote server, Browsing the dashboard on a mobile device]
+
+## 2. The "Happy Path" Narrative
+
+[Write a short story (3-5 sentences) describing the perfect interaction from the user's perspective. Focus on how it *feels* - is it instant? Does it guide them?]
+
+## 3. Interface Mockups
+
+### CLI Interaction (if applicable)
+
+```bash
+# User runs this command:
+$ command --flag value
+
+# System responds immediately with:
+[ spinner ] specific loading message...
+
+# Success output:
+✅ Operation completed successfully in 1.2s
+   - Created file: /path/to/file
+   - Updated config: /path/to/config
+```
+
+### UI Layout & Flow (if applicable)
+
+**Screen/Component**: [Name]
+
+*   **Layout**: [Description of structure, e.g., "Two-column layout, left sidebar navigation..."]
+*   **Key Elements**:
+    *   **[Button Name]**: Primary action. Color: Blue.
+    *   **[Input Field]**: Placeholder text: "Enter your name...". Validation: Real-time.
+*   **States**:
+    *   **Default**: Clean state, waiting for input.
+    *   **Loading**: Skeleton loader replaces content area.
+    *   **Success**: Toast notification appears top-right: "Saved!" (Green).
+
+## 4. The "Error" Experience
+
+**Philosophy**: Don't just report the error; guide the user to the fix.
+
+### Scenario A: [Common Error, e.g. Invalid Input]
+
+*   **User Action**: Enters "123" in a text-only field.
+*   **System Response**:
+    *   (UI) Input border turns Red. Message below input: "Please enter text only."
+    *   (CLI) `❌ Error: Invalid input '123'. Expected text format.`
+*   **Recovery**: User can immediately re-type without refreshing/re-running.
+
+### Scenario B: [System Failure, e.g. Network Timeout]
+
+*   **System Response**: "Unable to connect. Retrying in 3s... (Press C to cancel)"
+*   **Recovery**: Automatic retry or explicit "Retry Now" button.
+
+## 5. Tone & Voice
+
+*   **Style**: [e.g. Concise, Technical, Friendly, Verbose]
+*   **Terminology**: [e.g. Use "Repository" not "Repo", "Directory" not "Folder"]

README.md

@@ -1,119 +1,77 @@
-# Инструменты автоматизации Superset
+# Инструменты автоматизации Superset (ss-tools)
 
 ## Обзор
-Этот репозиторий содержит Python-скрипты и библиотеку (`superset_tool`) для автоматизации задач в Apache Superset, таких как:
+**ss-tools** — это современная платформа для автоматизации и управления экосистемой Apache Superset. Проект перешел от набора CLI-скриптов к полноценному веб-приложению с архитектурой Backend (FastAPI) + Frontend (SvelteKit), обеспечивая удобный интерфейс для сложных операций.
-- **Резервное копирование**: Экспорт всех дашбордов из экземпляра Superset в локальное хранилище.
+
-- **Миграция**: Перенос и преобразование дашбордов между разными средами Superset (например, Development, Sandbox, Production).
+## Основные возможности
+
+### 🚀 Миграция и управление дашбордами
+- **Dashboard Grid**: Удобный просмотр всех дашбордов во всех окружениях (Dev, Sandbox, Prod) в едином интерфейсе.
+- **Интеллектуальный маппинг**: Автоматическое и ручное сопоставление датасетов, таблиц и схем при переносе между окружениями.
+- **Проверка зависимостей**: Валидация наличия всех необходимых компонентов перед миграцией.
+
+### 📦 Резервное копирование
+- **Планировщик (Scheduler)**: Автоматическое создание резервных копий дашбордов и датасетов по расписанию.
+- **Хранилище**: Локальное хранение артефактов с возможностью управления через UI.
+
+### 🛠 Git Интеграция
+- **Version Control**: Возможность версионирования ассетов Superset.
+- **Git Dashboard**: Управление ветками, коммитами и деплоем изменений напрямую из интерфейса.
+- **Conflict Resolution**: Встроенные инструменты для разрешения конфликтов в YAML-конфигурациях.
+
+### 🤖 LLM Анализ (AI Plugin)
+- **Автоматический аудит**: Анализ состояния дашбордов на основе скриншотов и метаданных.
+- **Генерация документации**: Автоматическое описание датасетов и колонок с помощью LLM (OpenAI, OpenRouter и др.).
+- **Smart Validation**: Поиск аномалий и ошибок в визуализациях.
+
+### 🔐 Безопасность и администрирование
+- **Multi-user Auth**: Многопользовательский доступ с ролевой моделью (RBAC).
+- **Управление подключениями**: Централизованная настройка доступов к различным инстансам Superset.
+- **Логирование**: Подробная история выполнения всех фоновых задач.
+
+## Технологический стек
+- **Backend**: Python 3.9+, FastAPI, SQLAlchemy, APScheduler, Pydantic.
+- **Frontend**: Node.js 18+, SvelteKit, Tailwind CSS.
+- **Database**: SQLite (для хранения метаданных, задач и настроек доступа).
 
 ## Структура проекта
-- `backup_script.py`: Основной скрипт для выполнения запланированного резервного копирования дашбордов Superset.
+- `backend/` — Серверная часть, API и логика плагинов.
-- `migration_script.py`: Основной скрипт для переноса конкретных дашбордов между окружениями, включая переопределение соединений с базами данных.
+- `frontend/` — Клиентская часть (SvelteKit приложение).
-- `search_script.py`: Скрипт для поиска данных во всех доступных датасетах на сервере
+- `specs/` — Спецификации функций и планы реализации.
-- `run_mapper.py`: CLI-скрипт для маппинга метаданных датасетов.
+- `docs/` — Дополнительная документация по маппингу и разработке плагинов.
-- `superset_tool/`:
-    - `client.py`: Python-клиент для взаимодействия с API Superset.
-    - `exceptions.py`: Пользовательские классы исключений для структурированной обработки ошибок.
-    - `models.py`: Pydantic-модели для валидации конфигурационных данных.
-    - `utils/`:
-        - `fileio.py`: Утилиты для работы с файловой системой (работа с архивами, парсинг YAML).
-        - `logger.py`: Конфигурация логгера для единообразного логирования в проекте.
-        - `network.py`: HTTP-клиент для сетевых запросов с обработкой аутентификации и повторных попыток.
-        - `init_clients.py`: Утилита для инициализации клиентов Superset для разных окружений.
-        - `dataset_mapper.py`: Логика маппинга метаданных датасетов.
 
-## Настройка
+## Быстрый старт
 
 ### Требования
 - Python 3.9+
-- `pip` для управления пакетами.
+- Node.js 18+
-- `keyring` для безопасного хранения паролей.
+- Настроенный доступ к API Superset
 
-### Установка
+### Запуск
-1. **Клонируйте репозиторий:**
+Для автоматической настройки окружений и запуска обоих серверов (Backend & Frontend) используйте скрипт:
-    ```bash
-    git clone https://prod.gitlab.dwh.rusal.com/dwh_bi/superset-tools.git
-    cd superset-tools
-    ```
-2. **Установите зависимости:**
-    ```bash
-    pip install -r requirements.txt
-    ```
-    (Возможно, потребуется создать `requirements.txt` с `pydantic`, `requests`, `keyring`, `PyYAML`, `urllib3`)
-3. **Настройте пароли:**
-    Используйте `keyring` для хранения паролей API-пользователей Superset.
-    ```python
-    import keyring
-    keyring.set_password("system", "dev migrate", "пароль пользователя migrate_user")
-    keyring.set_password("system", "prod migrate", "пароль пользователя migrate_user")
-    keyring.set_password("system", "sandbox migrate", "пароль пользователя migrate_user")
-    ```
-
-## Использование
-
-### Запуск проекта (Web UI)
-Для запуска backend и frontend серверов одной командой:
 ```bash
 ./run.sh
 ```
+*Скрипт создаст виртуальное окружение Python, установит зависимости `pip` и `npm`, и запустит сервисы.*
+
 Опции:
-- `--skip-install`: Пропустить проверку и установку зависимостей.
+- `--skip-install`: Пропустить установку зависимостей.
 - `--help`: Показать справку.
 
 Переменные окружения:
-- `BACKEND_PORT`: Порт для backend (по умолчанию 8000).
+- `BACKEND_PORT`: Порт API (по умолчанию 8000).
-- `FRONTEND_PORT`: Порт для frontend (по умолчанию 5173).
+- `FRONTEND_PORT`: Порт UI (по умолчанию 5173).
 
-### Скрипт резервного копирования (`backup_script.py`)
+## Разработка
-Для создания резервных копий дашбордов из настроенных окружений Superset:
+Проект следует строгим правилам разработки:
-```bash
+1. **Semantic Code Generation**: Использование протокола `semantic_protocol.md` для обеспечения надежности кода.
-python backup_script.py
+2. **Design by Contract (DbC)**: Определение предусловий и постусловий для ключевых функций.
-```
+3. **Constitution**: Соблюдение правил, описанных в конституции проекта в папке `.specify/`.
-Резервные копии сохраняются в `P:\Superset\010 Бекапы\` по умолчанию. Логи хранятся в `P:\Superset\010 Бекапы\Logs`.
 
-### Скрипт миграции (`migration_script.py`)
+### Полезные команды
-Для переноса конкретного дашборда:
+- **Backend**: `cd backend && .venv/bin/python3 -m uvicorn src.app:app --reload`
-```bash
+- **Frontend**: `cd frontend && npm run dev`
-python migration_script.py
+- **Тесты**: `cd backend && .venv/bin/pytest`
-```
 
-### Скрипт поиска (`search_script.py`)
+## Контакты и вклад
-Для поиска по текстовым паттернам в метаданных датасетов Superset:
+Для добавления новых функций или исправления ошибок, пожалуйста, ознакомьтесь с `docs/plugin_dev.md` и создайте соответствующую спецификацию в `specs/`.
-```bash
-python search_script.py
-```
-Скрипт использует регулярные выражения для поиска в полях датасетов, таких как SQL-запросы. Результаты поиска выводятся в лог и в консоль.
-
-### Скрипт маппинга метаданных (`run_mapper.py`)
-Для обновления метаданных датасета (например, verbose names) в Superset:
-```bash
-python run_mapper.py --source <source_type> --dataset-id <dataset_id> [--table-name <table_name>] [--table-schema <table_schema>] [--excel-path <path_to_excel>] [--env <environment>]
-```
-Если вы используете XLSX - файл должен содержать два столбца - column_name | verbose_name
-
-
-Параметры:
-- `--source`: Источник данных ('postgres', 'excel' или 'both').
-- `--dataset-id`: ID датасета для обновления.
-- `--table-name`: Имя таблицы для PostgreSQL.
-- `--table-schema`: Схема таблицы для PostgreSQL.
-- `--excel-path`: Путь к Excel-файлу.
-- `--env`: Окружение Superset ('dev', 'prod' и т.д.).
-
-Пример использования:
-```bash
-python run_mapper.py --source postgres --dataset-id 123 --table-name account_debt --table-schema dm_view --env dev
-
-python run_mapper.py --source=excel --dataset-id=286 --excel-path=H:\dev\ss-tools\286_map.xlsx --env=dev
-```
-
-## Логирование
-Логи пишутся в файл в директории `Logs` (например, `P:\Superset\010 Бекапы\Logs` для резервных копий) и выводятся в консоль. Уровень логирования по умолчанию — `INFO`.
-
-## Разработка и вклад
-- Следуйте **Semantic Code Generation Protocol** (см. `semantic_protocol.md`):
-    - Все определения обернуты в `[DEF]...[/DEF]`.
-    - Контракты (`@PRE`, `@POST`) определяются ДО реализации.
-    - Строгая типизация и иммутабельность архитектурных решений.
-- Соблюдайте Конституцию проекта (`.specify/memory/constitution.md`).
-- Используйте `Pydantic`-модели для валидации данных.
-- Реализуйте всестороннюю обработку ошибок с помощью пользовательских исключений.

backend/backups/Logs/superset_tool_20251220.log

@@ -1,269 +0,0 @@
-2025-12-20 19:55:11,325 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 19:55:11,325 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 19:55:11,327 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 43, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 21:01:49,905 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 21:01:49,906 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 21:01:49,988 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 21:01:49,990 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 22:42:32,538 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 22:42:32,538 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 22:42:32,583 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 22:42:32,587 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 22:54:29,770 - INFO - [BackupPlugin][Entry] Starting backup for .
-2025-12-20 22:54:29,771 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 22:54:29,831 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 22:54:29,833 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 22:54:34,078 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 22:54:34,078 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 22:54:34,079 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 22:54:34,079 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 22:59:25,060 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 22:59:25,060 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 22:59:25,114 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 22:59:25,117 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:00:31,156 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:00:31,156 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:00:31,157 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:00:31,162 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:00:34,710 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:00:34,710 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:00:34,710 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:00:34,711 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:01:43,894 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:01:43,894 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:01:43,895 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:01:43,895 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:04:07,731 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:04:07,731 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:04:07,732 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:04:07,732 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:06:39,641 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:06:39,642 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:06:39,687 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:06:39,689 - CRITICAL - [setup_clients][Failure] Critical error during client initialization: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-Traceback (most recent call last):
-  File "/home/user/ss-tools/superset_tool/utils/init_clients.py", line 66, in setup_clients
-    config = SupersetConfig(
-             ^^^^^^^^^^^^^^^
-  File "/home/user/ss-tools/backend/.venv/lib/python3.12/site-packages/pydantic/main.py", line 250, in __init__
-    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
-                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-pydantic_core._pydantic_core.ValidationError: 1 validation error for SupersetConfig
-base_url
-  Value error, Invalid URL format: https://superset.bebesh.ru. Must include '/api/v1'. [type=value_error, input_value='https://superset.bebesh.ru', input_type=str]
-    For further information visit https://errors.pydantic.dev/2.12/v/value_error
-2025-12-20 23:30:36,090 - INFO - [BackupPlugin][Entry] Starting backup for superset.
-2025-12-20 23:30:36,093 - INFO - [setup_clients][Enter] Starting Superset clients initialization.
-2025-12-20 23:30:36,128 - INFO - [setup_clients][Action] Loading environments from ConfigManager
-2025-12-20 23:30:36,129 - INFO - [SupersetClient.__init__][Enter] Initializing SupersetClient.
-2025-12-20 23:30:36,129 - INFO - [APIClient.__init__][Entry] Initializing APIClient.
-2025-12-20 23:30:36,130 - WARNING - [_init_session][State] SSL verification disabled.
-2025-12-20 23:30:36,130 - INFO - [APIClient.__init__][Exit] APIClient initialized.
-2025-12-20 23:30:36,130 - INFO - [SupersetClient.__init__][Exit] SupersetClient initialized.
-2025-12-20 23:30:36,130 - INFO - [get_dashboards][Enter] Fetching dashboards.
-2025-12-20 23:30:36,131 - INFO - [authenticate][Enter] Authenticating to https://superset.bebesh.ru/api/v1
-2025-12-20 23:30:36,897 - INFO - [authenticate][Exit] Authenticated successfully.
-2025-12-20 23:30:37,527 - INFO - [get_dashboards][Exit] Found 11 dashboards.
-2025-12-20 23:30:37,527 - INFO - [BackupPlugin][Progress] Found 11 dashboards to export in superset.
-2025-12-20 23:30:37,529 - INFO - [export_dashboard][Enter] Exporting dashboard 11.
-2025-12-20 23:30:38,224 - INFO - [export_dashboard][Exit] Exported dashboard 11 to dashboard_export_20251220T203037.zip.
-2025-12-20 23:30:38,225 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:38,226 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/FCC New Coder Survey 2018/dashboard_export_20251220T203037.zip
-2025-12-20 23:30:38,227 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/FCC New Coder Survey 2018
-2025-12-20 23:30:38,230 - INFO - [export_dashboard][Enter] Exporting dashboard 10.
-2025-12-20 23:30:38,438 - INFO - [export_dashboard][Exit] Exported dashboard 10 to dashboard_export_20251220T203038.zip.
-2025-12-20 23:30:38,438 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:38,439 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/COVID Vaccine Dashboard/dashboard_export_20251220T203038.zip
-2025-12-20 23:30:38,439 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/COVID Vaccine Dashboard
-2025-12-20 23:30:38,440 - INFO - [export_dashboard][Enter] Exporting dashboard 9.
-2025-12-20 23:30:38,853 - INFO - [export_dashboard][Exit] Exported dashboard 9 to dashboard_export_20251220T203038.zip.
-2025-12-20 23:30:38,853 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:38,856 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Sales Dashboard/dashboard_export_20251220T203038.zip
-2025-12-20 23:30:38,856 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Sales Dashboard
-2025-12-20 23:30:38,858 - INFO - [export_dashboard][Enter] Exporting dashboard 8.
-2025-12-20 23:30:38,939 - INFO - [export_dashboard][Exit] Exported dashboard 8 to dashboard_export_20251220T203038.zip.
-2025-12-20 23:30:38,940 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:38,941 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Unicode Test/dashboard_export_20251220T203038.zip
-2025-12-20 23:30:38,941 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Unicode Test
-2025-12-20 23:30:38,942 - INFO - [export_dashboard][Enter] Exporting dashboard 7.
-2025-12-20 23:30:39,148 - INFO - [export_dashboard][Exit] Exported dashboard 7 to dashboard_export_20251220T203038.zip.
-2025-12-20 23:30:39,148 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:39,149 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Video Game Sales/dashboard_export_20251220T203038.zip
-2025-12-20 23:30:39,149 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Video Game Sales
-2025-12-20 23:30:39,150 - INFO - [export_dashboard][Enter] Exporting dashboard 6.
-2025-12-20 23:30:39,689 - INFO - [export_dashboard][Exit] Exported dashboard 6 to dashboard_export_20251220T203039.zip.
-2025-12-20 23:30:39,689 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:39,690 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Featured Charts/dashboard_export_20251220T203039.zip
-2025-12-20 23:30:39,691 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Featured Charts
-2025-12-20 23:30:39,692 - INFO - [export_dashboard][Enter] Exporting dashboard 5.
-2025-12-20 23:30:39,960 - INFO - [export_dashboard][Exit] Exported dashboard 5 to dashboard_export_20251220T203039.zip.
-2025-12-20 23:30:39,960 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:39,961 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Slack Dashboard/dashboard_export_20251220T203039.zip
-2025-12-20 23:30:39,961 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Slack Dashboard
-2025-12-20 23:30:39,962 - INFO - [export_dashboard][Enter] Exporting dashboard 4.
-2025-12-20 23:30:40,196 - INFO - [export_dashboard][Exit] Exported dashboard 4 to dashboard_export_20251220T203039.zip.
-2025-12-20 23:30:40,196 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:40,197 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/deck.gl Demo/dashboard_export_20251220T203039.zip
-2025-12-20 23:30:40,197 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/deck.gl Demo
-2025-12-20 23:30:40,198 - INFO - [export_dashboard][Enter] Exporting dashboard 3.
-2025-12-20 23:30:40,745 - INFO - [export_dashboard][Exit] Exported dashboard 3 to dashboard_export_20251220T203040.zip.
-2025-12-20 23:30:40,746 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:40,760 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/Misc Charts/dashboard_export_20251220T203040.zip
-2025-12-20 23:30:40,761 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/Misc Charts
-2025-12-20 23:30:40,762 - INFO - [export_dashboard][Enter] Exporting dashboard 2.
-2025-12-20 23:30:40,928 - INFO - [export_dashboard][Exit] Exported dashboard 2 to dashboard_export_20251220T203040.zip.
-2025-12-20 23:30:40,929 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:40,930 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/USA Births Names/dashboard_export_20251220T203040.zip
-2025-12-20 23:30:40,931 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/USA Births Names
-2025-12-20 23:30:40,932 - INFO - [export_dashboard][Enter] Exporting dashboard 1.
-2025-12-20 23:30:41,582 - INFO - [export_dashboard][Exit] Exported dashboard 1 to dashboard_export_20251220T203040.zip.
-2025-12-20 23:30:41,582 - INFO - [save_and_unpack_dashboard][Enter] Processing dashboard. Unpack: False
-2025-12-20 23:30:41,749 - INFO - [save_and_unpack_dashboard][State] Dashboard saved to: backups/SUPERSET/World Bank's Data/dashboard_export_20251220T203040.zip
-2025-12-20 23:30:41,750 - INFO - [archive_exports][Enter] Managing archive in backups/SUPERSET/World Bank's Data
-2025-12-20 23:30:41,752 - INFO - [consolidate_archive_folders][Enter] Consolidating archives in backups/SUPERSET
-2025-12-20 23:30:41,753 - INFO - [remove_empty_directories][Enter] Starting cleanup of empty directories in backups/SUPERSET
-2025-12-20 23:30:41,758 - INFO - [remove_empty_directories][Exit] Removed 0 empty directories.
-2025-12-20 23:30:41,758 - INFO - [BackupPlugin][CoherenceCheck:Passed] Backup logic completed for superset.

backend/delete_running_tasks.py

@@ -1,10 +1,17 @@
 #!/usr/bin/env python3
-"""Script to delete tasks with RUNNING status from the database."""
+# [DEF:backend.delete_running_tasks:Module]
+# @PURPOSE: Script to delete tasks with RUNNING status from the database.
+# @LAYER: Utility
+# @SEMANTICS: maintenance, database, cleanup
 
 from sqlalchemy.orm import Session
 from src.core.database import TasksSessionLocal
 from src.models.task import TaskRecord
 
+# [DEF:delete_running_tasks:Function]
+# @PURPOSE: Delete all tasks with RUNNING status from the database.
+# @PRE: Database is accessible and TaskRecord model is defined.
+# @POST: All tasks with status 'RUNNING' are removed from the database.
 def delete_running_tasks():
     """Delete all tasks with RUNNING status from the database."""
     session: Session = TasksSessionLocal()
@@ -30,6 +37,8 @@ def delete_running_tasks():
         print(f"Error deleting tasks: {e}")
     finally:
         session.close()
+# [/DEF:delete_running_tasks:Function]
 
 if __name__ == "__main__":
     delete_running_tasks()
+# [/DEF:backend.delete_running_tasks:Module]

backend/get_full_key.py

@@ -0,0 +1 @@
+{"print(f'Length": {"else": "print('Provider not found')\ndb.close()"}}

backend/requirements.txt

@@ -25,9 +25,13 @@ keyring==25.7.0
 more-itertools==10.8.0
 pycparser==2.23
 pydantic==2.12.5
+pydantic-settings
 pydantic_core==2.41.5
 python-multipart==0.0.21
 PyYAML==6.0.3
+passlib[bcrypt]
+python-jose[cryptography]
+PyJWT
 RapidFuzz==3.14.3
 referencing==0.37.0
 requests==2.32.5
@@ -44,3 +48,9 @@ websockets==15.0.1
 pandas
 psycopg2-binary
 openpyxl
+GitPython==3.1.44
+itsdangerous
+email-validator
+openai
+playwright
+tenacity

backend/src/api/auth.py

@@ -1,59 +1,118 @@
-# [DEF:AuthModule:Module]
+# [DEF:backend.src.api.auth:Module]
-# @SEMANTICS: auth, authentication, adfs, oauth, middleware
+#
-# @PURPOSE: Implements ADFS authentication using Authlib for FastAPI. It provides a dependency to protect endpoints.
+# @SEMANTICS: api, auth, routes, login, logout
-# @LAYER: UI (API)
+# @PURPOSE:   Authentication API endpoints.
-# @RELATION: Used by API routers to protect endpoints that require authentication.
+# @LAYER:     API
+# @RELATION:  USES -> backend.src.services.auth_service.AuthService
+# @RELATION:  USES -> backend.src.core.database.get_auth_db
+#
+# @INVARIANT: All auth endpoints must return consistent error codes.
 
-from fastapi import Depends, HTTPException, status
+# [SECTION: IMPORTS]
-from fastapi.security import OAuth2AuthorizationCodeBearer
+from fastapi import APIRouter, Depends, HTTPException, status
-from authlib.integrations.starlette_client import OAuth
+from fastapi.security import OAuth2PasswordRequestForm
-from starlette.config import Config
+from sqlalchemy.orm import Session
+from ..core.database import get_auth_db
+from ..services.auth_service import AuthService
+from ..schemas.auth import Token, User as UserSchema
+from ..dependencies import get_current_user
+from ..core.auth.oauth import oauth, is_adfs_configured
+from ..core.auth.logger import log_security_event
+from ..core.logger import belief_scope
+import starlette.requests
+# [/SECTION]
 
-# Placeholder for ADFS configuration. In a real app, this would come from a secure source.
+# [DEF:router:Variable]
-# Create an in-memory .env file
+# @PURPOSE: APIRouter instance for authentication routes.
-from io import StringIO
+router = APIRouter(prefix="/api/auth", tags=["auth"])
-config_data = StringIO("""
+# [/DEF:router:Variable]
-ADFS_CLIENT_ID=your-client-id
-ADFS_CLIENT_SECRET=your-client-secret
-ADFS_SERVER_METADATA_URL=https://your-adfs-server/.well-known/openid-configuration
-""")
-config = Config(config_data)
-oauth = OAuth(config)
 
-oauth.register(
+# [DEF:login_for_access_token:Function]
-    name='adfs',
+# @PURPOSE: Authenticates a user and returns a JWT access token.
-    server_metadata_url=config('ADFS_SERVER_METADATA_URL'),
+# @PRE:     form_data contains username and password.
-    client_kwargs={'scope': 'openid profile email'}
+# @POST:    Returns a Token object on success.
-)
+# @THROW:   HTTPException 401 if authentication fails.
+# @PARAM:   form_data (OAuth2PasswordRequestForm) - Login credentials.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  Token - The generated JWT token.
+@router.post("/login", response_model=Token)
+async def login_for_access_token(
+    form_data: OAuth2PasswordRequestForm = Depends(),
+    db: Session = Depends(get_auth_db)
+):
+    with belief_scope("api.auth.login"):
+        auth_service = AuthService(db)
+        user = auth_service.authenticate_user(form_data.username, form_data.password)
+        if not user:
+            log_security_event("LOGIN_FAILED", form_data.username, {"reason": "Invalid credentials"})
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Incorrect username or password",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        log_security_event("LOGIN_SUCCESS", user.username, {"source": "LOCAL"})
+        return auth_service.create_session(user)
+# [/DEF:login_for_access_token:Function]
 
-oauth2_scheme = OAuth2AuthorizationCodeBearer(
+# [DEF:read_users_me:Function]
-    authorizationUrl="https://your-adfs-server/adfs/oauth2/authorize",
+# @PURPOSE: Retrieves the profile of the currently authenticated user.
-    tokenUrl="https://your-adfs-server/adfs/oauth2/token",
+# @PRE:     Valid JWT token provided.
-)
+# @POST:    Returns the current user's data.
+# @PARAM:   current_user (UserSchema) - The user extracted from the token.
+# @RETURN:  UserSchema - The current user profile.
+@router.get("/me", response_model=UserSchema)
+async def read_users_me(current_user: UserSchema = Depends(get_current_user)):
+    with belief_scope("api.auth.me"):
+        return current_user
+# [/DEF:read_users_me:Function]
 
-# [DEF:get_current_user:Function]
+# [DEF:logout:Function]
-# @PURPOSE: Dependency to get the current user from the ADFS token.
+# @PURPOSE: Logs out the current user (placeholder for session revocation).
-# @PARAM: token (str) - The OAuth2 bearer token.
+# @PRE:     Valid JWT token provided.
-# @PRE: token should be provided via Authorization header.
+# @POST:    Returns success message.
-# @POST: Returns user details if authenticated, else raises 401.
+@router.post("/logout")
-# @RETURN: Dict[str, str] - User information.
+async def logout(current_user: UserSchema = Depends(get_current_user)):
-async def get_current_user(token: str = Depends(oauth2_scheme)):
+    with belief_scope("api.auth.logout"):
-    """
+        log_security_event("LOGOUT", current_user.username)
-    Dependency to get the current user from the ADFS token.
+        # In a stateless JWT setup, client-side token deletion is primary.
-    This is a placeholder and needs to be fully implemented.
+        # Server-side revocation (blacklisting) can be added here if needed.
-    """
+        return {"message": "Successfully logged out"}
-    # In a real implementation, you would:
+# [/DEF:logout:Function]
-    # 1. Validate the token with ADFS.
+
-    # 2. Fetch user information.
+# [DEF:login_adfs:Function]
-    # 3. Create a user object.
+# @PURPOSE: Initiates the ADFS OIDC login flow.
-    # For now, we'll just check if a token exists.
+# @POST:    Redirects the user to ADFS.
-    if not token:
+@router.get("/login/adfs")
-        raise HTTPException(
+async def login_adfs(request: starlette.requests.Request):
-            status_code=status.HTTP_401_UNAUTHORIZED,
+    with belief_scope("api.auth.login_adfs"):
-            detail="Not authenticated",
+        if not is_adfs_configured():
-            headers={"WWW-Authenticate": "Bearer"},
+            raise HTTPException(
-        )
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-    # A real implementation would return a user object.
+                detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables."
-    return {"placeholder_user": "user@example.com"}
+            )
-# [/DEF:get_current_user:Function]
+        redirect_uri = request.url_for('auth_callback_adfs')
-# [/DEF:AuthModule:Module]
+        return await oauth.adfs.authorize_redirect(request, str(redirect_uri))
+# [/DEF:login_adfs:Function]
+
+# [DEF:auth_callback_adfs:Function]
+# @PURPOSE: Handles the callback from ADFS after successful authentication.
+# @POST:    Provisions user JIT and returns session token.
+@router.get("/callback/adfs", name="auth_callback_adfs")
+async def auth_callback_adfs(request: starlette.requests.Request, db: Session = Depends(get_auth_db)):
+    with belief_scope("api.auth.callback_adfs"):
+        if not is_adfs_configured():
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="ADFS is not configured. Please set ADFS_CLIENT_ID, ADFS_CLIENT_SECRET, and ADFS_METADATA_URL environment variables."
+            )
+        token = await oauth.adfs.authorize_access_token(request)
+        user_info = token.get('userinfo')
+        if not user_info:
+            raise HTTPException(status_code=400, detail="Failed to retrieve user info from ADFS")
+        
+        auth_service = AuthService(db)
+        user = auth_service.provision_adfs_user(user_info)
+        return auth_service.create_session(user)
+# [/DEF:auth_callback_adfs:Function]
+
+# [/DEF:backend.src.api.auth:Module]

backend/src/api/routes/__init__.py

@@ -1 +1,10 @@
-from . import plugins, tasks, settings, connections
+# Lazy loading of route modules to avoid import issues in tests
+# This allows tests to import routes without triggering all module imports
+
+__all__ = ['plugins', 'tasks', 'settings', 'connections', 'environments', 'mappings', 'migration', 'git', 'storage', 'admin']
+
+def __getattr__(name):
+    if name in __all__:
+        import importlib
+        return importlib.import_module(f".{name}", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

backend/src/api/routes/__tests__/test_dashboards.py

@@ -0,0 +1,286 @@
+# [DEF:backend.src.api.routes.__tests__.test_dashboards:Module]
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for Dashboards API endpoints
+# @LAYER: API
+# @RELATION: TESTS -> backend.src.api.routes.dashboards
+
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock
+from fastapi.testclient import TestClient
+from src.app import app
+from src.api.routes.dashboards import DashboardsResponse
+
+client = TestClient(app)
+
+
+# [DEF:test_get_dashboards_success:Function]
+# @TEST: GET /api/dashboards returns 200 and valid schema
+# @PRE: env_id exists
+# @POST: Response matches DashboardsResponse schema
+def test_get_dashboards_success():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.get_resource_service") as mock_service, \
+         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        # Mock task manager
+        mock_task_mgr.return_value.get_all_tasks.return_value = []
+        
+        # Mock resource service response
+        async def mock_get_dashboards(env, tasks):
+            return [
+                {
+                    "id": 1,
+                    "title": "Sales Report",
+                    "slug": "sales",
+                    "git_status": {"branch": "main", "sync_status": "OK"},
+                    "last_task": {"task_id": "task-1", "status": "SUCCESS"}
+                }
+            ]
+        mock_service.return_value.get_dashboards_with_status = AsyncMock(
+            side_effect=mock_get_dashboards
+        )
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/dashboards?env_id=prod")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "dashboards" in data
+        assert "total" in data
+        assert "page" in data
+
+
+# [/DEF:test_get_dashboards_success:Function]
+
+
+# [DEF:test_get_dashboards_with_search:Function]
+# @TEST: GET /api/dashboards filters by search term
+# @PRE: search parameter provided
+# @POST: Only matching dashboards returned
+def test_get_dashboards_with_search():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.get_resource_service") as mock_service, \
+         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        mock_task_mgr.return_value.get_all_tasks.return_value = []
+        
+        async def mock_get_dashboards(env, tasks):
+            return [
+                {"id": 1, "title": "Sales Report", "slug": "sales"},
+                {"id": 2, "title": "Marketing Dashboard", "slug": "marketing"}
+            ]
+        mock_service.return_value.get_dashboards_with_status = AsyncMock(
+            side_effect=mock_get_dashboards
+        )
+        
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/dashboards?env_id=prod&search=sales")
+        
+        assert response.status_code == 200
+        data = response.json()
+        # Filtered by search term
+
+
+# [/DEF:test_get_dashboards_with_search:Function]
+
+
+# [DEF:test_get_dashboards_env_not_found:Function]
+# @TEST: GET /api/dashboards returns 404 if env_id missing
+# @PRE: env_id does not exist
+# @POST: Returns 404 error
+def test_get_dashboards_env_not_found():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        mock_config.return_value.get_environments.return_value = []
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/dashboards?env_id=nonexistent")
+        
+        assert response.status_code == 404
+        assert "Environment not found" in response.json()["detail"]
+
+
+# [/DEF:test_get_dashboards_env_not_found:Function]
+
+
+# [DEF:test_get_dashboards_invalid_pagination:Function]
+# @TEST: GET /api/dashboards returns 400 for invalid page/page_size
+# @PRE: page < 1 or page_size > 100
+# @POST: Returns 400 error
+def test_get_dashboards_invalid_pagination():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        mock_perm.return_value = lambda: True
+
+        # Invalid page
+        response = client.get("/api/dashboards?env_id=prod&page=0")
+        assert response.status_code == 400
+        assert "Page must be >= 1" in response.json()["detail"]
+        
+        # Invalid page_size
+        response = client.get("/api/dashboards?env_id=prod&page_size=101")
+        assert response.status_code == 400
+        assert "Page size must be between 1 and 100" in response.json()["detail"]
+
+
+# [/DEF:test_get_dashboards_invalid_pagination:Function]
+
+
+# [DEF:test_migrate_dashboards_success:Function]
+# @TEST: POST /api/dashboards/migrate creates migration task
+# @PRE: Valid source_env_id, target_env_id, dashboard_ids
+# @POST: Returns task_id
+def test_migrate_dashboards_success():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        # Mock environments
+        mock_source = MagicMock()
+        mock_source.id = "source"
+        mock_target = MagicMock()
+        mock_target.id = "target"
+        mock_config.return_value.get_environments.return_value = [mock_source, mock_target]
+        
+        # Mock task manager
+        mock_task = MagicMock()
+        mock_task.id = "task-migrate-123"
+        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/dashboards/migrate",
+            json={
+                "source_env_id": "source",
+                "target_env_id": "target",
+                "dashboard_ids": [1, 2, 3],
+                "db_mappings": {"old_db": "new_db"}
+            }
+        )
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "task_id" in data
+
+
+# [/DEF:test_migrate_dashboards_success:Function]
+
+
+# [DEF:test_migrate_dashboards_no_ids:Function]
+# @TEST: POST /api/dashboards/migrate returns 400 for empty dashboard_ids
+# @PRE: dashboard_ids is empty
+# @POST: Returns 400 error
+def test_migrate_dashboards_no_ids():
+    with patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/dashboards/migrate",
+            json={
+                "source_env_id": "source",
+                "target_env_id": "target",
+                "dashboard_ids": []
+            }
+        )
+        
+        assert response.status_code == 400
+        assert "At least one dashboard ID must be provided" in response.json()["detail"]
+
+
+# [/DEF:test_migrate_dashboards_no_ids:Function]
+
+
+# [DEF:test_backup_dashboards_success:Function]
+# @TEST: POST /api/dashboards/backup creates backup task
+# @PRE: Valid env_id, dashboard_ids
+# @POST: Returns task_id
+def test_backup_dashboards_success():
+    with patch("src.api.routes.dashboards.get_config_manager") as mock_config, \
+         patch("src.api.routes.dashboards.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        # Mock task manager
+        mock_task = MagicMock()
+        mock_task.id = "task-backup-456"
+        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/dashboards/backup",
+            json={
+                "env_id": "prod",
+                "dashboard_ids": [1, 2, 3],
+                "schedule": "0 0 * * *"
+            }
+        )
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "task_id" in data
+
+
+# [/DEF:test_backup_dashboards_success:Function]
+
+
+# [DEF:test_get_database_mappings_success:Function]
+# @TEST: GET /api/dashboards/db-mappings returns mapping suggestions
+# @PRE: Valid source_env_id, target_env_id
+# @POST: Returns list of database mappings
+def test_get_database_mappings_success():
+    with patch("src.api.routes.dashboards.get_mapping_service") as mock_service, \
+         patch("src.api.routes.dashboards.has_permission") as mock_perm:
+        
+        # Mock mapping service
+        mock_service.return_value.get_suggestions = AsyncMock(return_value=[
+            {
+                "source_db": "old_sales",
+                "target_db": "new_sales",
+                "source_db_uuid": "uuid-1",
+                "target_db_uuid": "uuid-2",
+                "confidence": 0.95
+            }
+        ])
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/dashboards/db-mappings?source_env_id=prod&target_env_id=staging")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "mappings" in data
+
+
+# [/DEF:test_get_database_mappings_success:Function]
+
+
+# [/DEF:backend.src.api.routes.__tests__.test_dashboards:Module]

backend/src/api/routes/__tests__/test_datasets.py

@@ -0,0 +1,209 @@
+# [DEF:backend.src.api.routes.__tests__.test_datasets:Module]
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for Datasets API endpoints
+# @LAYER: API
+# @RELATION: TESTS -> backend.src.api.routes.datasets
+
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock
+from fastapi.testclient import TestClient
+from src.app import app
+from src.api.routes.datasets import DatasetsResponse, DatasetDetailResponse
+
+client = TestClient(app)
+
+
+# [DEF:test_get_datasets_success:Function]
+# @TEST: GET /api/datasets returns 200 and valid schema
+# @PRE: env_id exists
+# @POST: Response matches DatasetsResponse schema
+def test_get_datasets_success():
+    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
+         patch("src.api.routes.datasets.get_resource_service") as mock_service, \
+         patch("src.api.routes.datasets.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        # Mock resource service response
+        mock_service.return_value.get_datasets_with_status.return_value = AsyncMock()(
+            return_value=[
+                {
+                    "id": 1,
+                    "table_name": "sales_data",
+                    "schema": "public",
+                    "database": "sales_db",
+                    "mapped_fields": {"total": 10, "mapped": 5},
+                    "last_task": {"task_id": "task-1", "status": "SUCCESS"}
+                }
+            ]
+        )
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/datasets?env_id=prod")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "datasets" in data
+        assert len(data["datasets"]) >= 0
+        # Validate against Pydantic model
+        DatasetsResponse(**data)
+
+
+# [/DEF:test_get_datasets_success:Function]
+
+
+# [DEF:test_get_datasets_env_not_found:Function]
+# @TEST: GET /api/datasets returns 404 if env_id missing
+# @PRE: env_id does not exist
+# @POST: Returns 404 error
+def test_get_datasets_env_not_found():
+    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
+         patch("src.api.routes.datasets.has_permission") as mock_perm:
+        
+        mock_config.return_value.get_environments.return_value = []
+        mock_perm.return_value = lambda: True
+
+        response = client.get("/api/datasets?env_id=nonexistent")
+        
+        assert response.status_code == 404
+        assert "Environment not found" in response.json()["detail"]
+
+
+# [/DEF:test_get_datasets_env_not_found:Function]
+
+
+# [DEF:test_get_datasets_invalid_pagination:Function]
+# @TEST: GET /api/datasets returns 400 for invalid page/page_size
+# @PRE: page < 1 or page_size > 100
+# @POST: Returns 400 error
+def test_get_datasets_invalid_pagination():
+    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
+         patch("src.api.routes.datasets.has_permission") as mock_perm:
+        
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        mock_perm.return_value = lambda: True
+
+        # Invalid page
+        response = client.get("/api/datasets?env_id=prod&page=0")
+        assert response.status_code == 400
+        assert "Page must be >= 1" in response.json()["detail"]
+        
+        # Invalid page_size
+        response = client.get("/api/datasets?env_id=prod&page_size=0")
+        assert response.status_code == 400
+        assert "Page size must be between 1 and 100" in response.json()["detail"]
+
+
+# [/DEF:test_get_datasets_invalid_pagination:Function]
+
+
+# [DEF:test_map_columns_success:Function]
+# @TEST: POST /api/datasets/map-columns creates mapping task
+# @PRE: Valid env_id, dataset_ids, source_type
+# @POST: Returns task_id
+def test_map_columns_success():
+    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
+         patch("src.api.routes.datasets.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.datasets.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        # Mock task manager
+        mock_task = MagicMock()
+        mock_task.id = "task-123"
+        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/datasets/map-columns",
+            json={
+                "env_id": "prod",
+                "dataset_ids": [1, 2, 3],
+                "source_type": "postgresql"
+            }
+        )
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "task_id" in data
+
+
+# [/DEF:test_map_columns_success:Function]
+
+
+# [DEF:test_map_columns_invalid_source_type:Function]
+# @TEST: POST /api/datasets/map-columns returns 400 for invalid source_type
+# @PRE: source_type is not 'postgresql' or 'xlsx'
+# @POST: Returns 400 error
+def test_map_columns_invalid_source_type():
+    with patch("src.api.routes.datasets.has_permission") as mock_perm:
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/datasets/map-columns",
+            json={
+                "env_id": "prod",
+                "dataset_ids": [1],
+                "source_type": "invalid"
+            }
+        )
+        
+        assert response.status_code == 400
+        assert "Source type must be 'postgresql' or 'xlsx'" in response.json()["detail"]
+
+
+# [/DEF:test_map_columns_invalid_source_type:Function]
+
+
+# [DEF:test_generate_docs_success:Function]
+# @TEST: POST /api/datasets/generate-docs creates doc generation task
+# @PRE: Valid env_id, dataset_ids, llm_provider
+# @POST: Returns task_id
+def test_generate_docs_success():
+    with patch("src.api.routes.datasets.get_config_manager") as mock_config, \
+         patch("src.api.routes.datasets.get_task_manager") as mock_task_mgr, \
+         patch("src.api.routes.datasets.has_permission") as mock_perm:
+        
+        # Mock environment
+        mock_env = MagicMock()
+        mock_env.id = "prod"
+        mock_config.return_value.get_environments.return_value = [mock_env]
+        
+        # Mock task manager
+        mock_task = MagicMock()
+        mock_task.id = "task-456"
+        mock_task_mgr.return_value.create_task = AsyncMock(return_value=mock_task)
+        
+        # Mock permission
+        mock_perm.return_value = lambda: True
+
+        response = client.post(
+            "/api/datasets/generate-docs",
+            json={
+                "env_id": "prod",
+                "dataset_ids": [1],
+                "llm_provider": "openai"
+            }
+        )
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert "task_id" in data
+
+
+# [/DEF:test_generate_docs_success:Function]
+
+
+# [/DEF:backend.src.api.routes.__tests__.test_datasets:Module]

backend/src/api/routes/admin.py

@@ -0,0 +1,310 @@
+# [DEF:backend.src.api.routes.admin:Module]
+#
+# @TIER:      STANDARD
+# @SEMANTICS: api, admin, users, roles, permissions
+# @PURPOSE:   Admin API endpoints for user and role management.
+# @LAYER:     API
+# @RELATION:  USES -> backend.src.core.auth.repository.AuthRepository
+# @RELATION:  USES -> backend.src.dependencies.has_permission
+#
+# @INVARIANT: All endpoints in this module require 'Admin' role or 'admin' scope.
+
+# [SECTION: IMPORTS]
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from ...core.database import get_auth_db
+from ...core.auth.repository import AuthRepository
+from ...core.auth.security import get_password_hash
+from ...schemas.auth import (
+    User as UserSchema, UserCreate, UserUpdate,
+    RoleSchema, RoleCreate, RoleUpdate, PermissionSchema,
+    ADGroupMappingSchema, ADGroupMappingCreate
+)
+from ...models.auth import User, Role, ADGroupMapping
+from ...dependencies import has_permission
+from ...core.logger import logger, belief_scope
+# [/SECTION]
+
+# [DEF:router:Variable]
+# @PURPOSE: APIRouter instance for admin routes.
+router = APIRouter(prefix="/api/admin", tags=["admin"])
+# [/DEF:router:Variable]
+
+# [DEF:list_users:Function]
+# @PURPOSE: Lists all registered users.
+# @PRE:     Current user has 'Admin' role.
+# @POST:    Returns a list of UserSchema objects.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  List[UserSchema] - List of users.
+@router.get("/users", response_model=List[UserSchema])
+async def list_users(
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:users", "READ"))
+):
+    with belief_scope("api.admin.list_users"):
+        users = db.query(User).all()
+        return users
+# [/DEF:list_users:Function]
+
+# [DEF:create_user:Function]
+# @PURPOSE: Creates a new local user.
+# @PRE:     Current user has 'Admin' role.
+# @POST:    New user is created in the database.
+# @PARAM:   user_in (UserCreate) - New user data.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  UserSchema - The created user.
+@router.post("/users", response_model=UserSchema, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    user_in: UserCreate,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:users", "WRITE"))
+):
+    with belief_scope("api.admin.create_user"):
+        repo = AuthRepository(db)
+        if repo.get_user_by_username(user_in.username):
+            raise HTTPException(status_code=400, detail="Username already exists")
+        
+        new_user = User(
+            username=user_in.username,
+            email=user_in.email,
+            password_hash=get_password_hash(user_in.password),
+            auth_source="LOCAL",
+            is_active=user_in.is_active
+        )
+        
+        for role_name in user_in.roles:
+            role = repo.get_role_by_name(role_name)
+            if role:
+                new_user.roles.append(role)
+        
+        db.add(new_user)
+        db.commit()
+        db.refresh(new_user)
+        return new_user
+# [/DEF:create_user:Function]
+
+# [DEF:update_user:Function]
+# @PURPOSE: Updates an existing user.
+@router.put("/users/{user_id}", response_model=UserSchema)
+async def update_user(
+    user_id: str,
+    user_in: UserUpdate,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:users", "WRITE"))
+):
+    with belief_scope("api.admin.update_user"):
+        repo = AuthRepository(db)
+        user = repo.get_user_by_id(user_id)
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+        
+        if user_in.email is not None:
+            user.email = user_in.email
+        if user_in.is_active is not None:
+            user.is_active = user_in.is_active
+        if user_in.password is not None:
+            user.password_hash = get_password_hash(user_in.password)
+        
+        if user_in.roles is not None:
+            user.roles = []
+            for role_name in user_in.roles:
+                role = repo.get_role_by_name(role_name)
+                if role:
+                    user.roles.append(role)
+        
+        db.commit()
+        db.refresh(user)
+        return user
+# [/DEF:update_user:Function]
+
+# [DEF:delete_user:Function]
+# @PURPOSE: Deletes a user.
+@router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: str,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:users", "WRITE"))
+):
+    with belief_scope("api.admin.delete_user"):
+        logger.info(f"[DEBUG] Attempting to delete user context={{'user_id': '{user_id}'}}")
+        repo = AuthRepository(db)
+        user = repo.get_user_by_id(user_id)
+        if not user:
+            logger.warning(f"[DEBUG] User not found for deletion context={{'user_id': '{user_id}'}}")
+            raise HTTPException(status_code=404, detail="User not found")
+        
+        logger.info(f"[DEBUG] Found user to delete context={{'username': '{user.username}'}}")
+        db.delete(user)
+        db.commit()
+        logger.info(f"[DEBUG] Successfully deleted user context={{'user_id': '{user_id}'}}")
+        return None
+# [/DEF:delete_user:Function]
+
+# [DEF:list_roles:Function]
+# @PURPOSE: Lists all available roles.
+# @RETURN:  List[RoleSchema] - List of roles.
+# @RELATION: CALLS -> backend.src.models.auth.Role
+@router.get("/roles", response_model=List[RoleSchema])
+async def list_roles(
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:roles", "READ"))
+):
+    with belief_scope("api.admin.list_roles"):
+        return db.query(Role).all()
+# [/DEF:list_roles:Function]
+
+# [DEF:create_role:Function]
+# @PURPOSE: Creates a new system role with associated permissions.
+# @PRE:     Role name must be unique.
+# @POST:    New Role record is created in auth.db.
+# @PARAM:   role_in (RoleCreate) - New role data.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  RoleSchema - The created role.
+# @SIDE_EFFECT: Commits new role and associations to auth.db.
+# @RELATION: CALLS -> backend.src.core.auth.repository.AuthRepository.get_permission_by_id
+@router.post("/roles", response_model=RoleSchema, status_code=status.HTTP_201_CREATED)
+async def create_role(
+    role_in: RoleCreate,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:roles", "WRITE"))
+):
+    with belief_scope("api.admin.create_role"):
+        if db.query(Role).filter(Role.name == role_in.name).first():
+            raise HTTPException(status_code=400, detail="Role already exists")
+        
+        new_role = Role(name=role_in.name, description=role_in.description)
+        repo = AuthRepository(db)
+        
+        for perm_id_or_str in role_in.permissions:
+            perm = repo.get_permission_by_id(perm_id_or_str)
+            if not perm and ":" in perm_id_or_str:
+                res, act = perm_id_or_str.split(":", 1)
+                perm = repo.get_permission_by_resource_action(res, act)
+            
+            if perm:
+                new_role.permissions.append(perm)
+        
+        db.add(new_role)
+        db.commit()
+        db.refresh(new_role)
+        return new_role
+# [/DEF:create_role:Function]
+
+# [DEF:update_role:Function]
+# @PURPOSE: Updates an existing role's metadata and permissions.
+# @PRE:     role_id must be a valid existing role UUID.
+# @POST:    Role record is updated in auth.db.
+# @PARAM:   role_id (str) - Target role identifier.
+# @PARAM:   role_in (RoleUpdate) - Updated role data.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  RoleSchema - The updated role.
+# @SIDE_EFFECT: Commits updates to auth.db.
+# @RELATION: CALLS -> backend.src.core.auth.repository.AuthRepository.get_role_by_id
+@router.put("/roles/{role_id}", response_model=RoleSchema)
+async def update_role(
+    role_id: str,
+    role_in: RoleUpdate,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:roles", "WRITE"))
+):
+    with belief_scope("api.admin.update_role"):
+        repo = AuthRepository(db)
+        role = repo.get_role_by_id(role_id)
+        if not role:
+            raise HTTPException(status_code=404, detail="Role not found")
+        
+        if role_in.name is not None:
+            role.name = role_in.name
+        if role_in.description is not None:
+            role.description = role_in.description
+        
+        if role_in.permissions is not None:
+            role.permissions = []
+            for perm_id_or_str in role_in.permissions:
+                perm = repo.get_permission_by_id(perm_id_or_str)
+                if not perm and ":" in perm_id_or_str:
+                    res, act = perm_id_or_str.split(":", 1)
+                    perm = repo.get_permission_by_resource_action(res, act)
+                
+                if perm:
+                    role.permissions.append(perm)
+        
+        db.commit()
+        db.refresh(role)
+        return role
+# [/DEF:update_role:Function]
+
+# [DEF:delete_role:Function]
+# @PURPOSE: Removes a role from the system.
+# @PRE:     role_id must be a valid existing role UUID.
+# @POST:    Role record is removed from auth.db.
+# @PARAM:   role_id (str) - Target role identifier.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  None
+# @SIDE_EFFECT: Deletes record from auth.db and commits.
+# @RELATION: CALLS -> backend.src.core.auth.repository.AuthRepository.get_role_by_id
+@router.delete("/roles/{role_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_role(
+    role_id: str,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:roles", "WRITE"))
+):
+    with belief_scope("api.admin.delete_role"):
+        repo = AuthRepository(db)
+        role = repo.get_role_by_id(role_id)
+        if not role:
+            raise HTTPException(status_code=404, detail="Role not found")
+        
+        db.delete(role)
+        db.commit()
+        return None
+# [/DEF:delete_role:Function]
+
+# [DEF:list_permissions:Function]
+# @PURPOSE: Lists all available system permissions for assignment.
+# @POST:    Returns a list of all PermissionSchema objects.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  List[PermissionSchema] - List of permissions.
+# @RELATION: CALLS -> backend.src.core.auth.repository.AuthRepository.list_permissions
+@router.get("/permissions", response_model=List[PermissionSchema])
+async def list_permissions(
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:roles", "READ"))
+):
+    with belief_scope("api.admin.list_permissions"):
+        repo = AuthRepository(db)
+        return repo.list_permissions()
+# [/DEF:list_permissions:Function]
+
+# [DEF:list_ad_mappings:Function]
+# @PURPOSE: Lists all AD Group to Role mappings.
+@router.get("/ad-mappings", response_model=List[ADGroupMappingSchema])
+async def list_ad_mappings(
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("api.admin.list_ad_mappings"):
+        return db.query(ADGroupMapping).all()
+# [/DEF:list_ad_mappings:Function]
+
+# [DEF:create_ad_mapping:Function]
+# @PURPOSE: Creates a new AD Group mapping.
+@router.post("/ad-mappings", response_model=ADGroupMappingSchema)
+async def create_ad_mapping(
+    mapping_in: ADGroupMappingCreate,
+    db: Session = Depends(get_auth_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("api.admin.create_ad_mapping"):
+        new_mapping = ADGroupMapping(
+            ad_group=mapping_in.ad_group,
+            role_id=mapping_in.role_id
+        )
+        db.add(new_mapping)
+        db.commit()
+        db.refresh(new_mapping)
+        return new_mapping
+# [/DEF:create_ad_mapping:Function]
+
+# [/DEF:backend.src.api.routes.admin:Module]

backend/src/api/routes/connections.py

@@ -11,7 +11,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
 from ...core.database import get_db
 from ...models.connection import ConnectionConfig
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 from datetime import datetime
 from ...core.logger import logger, belief_scope
 # [/SECTION]

backend/src/api/routes/dashboards.py

@@ -0,0 +1,327 @@
+# [DEF:backend.src.api.routes.dashboards:Module]
+#
+# @TIER: STANDARD
+# @SEMANTICS: api, dashboards, resources, hub
+# @PURPOSE:   API endpoints for the Dashboard Hub - listing dashboards with Git and task status
+# @LAYER:     API
+# @RELATION:  DEPENDS_ON -> backend.src.dependencies
+# @RELATION:  DEPENDS_ON -> backend.src.services.resource_service
+# @RELATION:  DEPENDS_ON -> backend.src.core.superset_client
+#
+# @INVARIANT: All dashboard responses include git_status and last_task metadata
+
+# [SECTION: IMPORTS]
+from fastapi import APIRouter, Depends, HTTPException
+from typing import List, Optional, Dict
+from pydantic import BaseModel, Field
+from ...dependencies import get_config_manager, get_task_manager, get_resource_service, get_mapping_service, has_permission
+from ...core.logger import logger, belief_scope
+# [/SECTION]
+
+router = APIRouter(prefix="/api/dashboards", tags=["Dashboards"])
+
+# [DEF:GitStatus:DataClass]
+class GitStatus(BaseModel):
+    branch: Optional[str] = None
+    sync_status: Optional[str] = Field(None, pattern="^OK|DIFF$")
+# [/DEF:GitStatus:DataClass]
+
+# [DEF:LastTask:DataClass]
+class LastTask(BaseModel):
+    task_id: Optional[str] = None
+    status: Optional[str] = Field(None, pattern="^RUNNING|SUCCESS|ERROR|WAITING_INPUT$")
+# [/DEF:LastTask:DataClass]
+
+# [DEF:DashboardItem:DataClass]
+class DashboardItem(BaseModel):
+    id: int
+    title: str
+    slug: Optional[str] = None
+    url: Optional[str] = None
+    last_modified: Optional[str] = None
+    git_status: Optional[GitStatus] = None
+    last_task: Optional[LastTask] = None
+# [/DEF:DashboardItem:DataClass]
+
+# [DEF:DashboardsResponse:DataClass]
+class DashboardsResponse(BaseModel):
+    dashboards: List[DashboardItem]
+    total: int
+    page: int
+    page_size: int
+    total_pages: int
+# [/DEF:DashboardsResponse:DataClass]
+
+# [DEF:get_dashboards:Function]
+# @PURPOSE: Fetch list of dashboards from a specific environment with Git status and last task status
+# @PRE: env_id must be a valid environment ID
+# @PRE: page must be >= 1 if provided
+# @PRE: page_size must be between 1 and 100 if provided
+# @POST: Returns a list of dashboards with enhanced metadata and pagination info
+# @POST: Response includes pagination metadata (page, page_size, total, total_pages)
+# @PARAM: env_id (str) - The environment ID to fetch dashboards from
+# @PARAM: search (Optional[str]) - Filter by title/slug
+# @PARAM: page (Optional[int]) - Page number (default: 1)
+# @PARAM: page_size (Optional[int]) - Items per page (default: 10, max: 100)
+# @RETURN: DashboardsResponse - List of dashboards with status metadata
+# @RELATION: CALLS -> ResourceService.get_dashboards_with_status
+@router.get("", response_model=DashboardsResponse)
+async def get_dashboards(
+    env_id: str,
+    search: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    resource_service=Depends(get_resource_service),
+    _ = Depends(has_permission("plugin:migration", "READ"))
+):
+    with belief_scope("get_dashboards", f"env_id={env_id}, search={search}, page={page}, page_size={page_size}"):
+        # Validate pagination parameters
+        if page < 1:
+            logger.error(f"[get_dashboards][Coherence:Failed] Invalid page: {page}")
+            raise HTTPException(status_code=400, detail="Page must be >= 1")
+        if page_size < 1 or page_size > 100:
+            logger.error(f"[get_dashboards][Coherence:Failed] Invalid page_size: {page_size}")
+            raise HTTPException(status_code=400, detail="Page size must be between 1 and 100")
+        
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == env_id), None)
+        if not env:
+            logger.error(f"[get_dashboards][Coherence:Failed] Environment not found: {env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Get all tasks for status lookup
+            all_tasks = task_manager.get_all_tasks()
+            
+            # Fetch dashboards with status using ResourceService
+            dashboards = await resource_service.get_dashboards_with_status(env, all_tasks)
+            
+            # Apply search filter if provided
+            if search:
+                search_lower = search.lower()
+                dashboards = [
+                    d for d in dashboards 
+                    if search_lower in d.get('title', '').lower() 
+                    or search_lower in d.get('slug', '').lower()
+                ]
+            
+            # Calculate pagination
+            total = len(dashboards)
+            total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+            start_idx = (page - 1) * page_size
+            end_idx = start_idx + page_size
+            
+            # Slice dashboards for current page
+            paginated_dashboards = dashboards[start_idx:end_idx]
+            
+            logger.info(f"[get_dashboards][Coherence:OK] Returning {len(paginated_dashboards)} dashboards (page {page}/{total_pages}, total: {total})")
+            
+            return DashboardsResponse(
+                dashboards=paginated_dashboards,
+                total=total,
+                page=page,
+                page_size=page_size,
+                total_pages=total_pages
+            )
+            
+        except Exception as e:
+            logger.error(f"[get_dashboards][Coherence:Failed] Failed to fetch dashboards: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to fetch dashboards: {str(e)}")
+# [/DEF:get_dashboards:Function]
+
+# [DEF:MigrateRequest:DataClass]
+class MigrateRequest(BaseModel):
+    source_env_id: str = Field(..., description="Source environment ID")
+    target_env_id: str = Field(..., description="Target environment ID")
+    dashboard_ids: List[int] = Field(..., description="List of dashboard IDs to migrate")
+    db_mappings: Optional[Dict[str, str]] = Field(None, description="Database mappings for migration")
+    replace_db_config: bool = Field(False, description="Replace database configuration")
+# [/DEF:MigrateRequest:DataClass]
+
+# [DEF:TaskResponse:DataClass]
+class TaskResponse(BaseModel):
+    task_id: str
+# [/DEF:TaskResponse:DataClass]
+
+# [DEF:migrate_dashboards:Function]
+# @PURPOSE: Trigger bulk migration of dashboards from source to target environment
+# @PRE: User has permission plugin:migration:execute
+# @PRE: source_env_id and target_env_id are valid environment IDs
+# @PRE: dashboard_ids is a non-empty list
+# @POST: Returns task_id for tracking migration progress
+# @POST: Task is created and queued for execution
+# @PARAM: request (MigrateRequest) - Migration request with source, target, and dashboard IDs
+# @RETURN: TaskResponse - Task ID for tracking
+# @RELATION: DISPATCHES -> MigrationPlugin
+# @RELATION: CALLS -> task_manager.create_task
+@router.post("/migrate", response_model=TaskResponse)
+async def migrate_dashboards(
+    request: MigrateRequest,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    _ = Depends(has_permission("plugin:migration", "EXECUTE"))
+):
+    with belief_scope("migrate_dashboards", f"source={request.source_env_id}, target={request.target_env_id}, count={len(request.dashboard_ids)}"):
+        # Validate request
+        if not request.dashboard_ids:
+            logger.error("[migrate_dashboards][Coherence:Failed] No dashboard IDs provided")
+            raise HTTPException(status_code=400, detail="At least one dashboard ID must be provided")
+        
+        # Validate environments exist
+        environments = config_manager.get_environments()
+        source_env = next((e for e in environments if e.id == request.source_env_id), None)
+        target_env = next((e for e in environments if e.id == request.target_env_id), None)
+        
+        if not source_env:
+            logger.error(f"[migrate_dashboards][Coherence:Failed] Source environment not found: {request.source_env_id}")
+            raise HTTPException(status_code=404, detail="Source environment not found")
+        if not target_env:
+            logger.error(f"[migrate_dashboards][Coherence:Failed] Target environment not found: {request.target_env_id}")
+            raise HTTPException(status_code=404, detail="Target environment not found")
+        
+        try:
+            # Create migration task
+            task_params = {
+                'source_env_id': request.source_env_id,
+                'target_env_id': request.target_env_id,
+                'selected_ids': request.dashboard_ids,
+                'replace_db_config': request.replace_db_config,
+                'db_mappings': request.db_mappings or {}
+            }
+            
+            task_obj = await task_manager.create_task(
+                plugin_id='superset-migration',
+                params=task_params
+            )
+            
+            logger.info(f"[migrate_dashboards][Coherence:OK] Migration task created: {task_obj.id} for {len(request.dashboard_ids)} dashboards")
+            
+            return TaskResponse(task_id=str(task_obj.id))
+            
+        except Exception as e:
+            logger.error(f"[migrate_dashboards][Coherence:Failed] Failed to create migration task: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to create migration task: {str(e)}")
+# [/DEF:migrate_dashboards:Function]
+
+# [DEF:BackupRequest:DataClass]
+class BackupRequest(BaseModel):
+    env_id: str = Field(..., description="Environment ID")
+    dashboard_ids: List[int] = Field(..., description="List of dashboard IDs to backup")
+    schedule: Optional[str] = Field(None, description="Cron schedule for recurring backups (e.g., '0 0 * * *')")
+# [/DEF:BackupRequest:DataClass]
+
+# [DEF:backup_dashboards:Function]
+# @PURPOSE: Trigger bulk backup of dashboards with optional cron schedule
+# @PRE: User has permission plugin:backup:execute
+# @PRE: env_id is a valid environment ID
+# @PRE: dashboard_ids is a non-empty list
+# @POST: Returns task_id for tracking backup progress
+# @POST: Task is created and queued for execution
+# @POST: If schedule is provided, a scheduled task is created
+# @PARAM: request (BackupRequest) - Backup request with environment and dashboard IDs
+# @RETURN: TaskResponse - Task ID for tracking
+# @RELATION: DISPATCHES -> BackupPlugin
+# @RELATION: CALLS -> task_manager.create_task
+@router.post("/backup", response_model=TaskResponse)
+async def backup_dashboards(
+    request: BackupRequest,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    _ = Depends(has_permission("plugin:backup", "EXECUTE"))
+):
+    with belief_scope("backup_dashboards", f"env={request.env_id}, count={len(request.dashboard_ids)}, schedule={request.schedule}"):
+        # Validate request
+        if not request.dashboard_ids:
+            logger.error("[backup_dashboards][Coherence:Failed] No dashboard IDs provided")
+            raise HTTPException(status_code=400, detail="At least one dashboard ID must be provided")
+        
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == request.env_id), None)
+        
+        if not env:
+            logger.error(f"[backup_dashboards][Coherence:Failed] Environment not found: {request.env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Create backup task
+            task_params = {
+                'env': request.env_id,
+                'dashboards': request.dashboard_ids,
+                'schedule': request.schedule
+            }
+            
+            task_obj = await task_manager.create_task(
+                plugin_id='superset-backup',
+                params=task_params
+            )
+            
+            logger.info(f"[backup_dashboards][Coherence:OK] Backup task created: {task_obj.id} for {len(request.dashboard_ids)} dashboards")
+            
+            return TaskResponse(task_id=str(task_obj.id))
+            
+        except Exception as e:
+            logger.error(f"[backup_dashboards][Coherence:Failed] Failed to create backup task: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to create backup task: {str(e)}")
+# [/DEF:backup_dashboards:Function]
+
+# [DEF:DatabaseMapping:DataClass]
+class DatabaseMapping(BaseModel):
+    source_db: str
+    target_db: str
+    source_db_uuid: Optional[str] = None
+    target_db_uuid: Optional[str] = None
+    confidence: float
+# [/DEF:DatabaseMapping:DataClass]
+
+# [DEF:DatabaseMappingsResponse:DataClass]
+class DatabaseMappingsResponse(BaseModel):
+    mappings: List[DatabaseMapping]
+# [/DEF:DatabaseMappingsResponse:DataClass]
+
+# [DEF:get_database_mappings:Function]
+# @PURPOSE: Get database mapping suggestions between source and target environments
+# @PRE: User has permission plugin:migration:read
+# @PRE: source_env_id and target_env_id are valid environment IDs
+# @POST: Returns list of suggested database mappings with confidence scores
+# @PARAM: source_env_id (str) - Source environment ID
+# @PARAM: target_env_id (str) - Target environment ID
+# @RETURN: DatabaseMappingsResponse - List of suggested mappings
+# @RELATION: CALLS -> MappingService.get_suggestions
+@router.get("/db-mappings", response_model=DatabaseMappingsResponse)
+async def get_database_mappings(
+    source_env_id: str,
+    target_env_id: str,
+    mapping_service=Depends(get_mapping_service),
+    _ = Depends(has_permission("plugin:migration", "READ"))
+):
+    with belief_scope("get_database_mappings", f"source={source_env_id}, target={target_env_id}"):
+        try:
+            # Get mapping suggestions using MappingService
+            suggestions = await mapping_service.get_suggestions(source_env_id, target_env_id)
+            
+            # Format suggestions as DatabaseMapping objects
+            mappings = [
+                DatabaseMapping(
+                    source_db=s.get('source_db', ''),
+                    target_db=s.get('target_db', ''),
+                    source_db_uuid=s.get('source_db_uuid'),
+                    target_db_uuid=s.get('target_db_uuid'),
+                    confidence=s.get('confidence', 0.0)
+                )
+                for s in suggestions
+            ]
+            
+            logger.info(f"[get_database_mappings][Coherence:OK] Returning {len(mappings)} database mapping suggestions")
+            
+            return DatabaseMappingsResponse(mappings=mappings)
+            
+        except Exception as e:
+            logger.error(f"[get_database_mappings][Coherence:Failed] Failed to get database mappings: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to get database mappings: {str(e)}")
+# [/DEF:get_database_mappings:Function]
+
+# [/DEF:backend.src.api.routes.dashboards:Module]

backend/src/api/routes/datasets.py

@@ -0,0 +1,395 @@
+# [DEF:backend.src.api.routes.datasets:Module]
+#
+# @TIER: STANDARD
+# @SEMANTICS: api, datasets, resources, hub
+# @PURPOSE:   API endpoints for the Dataset Hub - listing datasets with mapping progress
+# @LAYER:     API
+# @RELATION:  DEPENDS_ON -> backend.src.dependencies
+# @RELATION:  DEPENDS_ON -> backend.src.services.resource_service
+# @RELATION:  DEPENDS_ON -> backend.src.core.superset_client
+#
+# @INVARIANT: All dataset responses include last_task metadata
+
+# [SECTION: IMPORTS]
+from fastapi import APIRouter, Depends, HTTPException
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from ...dependencies import get_config_manager, get_task_manager, get_resource_service, has_permission
+from ...core.logger import logger, belief_scope
+from ...core.superset_client import SupersetClient
+# [/SECTION]
+
+router = APIRouter(prefix="/api/datasets", tags=["Datasets"])
+
+# [DEF:MappedFields:DataClass]
+class MappedFields(BaseModel):
+    total: int
+    mapped: int
+# [/DEF:MappedFields:DataClass]
+
+# [DEF:LastTask:DataClass]
+class LastTask(BaseModel):
+    task_id: Optional[str] = None
+    status: Optional[str] = Field(None, pattern="^RUNNING|SUCCESS|ERROR|WAITING_INPUT$")
+# [/DEF:LastTask:DataClass]
+
+# [DEF:DatasetItem:DataClass]
+class DatasetItem(BaseModel):
+    id: int
+    table_name: str
+    schema: str
+    database: str
+    mapped_fields: Optional[MappedFields] = None
+    last_task: Optional[LastTask] = None
+# [/DEF:DatasetItem:DataClass]
+
+# [DEF:LinkedDashboard:DataClass]
+class LinkedDashboard(BaseModel):
+    id: int
+    title: str
+    slug: Optional[str] = None
+# [/DEF:LinkedDashboard:DataClass]
+
+# [DEF:DatasetColumn:DataClass]
+class DatasetColumn(BaseModel):
+    id: int
+    name: str
+    type: Optional[str] = None
+    is_dttm: bool = False
+    is_active: bool = True
+    description: Optional[str] = None
+# [/DEF:DatasetColumn:DataClass]
+
+# [DEF:DatasetDetailResponse:DataClass]
+class DatasetDetailResponse(BaseModel):
+    id: int
+    table_name: Optional[str] = None
+    schema: Optional[str] = None
+    database: str
+    description: Optional[str] = None
+    columns: List[DatasetColumn]
+    column_count: int
+    sql: Optional[str] = None
+    linked_dashboards: List[LinkedDashboard]
+    linked_dashboard_count: int
+    is_sqllab_view: bool = False
+    created_on: Optional[str] = None
+    changed_on: Optional[str] = None
+# [/DEF:DatasetDetailResponse:DataClass]
+
+# [DEF:DatasetsResponse:DataClass]
+class DatasetsResponse(BaseModel):
+    datasets: List[DatasetItem]
+    total: int
+    page: int
+    page_size: int
+    total_pages: int
+# [/DEF:DatasetsResponse:DataClass]
+
+# [DEF:TaskResponse:DataClass]
+class TaskResponse(BaseModel):
+    task_id: str
+# [/DEF:TaskResponse:DataClass]
+
+# [DEF:get_dataset_ids:Function]
+# @PURPOSE: Fetch list of all dataset IDs from a specific environment (without pagination)
+# @PRE: env_id must be a valid environment ID
+# @POST: Returns a list of all dataset IDs
+# @PARAM: env_id (str) - The environment ID to fetch datasets from
+# @PARAM: search (Optional[str]) - Filter by table name
+# @RETURN: List[int] - List of dataset IDs
+# @RELATION: CALLS -> ResourceService.get_datasets_with_status
+@router.get("/ids")
+async def get_dataset_ids(
+    env_id: str,
+    search: Optional[str] = None,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    resource_service=Depends(get_resource_service),
+    _ = Depends(has_permission("plugin:migration", "READ"))
+):
+    with belief_scope("get_dataset_ids", f"env_id={env_id}, search={search}"):
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == env_id), None)
+        if not env:
+            logger.error(f"[get_dataset_ids][Coherence:Failed] Environment not found: {env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Get all tasks for status lookup
+            all_tasks = task_manager.get_all_tasks()
+            
+            # Fetch datasets with status using ResourceService
+            datasets = await resource_service.get_datasets_with_status(env, all_tasks)
+            
+            # Apply search filter if provided
+            if search:
+                search_lower = search.lower()
+                datasets = [
+                    d for d in datasets 
+                    if search_lower in d.get('table_name', '').lower()
+                ]
+            
+            # Extract and return just the IDs
+            dataset_ids = [d['id'] for d in datasets]
+            logger.info(f"[get_dataset_ids][Coherence:OK] Returning {len(dataset_ids)} dataset IDs")
+            
+            return {"dataset_ids": dataset_ids}
+            
+        except Exception as e:
+            logger.error(f"[get_dataset_ids][Coherence:Failed] Failed to fetch dataset IDs: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to fetch dataset IDs: {str(e)}")
+# [/DEF:get_dataset_ids:Function]
+
+# [DEF:get_datasets:Function]
+# @PURPOSE: Fetch list of datasets from a specific environment with mapping progress
+# @PRE: env_id must be a valid environment ID
+# @PRE: page must be >= 1 if provided
+# @PRE: page_size must be between 1 and 100 if provided
+# @POST: Returns a list of datasets with enhanced metadata and pagination info
+# @POST: Response includes pagination metadata (page, page_size, total, total_pages)
+# @PARAM: env_id (str) - The environment ID to fetch datasets from
+# @PARAM: search (Optional[str]) - Filter by table name
+# @PARAM: page (Optional[int]) - Page number (default: 1)
+# @PARAM: page_size (Optional[int]) - Items per page (default: 10, max: 100)
+# @RETURN: DatasetsResponse - List of datasets with status metadata
+# @RELATION: CALLS -> ResourceService.get_datasets_with_status
+@router.get("", response_model=DatasetsResponse)
+async def get_datasets(
+    env_id: str,
+    search: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    resource_service=Depends(get_resource_service),
+    _ = Depends(has_permission("plugin:migration", "READ"))
+):
+    with belief_scope("get_datasets", f"env_id={env_id}, search={search}, page={page}, page_size={page_size}"):
+        # Validate pagination parameters
+        if page < 1:
+            logger.error(f"[get_datasets][Coherence:Failed] Invalid page: {page}")
+            raise HTTPException(status_code=400, detail="Page must be >= 1")
+        if page_size < 1 or page_size > 100:
+            logger.error(f"[get_datasets][Coherence:Failed] Invalid page_size: {page_size}")
+            raise HTTPException(status_code=400, detail="Page size must be between 1 and 100")
+        
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == env_id), None)
+        if not env:
+            logger.error(f"[get_datasets][Coherence:Failed] Environment not found: {env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Get all tasks for status lookup
+            all_tasks = task_manager.get_all_tasks()
+            
+            # Fetch datasets with status using ResourceService
+            datasets = await resource_service.get_datasets_with_status(env, all_tasks)
+            
+            # Apply search filter if provided
+            if search:
+                search_lower = search.lower()
+                datasets = [
+                    d for d in datasets 
+                    if search_lower in d.get('table_name', '').lower()
+                ]
+            
+            # Calculate pagination
+            total = len(datasets)
+            total_pages = (total + page_size - 1) // page_size if total > 0 else 1
+            start_idx = (page - 1) * page_size
+            end_idx = start_idx + page_size
+            
+            # Slice datasets for current page
+            paginated_datasets = datasets[start_idx:end_idx]
+            
+            logger.info(f"[get_datasets][Coherence:OK] Returning {len(paginated_datasets)} datasets (page {page}/{total_pages}, total: {total})")
+            
+            return DatasetsResponse(
+                datasets=paginated_datasets,
+                total=total,
+                page=page,
+                page_size=page_size,
+                total_pages=total_pages
+            )
+            
+        except Exception as e:
+            logger.error(f"[get_datasets][Coherence:Failed] Failed to fetch datasets: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to fetch datasets: {str(e)}")
+# [/DEF:get_datasets:Function]
+
+# [DEF:MapColumnsRequest:DataClass]
+class MapColumnsRequest(BaseModel):
+    env_id: str = Field(..., description="Environment ID")
+    dataset_ids: List[int] = Field(..., description="List of dataset IDs to map")
+    source_type: str = Field(..., description="Source type: 'postgresql' or 'xlsx'")
+    connection_id: Optional[str] = Field(None, description="Connection ID for PostgreSQL source")
+    file_data: Optional[str] = Field(None, description="File path or data for XLSX source")
+# [/DEF:MapColumnsRequest:DataClass]
+
+# [DEF:map_columns:Function]
+# @PURPOSE: Trigger bulk column mapping for datasets
+# @PRE: User has permission plugin:mapper:execute
+# @PRE: env_id is a valid environment ID
+# @PRE: dataset_ids is a non-empty list
+# @POST: Returns task_id for tracking mapping progress
+# @POST: Task is created and queued for execution
+# @PARAM: request (MapColumnsRequest) - Mapping request with environment and dataset IDs
+# @RETURN: TaskResponse - Task ID for tracking
+# @RELATION: DISPATCHES -> MapperPlugin
+# @RELATION: CALLS -> task_manager.create_task
+@router.post("/map-columns", response_model=TaskResponse)
+async def map_columns(
+    request: MapColumnsRequest,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    _ = Depends(has_permission("plugin:mapper", "EXECUTE"))
+):
+    with belief_scope("map_columns", f"env={request.env_id}, count={len(request.dataset_ids)}, source={request.source_type}"):
+        # Validate request
+        if not request.dataset_ids:
+            logger.error("[map_columns][Coherence:Failed] No dataset IDs provided")
+            raise HTTPException(status_code=400, detail="At least one dataset ID must be provided")
+        
+        # Validate source type
+        if request.source_type not in ['postgresql', 'xlsx']:
+            logger.error(f"[map_columns][Coherence:Failed] Invalid source type: {request.source_type}")
+            raise HTTPException(status_code=400, detail="Source type must be 'postgresql' or 'xlsx'")
+        
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == request.env_id), None)
+        
+        if not env:
+            logger.error(f"[map_columns][Coherence:Failed] Environment not found: {request.env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Create mapping task
+            task_params = {
+                'env': request.env_id,
+                'dataset_id': request.dataset_ids[0] if request.dataset_ids else None,
+                'source': request.source_type,
+                'connection_id': request.connection_id,
+                'file_data': request.file_data
+            }
+            
+            task_obj = await task_manager.create_task(
+                plugin_id='dataset-mapper',
+                params=task_params
+            )
+            
+            logger.info(f"[map_columns][Coherence:OK] Mapping task created: {task_obj.id} for {len(request.dataset_ids)} datasets")
+            
+            return TaskResponse(task_id=str(task_obj.id))
+            
+        except Exception as e:
+            logger.error(f"[map_columns][Coherence:Failed] Failed to create mapping task: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to create mapping task: {str(e)}")
+# [/DEF:map_columns:Function]
+
+# [DEF:GenerateDocsRequest:DataClass]
+class GenerateDocsRequest(BaseModel):
+    env_id: str = Field(..., description="Environment ID")
+    dataset_ids: List[int] = Field(..., description="List of dataset IDs to generate docs for")
+    llm_provider: str = Field(..., description="LLM provider to use")
+    options: Optional[dict] = Field(None, description="Additional options for documentation generation")
+# [/DEF:GenerateDocsRequest:DataClass]
+
+# [DEF:generate_docs:Function]
+# @PURPOSE: Trigger bulk documentation generation for datasets
+# @PRE: User has permission plugin:llm_analysis:execute
+# @PRE: env_id is a valid environment ID
+# @PRE: dataset_ids is a non-empty list
+# @POST: Returns task_id for tracking documentation generation progress
+# @POST: Task is created and queued for execution
+# @PARAM: request (GenerateDocsRequest) - Documentation generation request
+# @RETURN: TaskResponse - Task ID for tracking
+# @RELATION: DISPATCHES -> LLMAnalysisPlugin
+# @RELATION: CALLS -> task_manager.create_task
+@router.post("/generate-docs", response_model=TaskResponse)
+async def generate_docs(
+    request: GenerateDocsRequest,
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    _ = Depends(has_permission("plugin:llm_analysis", "EXECUTE"))
+):
+    with belief_scope("generate_docs", f"env={request.env_id}, count={len(request.dataset_ids)}, provider={request.llm_provider}"):
+        # Validate request
+        if not request.dataset_ids:
+            logger.error("[generate_docs][Coherence:Failed] No dataset IDs provided")
+            raise HTTPException(status_code=400, detail="At least one dataset ID must be provided")
+        
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == request.env_id), None)
+        
+        if not env:
+            logger.error(f"[generate_docs][Coherence:Failed] Environment not found: {request.env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Create documentation generation task
+            task_params = {
+                'environment_id': request.env_id,
+                'dataset_id': str(request.dataset_ids[0]) if request.dataset_ids else None,
+                'provider_id': request.llm_provider,
+                'options': request.options or {}
+            }
+            
+            task_obj = await task_manager.create_task(
+                plugin_id='llm_documentation',
+                params=task_params
+            )
+            
+            logger.info(f"[generate_docs][Coherence:OK] Documentation generation task created: {task_obj.id} for {len(request.dataset_ids)} datasets")
+            
+            return TaskResponse(task_id=str(task_obj.id))
+            
+        except Exception as e:
+            logger.error(f"[generate_docs][Coherence:Failed] Failed to create documentation generation task: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to create documentation generation task: {str(e)}")
+# [/DEF:generate_docs:Function]
+
+# [DEF:get_dataset_detail:Function]
+# @PURPOSE: Get detailed dataset information including columns and linked dashboards
+# @PRE: env_id is a valid environment ID
+# @PRE: dataset_id is a valid dataset ID
+# @POST: Returns detailed dataset info with columns and linked dashboards
+# @PARAM: env_id (str) - The environment ID
+# @PARAM: dataset_id (int) - The dataset ID
+# @RETURN: DatasetDetailResponse - Detailed dataset information
+# @RELATION: CALLS -> SupersetClient.get_dataset_detail
+@router.get("/{dataset_id}", response_model=DatasetDetailResponse)
+async def get_dataset_detail(
+    env_id: str,
+    dataset_id: int,
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("plugin:migration", "READ"))
+):
+    with belief_scope("get_dataset_detail", f"env_id={env_id}, dataset_id={dataset_id}"):
+        # Validate environment exists
+        environments = config_manager.get_environments()
+        env = next((e for e in environments if e.id == env_id), None)
+        if not env:
+            logger.error(f"[get_dataset_detail][Coherence:Failed] Environment not found: {env_id}")
+            raise HTTPException(status_code=404, detail="Environment not found")
+        
+        try:
+            # Fetch detailed dataset info using SupersetClient
+            client = SupersetClient(env)
+            dataset_detail = client.get_dataset_detail(dataset_id)
+            
+            logger.info(f"[get_dataset_detail][Coherence:OK] Retrieved dataset {dataset_id} with {dataset_detail['column_count']} columns and {dataset_detail['linked_dashboard_count']} linked dashboards")
+            
+            return DatasetDetailResponse(**dataset_detail)
+            
+        except Exception as e:
+            logger.error(f"[get_dataset_detail][Coherence:Failed] Failed to fetch dataset detail: {e}")
+            raise HTTPException(status_code=503, detail=f"Failed to fetch dataset detail: {str(e)}")
+# [/DEF:get_dataset_detail:Function]
+
+# [/DEF:backend.src.api.routes.datasets:Module]

backend/src/api/routes/environments.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.api.routes.environments:Module]
 #
+# @TIER: STANDARD
 # @SEMANTICS: api, environments, superset, databases
 # @PURPOSE:   API endpoints for listing environments and their databases.
 # @LAYER:     API
@@ -10,20 +11,19 @@
 
 # [SECTION: IMPORTS]
 from fastapi import APIRouter, Depends, HTTPException
-from typing import List, Dict, Optional
+from typing import List, Optional
-from ...dependencies import get_config_manager, get_scheduler_service
+from ...dependencies import get_config_manager, get_scheduler_service, has_permission
 from ...core.superset_client import SupersetClient
 from pydantic import BaseModel, Field
-from ...core.config_models import Environment as EnvModel
 from ...core.logger import belief_scope
 # [/SECTION]
 
-router = APIRouter()
+router = APIRouter(prefix="/api/environments", tags=["Environments"])
 
 # [DEF:ScheduleSchema:DataClass]
 class ScheduleSchema(BaseModel):
     enabled: bool = False
-    cron_expression: str = Field(..., pattern=r'^(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|((((\d+,)*\d+|(\d+(\/|-)\d+)|\d+|\*) ?){5,7})$')
+    cron_expression: str = Field(..., pattern=r'^(@(annually|yearly|monthly|weekly|daily|hourly|reboot))|((((\d+,)*\d+|(\d+(\/|-)\d+)|\d+|\*) ?){4,6})$')
 # [/DEF:ScheduleSchema:DataClass]
 
 # [DEF:EnvironmentResponse:DataClass]
@@ -43,11 +43,16 @@ class DatabaseResponse(BaseModel):
 
 # [DEF:get_environments:Function]
 # @PURPOSE: List all configured environments.
+# @LAYER: API
+# @SEMANTICS: list, environments, config
 # @PRE:     config_manager is injected via Depends.
 # @POST:    Returns a list of EnvironmentResponse objects.
 # @RETURN:  List[EnvironmentResponse]
 @router.get("", response_model=List[EnvironmentResponse])
-async def get_environments(config_manager=Depends(get_config_manager)):
+async def get_environments(
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("environments", "READ"))
+):
     with belief_scope("get_environments"):
         envs = config_manager.get_environments()
     # Ensure envs is a list
@@ -61,13 +66,15 @@ async def get_environments(config_manager=Depends(get_config_manager)):
             backup_schedule=ScheduleSchema(
                 enabled=e.backup_schedule.enabled,
                 cron_expression=e.backup_schedule.cron_expression
-            ) if e.backup_schedule else None
+            ) if getattr(e, 'backup_schedule', None) else None
         ) for e in envs
     ]
 # [/DEF:get_environments:Function]
 
 # [DEF:update_environment_schedule:Function]
 # @PURPOSE: Update backup schedule for an environment.
+# @LAYER: API
+# @SEMANTICS: update, schedule, backup, environment
 # @PRE:     Environment id exists, schedule is valid ScheduleSchema.
 # @POST:    Backup schedule updated and scheduler reloaded.
 # @PARAM:   id (str) - The environment ID.
@@ -77,7 +84,8 @@ async def update_environment_schedule(
     id: str,
     schedule: ScheduleSchema,
     config_manager=Depends(get_config_manager),
-    scheduler_service=Depends(get_scheduler_service)
+    scheduler_service=Depends(get_scheduler_service),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
 ):
     with belief_scope("update_environment_schedule", f"id={id}"):
         envs = config_manager.get_environments()
@@ -99,12 +107,18 @@ async def update_environment_schedule(
 
 # [DEF:get_environment_databases:Function]
 # @PURPOSE: Fetch the list of databases from a specific environment.
+# @LAYER: API
+# @SEMANTICS: fetch, databases, superset, environment
 # @PRE:     Environment id exists.
 # @POST:    Returns a list of database summaries from the environment.
 # @PARAM:   id (str) - The environment ID.
 # @RETURN:  List[Dict] - List of databases.
 @router.get("/{id}/databases")
-async def get_environment_databases(id: str, config_manager=Depends(get_config_manager)):
+async def get_environment_databases(
+    id: str,
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
     with belief_scope("get_environment_databases", f"id={id}"):
         envs = config_manager.get_environments()
     env = next((e for e in envs if e.id == id), None)

backend/src/api/routes/git.py

@@ -0,0 +1,456 @@
+# [DEF:backend.src.api.routes.git:Module]
+#
+# @TIER: STANDARD
+# @SEMANTICS: git, routes, api, fastapi, repository, deployment
+# @PURPOSE:   Provides FastAPI endpoints for Git integration operations.
+# @LAYER:     API
+# @RELATION:  USES -> src.services.git_service.GitService
+# @RELATION:  USES -> src.api.routes.git_schemas
+# @RELATION:  USES -> src.models.git
+#
+# @INVARIANT: All Git operations must be routed through GitService.
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from typing import List, Optional
+import typing
+from src.dependencies import get_config_manager, has_permission
+from src.core.database import get_db
+from src.models.git import GitServerConfig, GitRepository
+from src.api.routes.git_schemas import (
+    GitServerConfigSchema, GitServerConfigCreate,
+    BranchSchema, BranchCreate,
+    BranchCheckout, CommitSchema, CommitCreate,
+    DeploymentEnvironmentSchema, DeployRequest, RepoInitRequest
+)
+from src.services.git_service import GitService
+from src.core.logger import logger, belief_scope
+
+router = APIRouter(tags=["git"])
+git_service = GitService()
+
+# [DEF:get_git_configs:Function]
+# @PURPOSE: List all configured Git servers.
+# @PRE: Database session `db` is available.
+# @POST: Returns a list of all GitServerConfig objects from the database.
+# @RETURN: List[GitServerConfigSchema]
+@router.get("/config", response_model=List[GitServerConfigSchema])
+async def get_git_configs(
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("get_git_configs"):
+        return db.query(GitServerConfig).all()
+# [/DEF:get_git_configs:Function]
+
+# [DEF:create_git_config:Function]
+# @PURPOSE: Register a new Git server configuration.
+# @PRE: `config` contains valid GitServerConfigCreate data.
+# @POST: A new GitServerConfig record is created in the database.
+# @PARAM: config (GitServerConfigCreate)
+# @RETURN: GitServerConfigSchema
+@router.post("/config", response_model=GitServerConfigSchema)
+async def create_git_config(
+    config: GitServerConfigCreate,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("create_git_config"):
+        db_config = GitServerConfig(**config.dict())
+        db.add(db_config)
+        db.commit()
+        db.refresh(db_config)
+        return db_config
+# [/DEF:create_git_config:Function]
+
+# [DEF:delete_git_config:Function]
+# @PURPOSE: Remove a Git server configuration.
+# @PRE: `config_id` corresponds to an existing configuration.
+# @POST: The configuration record is removed from the database.
+# @PARAM: config_id (str)
+@router.delete("/config/{config_id}")
+async def delete_git_config(
+    config_id: str,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("delete_git_config"):
+        db_config = db.query(GitServerConfig).filter(GitServerConfig.id == config_id).first()
+        if not db_config:
+            raise HTTPException(status_code=404, detail="Configuration not found")
+        
+        db.delete(db_config)
+        db.commit()
+        return {"status": "success", "message": "Configuration deleted"}
+# [/DEF:delete_git_config:Function]
+
+# [DEF:test_git_config:Function]
+# @PURPOSE: Validate connection to a Git server using provided credentials.
+# @PRE: `config` contains provider, url, and pat.
+# @POST: Returns success if the connection is validated via GitService.
+# @PARAM: config (GitServerConfigCreate)
+@router.post("/config/test")
+async def test_git_config(
+    config: GitServerConfigCreate,
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("test_git_config"):
+        success = await git_service.test_connection(config.provider, config.url, config.pat)
+        if success:
+            return {"status": "success", "message": "Connection successful"}
+        else:
+            raise HTTPException(status_code=400, detail="Connection failed")
+# [/DEF:test_git_config:Function]
+
+# [DEF:init_repository:Function]
+# @PURPOSE: Link a dashboard to a Git repository and perform initial clone/init.
+# @PRE: `dashboard_id` exists and `init_data` contains valid config_id and remote_url.
+# @POST: Repository is initialized on disk and a GitRepository record is saved in DB.
+# @PARAM: dashboard_id (int)
+# @PARAM: init_data (RepoInitRequest)
+@router.post("/repositories/{dashboard_id}/init")
+async def init_repository(
+    dashboard_id: int,
+    init_data: RepoInitRequest,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("init_repository"):
+        # 1. Get config
+        config = db.query(GitServerConfig).filter(GitServerConfig.id == init_data.config_id).first()
+        if not config:
+            raise HTTPException(status_code=404, detail="Git configuration not found")
+        
+        try:
+            # 2. Perform Git clone/init
+            logger.info(f"[init_repository][Action] Initializing repo for dashboard {dashboard_id}")
+            git_service.init_repo(dashboard_id, init_data.remote_url, config.pat)
+            
+            # 3. Save to DB
+            repo_path = git_service._get_repo_path(dashboard_id)
+            db_repo = db.query(GitRepository).filter(GitRepository.dashboard_id == dashboard_id).first()
+            if not db_repo:
+                db_repo = GitRepository(
+                    dashboard_id=dashboard_id,
+                    config_id=config.id,
+                    remote_url=init_data.remote_url,
+                    local_path=repo_path
+                )
+                db.add(db_repo)
+            else:
+                db_repo.config_id = config.id
+                db_repo.remote_url = init_data.remote_url
+                db_repo.local_path = repo_path
+            
+            db.commit()
+            logger.info(f"[init_repository][Coherence:OK] Repository initialized for dashboard {dashboard_id}")
+            return {"status": "success", "message": "Repository initialized"}
+        except Exception as e:
+            db.rollback()
+            logger.error(f"[init_repository][Coherence:Failed] Failed to init repository: {e}")
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:init_repository:Function]
+
+# [DEF:get_branches:Function]
+# @PURPOSE: List all branches for a dashboard's repository.
+# @PRE: Repository for `dashboard_id` is initialized.
+# @POST: Returns a list of branches from the local repository.
+# @PARAM: dashboard_id (int)
+# @RETURN: List[BranchSchema]
+@router.get("/repositories/{dashboard_id}/branches", response_model=List[BranchSchema])
+async def get_branches(
+    dashboard_id: int,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("get_branches"):
+        try:
+            return git_service.list_branches(dashboard_id)
+        except Exception as e:
+            raise HTTPException(status_code=404, detail=str(e))
+# [/DEF:get_branches:Function]
+
+# [DEF:create_branch:Function]
+# @PURPOSE: Create a new branch in the dashboard's repository.
+# @PRE: `dashboard_id` repository exists and `branch_data` has name and from_branch.
+# @POST: A new branch is created in the local repository.
+# @PARAM: dashboard_id (int)
+# @PARAM: branch_data (BranchCreate)
+@router.post("/repositories/{dashboard_id}/branches")
+async def create_branch(
+    dashboard_id: int,
+    branch_data: BranchCreate,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("create_branch"):
+        try:
+            git_service.create_branch(dashboard_id, branch_data.name, branch_data.from_branch)
+            return {"status": "success"}
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:create_branch:Function]
+
+# [DEF:checkout_branch:Function]
+# @PURPOSE: Switch the dashboard's repository to a specific branch.
+# @PRE: `dashboard_id` repository exists and branch `checkout_data.name` exists.
+# @POST: The local repository HEAD is moved to the specified branch.
+# @PARAM: dashboard_id (int)
+# @PARAM: checkout_data (BranchCheckout)
+@router.post("/repositories/{dashboard_id}/checkout")
+async def checkout_branch(
+    dashboard_id: int,
+    checkout_data: BranchCheckout,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("checkout_branch"):
+        try:
+            git_service.checkout_branch(dashboard_id, checkout_data.name)
+            return {"status": "success"}
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:checkout_branch:Function]
+
+# [DEF:commit_changes:Function]
+# @PURPOSE: Stage and commit changes in the dashboard's repository.
+# @PRE: `dashboard_id` repository exists and `commit_data` has message and files.
+# @POST: Specified files are staged and a new commit is created.
+# @PARAM: dashboard_id (int)
+# @PARAM: commit_data (CommitCreate)
+@router.post("/repositories/{dashboard_id}/commit")
+async def commit_changes(
+    dashboard_id: int,
+    commit_data: CommitCreate,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("commit_changes"):
+        try:
+            git_service.commit_changes(dashboard_id, commit_data.message, commit_data.files)
+            return {"status": "success"}
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:commit_changes:Function]
+
+# [DEF:push_changes:Function]
+# @PURPOSE: Push local commits to the remote repository.
+# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @POST: Local commits are pushed to the remote repository.
+# @PARAM: dashboard_id (int)
+@router.post("/repositories/{dashboard_id}/push")
+async def push_changes(
+    dashboard_id: int,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("push_changes"):
+        try:
+            git_service.push_changes(dashboard_id)
+            return {"status": "success"}
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:push_changes:Function]
+
+# [DEF:pull_changes:Function]
+# @PURPOSE: Pull changes from the remote repository.
+# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @POST: Remote changes are fetched and merged into the local branch.
+# @PARAM: dashboard_id (int)
+@router.post("/repositories/{dashboard_id}/pull")
+async def pull_changes(
+    dashboard_id: int,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("pull_changes"):
+        try:
+            git_service.pull_changes(dashboard_id)
+            return {"status": "success"}
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:pull_changes:Function]
+
+# [DEF:sync_dashboard:Function]
+# @PURPOSE: Sync dashboard state from Superset to Git using the GitPlugin.
+# @PRE: `dashboard_id` is valid; GitPlugin is available.
+# @POST: Dashboard YAMLs are exported from Superset and committed to Git.
+# @PARAM: dashboard_id (int)
+# @PARAM: source_env_id (Optional[str])
+@router.post("/repositories/{dashboard_id}/sync")
+async def sync_dashboard(
+    dashboard_id: int,
+    source_env_id: typing.Optional[str] = None,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("sync_dashboard"):
+        try:
+            from src.plugins.git_plugin import GitPlugin
+            plugin = GitPlugin()
+            return await plugin.execute({
+                "operation": "sync",
+                "dashboard_id": dashboard_id,
+                "source_env_id": source_env_id
+            })
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:sync_dashboard:Function]
+
+# [DEF:get_environments:Function]
+# @PURPOSE: List all deployment environments.
+# @PRE: Config manager is accessible.
+# @POST: Returns a list of DeploymentEnvironmentSchema objects.
+# @RETURN: List[DeploymentEnvironmentSchema]
+@router.get("/environments", response_model=List[DeploymentEnvironmentSchema])
+async def get_environments(
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("environments", "READ"))
+):
+    with belief_scope("get_environments"):
+        envs = config_manager.get_environments()
+        return [
+            DeploymentEnvironmentSchema(
+                id=e.id,
+                name=e.name,
+                superset_url=e.url,
+                is_active=True
+            ) for e in envs
+        ]
+# [/DEF:get_environments:Function]
+
+# [DEF:deploy_dashboard:Function]
+# @PURPOSE: Deploy dashboard from Git to a target environment.
+# @PRE: `dashboard_id` and `deploy_data.environment_id` are valid.
+# @POST: Dashboard YAMLs are read from Git and imported into the target Superset.
+# @PARAM: dashboard_id (int)
+# @PARAM: deploy_data (DeployRequest)
+@router.post("/repositories/{dashboard_id}/deploy")
+async def deploy_dashboard(
+    dashboard_id: int,
+    deploy_data: DeployRequest,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("deploy_dashboard"):
+        try:
+            from src.plugins.git_plugin import GitPlugin
+            plugin = GitPlugin()
+            return await plugin.execute({
+                "operation": "deploy", 
+                "dashboard_id": dashboard_id,
+                "environment_id": deploy_data.environment_id
+            })
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:deploy_dashboard:Function]
+
+# [DEF:get_history:Function]
+# @PURPOSE: View commit history for a dashboard's repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns a list of recent commits from the repository.
+# @PARAM: dashboard_id (int)
+# @PARAM: limit (int)
+# @RETURN: List[CommitSchema]
+@router.get("/repositories/{dashboard_id}/history", response_model=List[CommitSchema])
+async def get_history(
+    dashboard_id: int,
+    limit: int = 50,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("get_history"):
+        try:
+            return git_service.get_commit_history(dashboard_id, limit)
+        except Exception as e:
+            raise HTTPException(status_code=404, detail=str(e))
+# [/DEF:get_history:Function]
+
+# [DEF:get_repository_status:Function]
+# @PURPOSE: Get current Git status for a dashboard repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns the status of the working directory (staged, unstaged, untracked).
+# @PARAM: dashboard_id (int)
+# @RETURN: dict
+@router.get("/repositories/{dashboard_id}/status")
+async def get_repository_status(
+    dashboard_id: int,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("get_repository_status"):
+        try:
+            return git_service.get_status(dashboard_id)
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:get_repository_status:Function]
+
+# [DEF:get_repository_diff:Function]
+# @PURPOSE: Get Git diff for a dashboard repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns the diff text for the specified file or all changes.
+# @PARAM: dashboard_id (int)
+# @PARAM: file_path (Optional[str])
+# @PARAM: staged (bool)
+# @RETURN: str
+@router.get("/repositories/{dashboard_id}/diff")
+async def get_repository_diff(
+    dashboard_id: int,
+    file_path: Optional[str] = None,
+    staged: bool = False,
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("get_repository_diff"):
+        try:
+            diff_text = git_service.get_diff(dashboard_id, file_path, staged)
+            return diff_text
+        except Exception as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:get_repository_diff:Function]
+
+# [DEF:generate_commit_message:Function]
+# @PURPOSE: Generate a suggested commit message using LLM.
+# @PRE: Repository for `dashboard_id` is initialized.
+# @POST: Returns a suggested commit message string.
+@router.post("/repositories/{dashboard_id}/generate-message")
+async def generate_commit_message(
+    dashboard_id: int,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:git", "EXECUTE"))
+):
+    with belief_scope("generate_commit_message"):
+        try:
+            # 1. Get Diff
+            diff = git_service.get_diff(dashboard_id, staged=True)
+            if not diff:
+                diff = git_service.get_diff(dashboard_id, staged=False)
+            
+            if not diff:
+                return {"message": "No changes detected"}
+
+            # 2. Get History
+            history_objs = git_service.get_commit_history(dashboard_id, limit=5)
+            history = [h.message for h in history_objs if hasattr(h, 'message')]
+
+            # 3. Get LLM Client
+            from ...services.llm_provider import LLMProviderService
+            from ...plugins.llm_analysis.service import LLMClient
+            from ...plugins.llm_analysis.models import LLMProviderType
+            
+            llm_service = LLMProviderService(db)
+            providers = llm_service.get_all_providers()
+            provider = next((p for p in providers if p.is_active), None)
+            
+            if not provider:
+                raise HTTPException(status_code=400, detail="No active LLM provider found")
+            
+            api_key = llm_service.get_decrypted_api_key(provider.id)
+            client = LLMClient(
+                provider_type=LLMProviderType(provider.provider_type),
+                api_key=api_key,
+                base_url=provider.base_url,
+                default_model=provider.default_model
+            )
+
+            # 4. Generate Message
+            from ...plugins.git.llm_extension import GitLLMExtension
+            extension = GitLLMExtension(client)
+            message = await extension.suggest_commit_message(diff, history)
+            
+            return {"message": message}
+        except Exception as e:
+            logger.error(f"Failed to generate commit message: {e}")
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:generate_commit_message:Function]
+
+# [/DEF:backend.src.api.routes.git:Module]

backend/src/api/routes/git_schemas.py

@@ -0,0 +1,144 @@
+# [DEF:backend.src.api.routes.git_schemas:Module]
+#
+# @TIER:      STANDARD
+# @SEMANTICS: git, schemas, pydantic, api, contracts
+# @PURPOSE:   Defines Pydantic models for the Git integration API layer.
+# @LAYER:     API
+# @RELATION:  DEPENDS_ON -> backend.src.models.git
+#
+# @INVARIANT: All schemas must be compatible with the FastAPI router.
+
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from datetime import datetime
+from src.models.git import GitProvider, GitStatus, SyncStatus
+
+# [DEF:GitServerConfigBase:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Base schema for Git server configuration attributes.
+class GitServerConfigBase(BaseModel):
+    name: str = Field(..., description="Display name for the Git server")
+    provider: GitProvider = Field(..., description="Git provider (GITHUB, GITLAB, GITEA)")
+    url: str = Field(..., description="Server base URL")
+    pat: str = Field(..., description="Personal Access Token")
+    default_repository: Optional[str] = Field(None, description="Default repository path (org/repo)")
+# [/DEF:GitServerConfigBase:Class]
+
+# [DEF:GitServerConfigCreate:Class]
+# @PURPOSE: Schema for creating a new Git server configuration.
+class GitServerConfigCreate(GitServerConfigBase):
+    """Schema for creating a new Git server configuration."""
+    pass
+# [/DEF:GitServerConfigCreate:Class]
+
+# [DEF:GitServerConfigSchema:Class]
+# @PURPOSE: Schema for representing a Git server configuration with metadata.
+class GitServerConfigSchema(GitServerConfigBase):
+    """Schema for representing a Git server configuration with metadata."""
+    id: str
+    status: GitStatus
+    last_validated: datetime
+
+    class Config:
+        from_attributes = True
+# [/DEF:GitServerConfigSchema:Class]
+
+# [DEF:GitRepositorySchema:Class]
+# @PURPOSE: Schema for tracking a local Git repository linked to a dashboard.
+class GitRepositorySchema(BaseModel):
+    """Schema for tracking a local Git repository linked to a dashboard."""
+    id: str
+    dashboard_id: int
+    config_id: str
+    remote_url: str
+    local_path: str
+    current_branch: str
+    sync_status: SyncStatus
+
+    class Config:
+        from_attributes = True
+# [/DEF:GitRepositorySchema:Class]
+
+# [DEF:BranchSchema:Class]
+# @PURPOSE: Schema for representing a Git branch metadata.
+class BranchSchema(BaseModel):
+    """Schema for representing a Git branch."""
+    name: str
+    commit_hash: str
+    is_remote: bool
+    last_updated: datetime
+# [/DEF:BranchSchema:Class]
+
+# [DEF:CommitSchema:Class]
+# @PURPOSE: Schema for representing Git commit details.
+class CommitSchema(BaseModel):
+    """Schema for representing a Git commit."""
+    hash: str
+    author: str
+    email: str
+    timestamp: datetime
+    message: str
+    files_changed: List[str]
+# [/DEF:CommitSchema:Class]
+
+# [DEF:BranchCreate:Class]
+# @PURPOSE: Schema for branch creation requests.
+class BranchCreate(BaseModel):
+    """Schema for branch creation requests."""
+    name: str
+    from_branch: str
+# [/DEF:BranchCreate:Class]
+
+# [DEF:BranchCheckout:Class]
+# @PURPOSE: Schema for branch checkout requests.
+class BranchCheckout(BaseModel):
+    """Schema for branch checkout requests."""
+    name: str
+# [/DEF:BranchCheckout:Class]
+
+# [DEF:CommitCreate:Class]
+# @PURPOSE: Schema for staging and committing changes.
+class CommitCreate(BaseModel):
+    """Schema for staging and committing changes."""
+    message: str
+    files: List[str]
+# [/DEF:CommitCreate:Class]
+
+# [DEF:ConflictResolution:Class]
+# @PURPOSE: Schema for resolving merge conflicts.
+class ConflictResolution(BaseModel):
+    """Schema for resolving merge conflicts."""
+    file_path: str
+    resolution: str = Field(pattern="^(mine|theirs|manual)$")
+    content: Optional[str] = None
+# [/DEF:ConflictResolution:Class]
+
+# [DEF:DeploymentEnvironmentSchema:Class]
+# @PURPOSE: Schema for representing a target deployment environment.
+class DeploymentEnvironmentSchema(BaseModel):
+    """Schema for representing a target deployment environment."""
+    id: str
+    name: str
+    superset_url: str
+    is_active: bool
+
+    class Config:
+        from_attributes = True
+# [/DEF:DeploymentEnvironmentSchema:Class]
+
+# [DEF:DeployRequest:Class]
+# @PURPOSE: Schema for dashboard deployment requests.
+class DeployRequest(BaseModel):
+    """Schema for deployment requests."""
+    environment_id: str
+# [/DEF:DeployRequest:Class]
+
+# [DEF:RepoInitRequest:Class]
+# @PURPOSE: Schema for repository initialization requests.
+class RepoInitRequest(BaseModel):
+    """Schema for repository initialization requests."""
+    config_id: str
+    remote_url: str
+# [/DEF:RepoInitRequest:Class]
+
+# [/DEF:backend.src.api.routes.git_schemas:Module]

backend/src/api/routes/llm.py

@@ -0,0 +1,207 @@
+# [DEF:backend/src/api/routes/llm.py:Module]
+# @TIER: STANDARD
+# @SEMANTICS: api, routes, llm
+# @PURPOSE: API routes for LLM provider configuration and management.
+# @LAYER: UI (API)
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import List
+from ...core.logger import logger
+from ...schemas.auth import User
+from ...dependencies import get_current_user as get_current_active_user
+from ...plugins.llm_analysis.models import LLMProviderConfig, LLMProviderType
+from ...services.llm_provider import LLMProviderService
+from ...core.database import get_db
+from sqlalchemy.orm import Session
+
+# [DEF:router:Global]
+# @PURPOSE: APIRouter instance for LLM routes.
+router = APIRouter(tags=["LLM"])
+# [/DEF:router:Global]
+
+# [DEF:get_providers:Function]
+# @PURPOSE: Retrieve all LLM provider configurations.
+# @PRE: User is authenticated.
+# @POST: Returns list of LLMProviderConfig.
+@router.get("/providers", response_model=List[LLMProviderConfig])
+async def get_providers(
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get all LLM provider configurations.
+    """
+    logger.info(f"[llm_routes][get_providers][Action] Fetching providers for user: {current_user.username}")
+    service = LLMProviderService(db)
+    providers = service.get_all_providers()
+    return [
+        LLMProviderConfig(
+            id=p.id,
+            provider_type=LLMProviderType(p.provider_type),
+            name=p.name,
+            base_url=p.base_url,
+            api_key="********",
+            default_model=p.default_model,
+            is_active=p.is_active
+        ) for p in providers
+    ]
+# [/DEF:get_providers:Function]
+
+# [DEF:create_provider:Function]
+# @PURPOSE: Create a new LLM provider configuration.
+# @PRE: User is authenticated and has admin permissions.
+# @POST: Returns the created LLMProviderConfig.
+@router.post("/providers", response_model=LLMProviderConfig, status_code=status.HTTP_201_CREATED)
+async def create_provider(
+    config: LLMProviderConfig,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Create a new LLM provider configuration.
+    """
+    service = LLMProviderService(db)
+    provider = service.create_provider(config)
+    return LLMProviderConfig(
+        id=provider.id,
+        provider_type=LLMProviderType(provider.provider_type),
+        name=provider.name,
+        base_url=provider.base_url,
+        api_key="********",
+        default_model=provider.default_model,
+        is_active=provider.is_active
+    )
+# [/DEF:create_provider:Function]
+
+# [DEF:update_provider:Function]
+# @PURPOSE: Update an existing LLM provider configuration.
+# @PRE: User is authenticated and has admin permissions.
+# @POST: Returns the updated LLMProviderConfig.
+@router.put("/providers/{provider_id}", response_model=LLMProviderConfig)
+async def update_provider(
+    provider_id: str,
+    config: LLMProviderConfig,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Update an existing LLM provider configuration.
+    """
+    service = LLMProviderService(db)
+    provider = service.update_provider(provider_id, config)
+    if not provider:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    
+    return LLMProviderConfig(
+        id=provider.id,
+        provider_type=LLMProviderType(provider.provider_type),
+        name=provider.name,
+        base_url=provider.base_url,
+        api_key="********",
+        default_model=provider.default_model,
+        is_active=provider.is_active
+    )
+# [/DEF:update_provider:Function]
+
+# [DEF:delete_provider:Function]
+# @PURPOSE: Delete an LLM provider configuration.
+# @PRE: User is authenticated and has admin permissions.
+# @POST: Returns success status.
+@router.delete("/providers/{provider_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_provider(
+    provider_id: str,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Delete an LLM provider configuration.
+    """
+    service = LLMProviderService(db)
+    if not service.delete_provider(provider_id):
+        raise HTTPException(status_code=404, detail="Provider not found")
+    return
+# [/DEF:delete_provider:Function]
+
+# [DEF:test_connection:Function]
+# @PURPOSE: Test connection to an LLM provider.
+# @PRE: User is authenticated.
+# @POST: Returns success status and message.
+@router.post("/providers/{provider_id}/test")
+async def test_connection(
+    provider_id: str,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    logger.info(f"[llm_routes][test_connection][Action] Testing connection for provider_id: {provider_id}")
+    """
+    Test connection to an LLM provider.
+    """
+    from ...plugins.llm_analysis.service import LLMClient
+    service = LLMProviderService(db)
+    db_provider = service.get_provider(provider_id)
+    if not db_provider:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    
+    api_key = service.get_decrypted_api_key(provider_id)
+    
+    # Check if API key was successfully decrypted
+    if not api_key:
+        logger.error(f"[llm_routes][test_connection] Failed to decrypt API key for provider {provider_id}")
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to decrypt API key. The provider may have been encrypted with a different encryption key. Please update the provider with a new API key."
+        )
+    
+    client = LLMClient(
+        provider_type=LLMProviderType(db_provider.provider_type),
+        api_key=api_key,
+        base_url=db_provider.base_url,
+        default_model=db_provider.default_model
+    )
+    
+    try:
+        # Simple test call
+        await client.client.models.list()
+        return {"success": True, "message": "Connection successful"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+# [/DEF:test_connection:Function]
+
+# [DEF:test_provider_config:Function]
+# @PURPOSE: Test connection with a provided configuration (not yet saved).
+# @PRE: User is authenticated.
+# @POST: Returns success status and message.
+@router.post("/providers/test")
+async def test_provider_config(
+    config: LLMProviderConfig,
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Test connection with a provided configuration.
+    """
+    from ...plugins.llm_analysis.service import LLMClient
+    logger.info(f"[llm_routes][test_provider_config][Action] Testing config for {config.name}")
+    
+    # Check if API key is provided
+    if not config.api_key or config.api_key == "********":
+        raise HTTPException(
+            status_code=400,
+            detail="API key is required for testing connection"
+        )
+    
+    client = LLMClient(
+        provider_type=config.provider_type,
+        api_key=config.api_key,
+        base_url=config.base_url,
+        default_model=config.default_model
+    )
+    
+    try:
+        # Simple test call
+        await client.client.models.list()
+        return {"success": True, "message": "Connection successful"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+# [/DEF:test_provider_config:Function]
+
+# [/DEF:backend/src/api/routes/llm.py]

backend/src/api/routes/mappings.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.api.routes.mappings:Module]
 #
+# @TIER: STANDARD
 # @SEMANTICS: api, mappings, database, fuzzy-matching
 # @PURPOSE:   API endpoints for managing database mappings and getting suggestions.
 # @LAYER:     API
@@ -13,13 +14,14 @@
 from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.orm import Session
 from typing import List, Optional
-from ...dependencies import get_config_manager
+from ...core.logger import belief_scope
+from ...dependencies import get_config_manager, has_permission
 from ...core.database import get_db
 from ...models.mapping import DatabaseMapping
 from pydantic import BaseModel
 # [/SECTION]
 
-router = APIRouter(prefix="/api/mappings", tags=["mappings"])
+router = APIRouter(tags=["mappings"])
 
 # [DEF:MappingCreate:DataClass]
 class MappingCreate(BaseModel):
@@ -29,6 +31,7 @@ class MappingCreate(BaseModel):
     target_db_uuid: str
     source_db_name: str
     target_db_name: str
+    engine: Optional[str] = None
 # [/DEF:MappingCreate:DataClass]
 
 # [DEF:MappingResponse:DataClass]
@@ -40,6 +43,7 @@ class MappingResponse(BaseModel):
     target_db_uuid: str
     source_db_name: str
     target_db_name: str
+    engine: Optional[str] = None
 
     class Config:
         from_attributes = True
@@ -59,7 +63,8 @@ class SuggestRequest(BaseModel):
 async def get_mappings(
     source_env_id: Optional[str] = None,
     target_env_id: Optional[str] = None,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:mapper", "EXECUTE"))
 ):
     with belief_scope("get_mappings"):
         query = db.query(DatabaseMapping)
@@ -75,7 +80,11 @@ async def get_mappings(
 # @PRE:     mapping is valid MappingCreate, db session is injected.
 # @POST:    DatabaseMapping created or updated in database.
 @router.post("", response_model=MappingResponse)
-async def create_mapping(mapping: MappingCreate, db: Session = Depends(get_db)):
+async def create_mapping(
+    mapping: MappingCreate,
+    db: Session = Depends(get_db),
+    _ = Depends(has_permission("plugin:mapper", "EXECUTE"))
+):
     with belief_scope("create_mapping"):
         # Check if mapping already exists
         existing = db.query(DatabaseMapping).filter(
@@ -87,6 +96,7 @@ async def create_mapping(mapping: MappingCreate, db: Session = Depends(get_db)):
         if existing:
             existing.target_db_uuid = mapping.target_db_uuid
             existing.target_db_name = mapping.target_db_name
+            existing.engine = mapping.engine
             db.commit()
             db.refresh(existing)
             return existing
@@ -105,10 +115,11 @@ async def create_mapping(mapping: MappingCreate, db: Session = Depends(get_db)):
 @router.post("/suggest")
 async def suggest_mappings_api(
     request: SuggestRequest,
-    config_manager=Depends(get_config_manager)
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("plugin:mapper", "EXECUTE"))
 ):
     with belief_scope("suggest_mappings_api"):
-        from backend.src.services.mapping_service import MappingService
+        from ...services.mapping_service import MappingService
         service = MappingService(config_manager)
         try:
             return await service.get_suggestions(request.source_env_id, request.target_env_id)

backend/src/api/routes/migration.py

@@ -1,4 +1,5 @@
 # [DEF:backend.src.api.routes.migration:Module]
+# @TIER: STANDARD
 # @SEMANTICS: api, migration, dashboards
 # @PURPOSE:   API endpoints for migration operations.
 # @LAYER:     API
@@ -6,10 +7,11 @@
 # @RELATION:  DEPENDS_ON -> backend.src.models.dashboard
 
 from fastapi import APIRouter, Depends, HTTPException
-from typing import List, Dict
+from typing import List
-from ...dependencies import get_config_manager, get_task_manager
+from ...dependencies import get_config_manager, get_task_manager, has_permission
 from ...models.dashboard import DashboardMetadata, DashboardSelection
 from ...core.superset_client import SupersetClient
+from ...core.logger import belief_scope
 
 router = APIRouter(prefix="/api", tags=["migration"])
 
@@ -20,8 +22,13 @@ router = APIRouter(prefix="/api", tags=["migration"])
 # @PARAM:   env_id (str) - The ID of the environment to fetch from.
 # @RETURN:  List[DashboardMetadata]
 @router.get("/environments/{env_id}/dashboards", response_model=List[DashboardMetadata])
-async def get_dashboards(env_id: str, config_manager=Depends(get_config_manager)):
+async def get_dashboards(
-    environments = config_manager.get_environments()
+    env_id: str,
+    config_manager=Depends(get_config_manager),
+    _ = Depends(has_permission("plugin:migration", "EXECUTE"))
+):
+    with belief_scope("get_dashboards", f"env_id={env_id}"):
+        environments = config_manager.get_environments()
     env = next((e for e in environments if e.id == env_id), None)
     if not env:
         raise HTTPException(status_code=404, detail="Environment not found")
@@ -37,10 +44,16 @@ async def get_dashboards(env_id: str, config_manager=Depends(get_config_manager)
 # @POST:    Starts the migration task and returns the task ID.
 # @PARAM:   selection (DashboardSelection) - The dashboards to migrate.
 # @RETURN:  Dict - {"task_id": str, "message": str}
-@router.post("/migration/execute")
+@router.post("/execute")
-async def execute_migration(selection: DashboardSelection, config_manager=Depends(get_config_manager), task_manager=Depends(get_task_manager)):
+async def execute_migration(
-    # Validate environments exist
+    selection: DashboardSelection,
-    environments = config_manager.get_environments()
+    config_manager=Depends(get_config_manager),
+    task_manager=Depends(get_task_manager),
+    _ = Depends(has_permission("plugin:migration", "EXECUTE"))
+):
+    with belief_scope("execute_migration"):
+        # Validate environments exist
+        environments = config_manager.get_environments()
     env_ids = {e.id for e in environments}
     if selection.source_env_id not in env_ids or selection.target_env_id not in env_ids:
         raise HTTPException(status_code=400, detail="Invalid source or target environment")

backend/src/api/routes/plugins.py

@@ -1,4 +1,5 @@
 # [DEF:PluginsRouter:Module]
+# @TIER: STANDARD
 # @SEMANTICS: api, router, plugins, list
 # @PURPOSE: Defines the FastAPI router for plugin-related endpoints, allowing clients to list available plugins.
 # @LAYER: UI (API)
@@ -7,7 +8,7 @@ from typing import List
 from fastapi import APIRouter, Depends
 
 from ...core.plugin_base import PluginConfig
-from ...dependencies import get_plugin_loader
+from ...dependencies import get_plugin_loader, has_permission
 from ...core.logger import belief_scope
 
 router = APIRouter()
@@ -19,7 +20,8 @@ router = APIRouter()
 # @RETURN: List[PluginConfig] - List of registered plugins.
 @router.get("", response_model=List[PluginConfig])
 async def list_plugins(
-    plugin_loader = Depends(get_plugin_loader)
+    plugin_loader = Depends(get_plugin_loader),
+    _ = Depends(has_permission("plugins", "READ"))
 ):
     with belief_scope("list_plugins"):
         """

backend/src/api/routes/settings.py

@@ -12,14 +12,24 @@
 # [SECTION: IMPORTS]
 from fastapi import APIRouter, Depends, HTTPException
 from typing import List
-from ...core.config_models import AppConfig, Environment, GlobalSettings
+from pydantic import BaseModel
-from ...dependencies import get_config_manager
+from ...core.config_models import AppConfig, Environment, GlobalSettings, LoggingConfig
+from ...models.storage import StorageConfig
+from ...dependencies import get_config_manager, has_permission
 from ...core.config_manager import ConfigManager
 from ...core.logger import logger, belief_scope
 from ...core.superset_client import SupersetClient
-import os
 # [/SECTION]
 
+# [DEF:LoggingConfigResponse:Class]
+# @PURPOSE: Response model for logging configuration with current task log level.
+# @SEMANTICS: logging, config, response
+class LoggingConfigResponse(BaseModel):
+    level: str
+    task_log_level: str
+    enable_belief_state: bool
+# [/DEF:LoggingConfigResponse:Class]
+
 router = APIRouter()
 
 # [DEF:get_settings:Function]
@@ -28,7 +38,10 @@ router = APIRouter()
 # @POST:    Returns masked AppConfig.
 # @RETURN: AppConfig - The current configuration.
 @router.get("", response_model=AppConfig)
-async def get_settings(config_manager: ConfigManager = Depends(get_config_manager)):
+async def get_settings(
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
     with belief_scope("get_settings"):
         logger.info("[get_settings][Entry] Fetching all settings")
     config = config_manager.get_config().copy(deep=True)
@@ -48,21 +61,60 @@ async def get_settings(config_manager: ConfigManager = Depends(get_config_manage
 @router.patch("/global", response_model=GlobalSettings)
 async def update_global_settings(
     settings: GlobalSettings,
-    config_manager: ConfigManager = Depends(get_config_manager)
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
 ):
     with belief_scope("update_global_settings"):
         logger.info("[update_global_settings][Entry] Updating global settings")
+    
     config_manager.update_global_settings(settings)
     return settings
 # [/DEF:update_global_settings:Function]
 
+# [DEF:get_storage_settings:Function]
+# @PURPOSE: Retrieves storage-specific settings.
+# @RETURN: StorageConfig - The storage configuration.
+@router.get("/storage", response_model=StorageConfig)
+async def get_storage_settings(
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("get_storage_settings"):
+        return config_manager.get_config().settings.storage
+# [/DEF:get_storage_settings:Function]
+
+# [DEF:update_storage_settings:Function]
+# @PURPOSE: Updates storage-specific settings.
+# @PARAM: storage (StorageConfig) - The new storage settings.
+# @POST: Storage settings are updated and saved.
+# @RETURN: StorageConfig - The updated storage settings.
+@router.put("/storage", response_model=StorageConfig)
+async def update_storage_settings(
+    storage: StorageConfig,
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("update_storage_settings"):
+        is_valid, message = config_manager.validate_path(storage.root_path)
+        if not is_valid:
+            raise HTTPException(status_code=400, detail=message)
+        
+        settings = config_manager.get_config().settings
+        settings.storage = storage
+        config_manager.update_global_settings(settings)
+        return config_manager.get_config().settings.storage
+# [/DEF:update_storage_settings:Function]
+
 # [DEF:get_environments:Function]
 # @PURPOSE: Lists all configured Superset environments.
 # @PRE:     Config manager is available.
 # @POST:    Returns list of environments.
 # @RETURN: List[Environment] - List of environments.
 @router.get("/environments", response_model=List[Environment])
-async def get_environments(config_manager: ConfigManager = Depends(get_config_manager)):
+async def get_environments(
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
     with belief_scope("get_environments"):
         logger.info("[get_environments][Entry] Fetching environments")
     return config_manager.get_environments()
@@ -77,7 +129,8 @@ async def get_environments(config_manager: ConfigManager = Depends(get_config_ma
 @router.post("/environments", response_model=Environment)
 async def add_environment(
     env: Environment,
-    config_manager: ConfigManager = Depends(get_config_manager)
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
 ):
     with belief_scope("add_environment"):
         logger.info(f"[add_environment][Entry] Adding environment {env.id}")
@@ -179,30 +232,145 @@ async def test_environment_connection(
         return {"status": "error", "message": str(e)}
 # [/DEF:test_environment_connection:Function]
 
-# [DEF:validate_backup_path:Function]
+# [DEF:get_logging_config:Function]
-# @PURPOSE: Validates if a backup path exists and is writable.
+# @PURPOSE: Retrieves current logging configuration.
-# @PRE:     Path is provided in path_data.
+# @PRE:     Config manager is available.
-# @POST:    Returns success or error status.
+# @POST:    Returns logging configuration.
-# @PARAM: path (str) - The path to validate.
+# @RETURN: LoggingConfigResponse - The current logging config.
-# @RETURN: dict - Validation result.
+@router.get("/logging", response_model=LoggingConfigResponse)
-@router.post("/validate-path")
+async def get_logging_config(
-async def validate_backup_path(
+    config_manager: ConfigManager = Depends(get_config_manager),
-    path_data: dict,
+    _ = Depends(has_permission("admin:settings", "READ"))
-    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    with belief_scope("validate_backup_path"):
+    with belief_scope("get_logging_config"):
-        path = path_data.get("path")
+        logging_config = config_manager.get_config().settings.logging
-        if not path:
+        return LoggingConfigResponse(
-            raise HTTPException(status_code=400, detail="Path is required")
+            level=logging_config.level,
+            task_log_level=logging_config.task_log_level,
+            enable_belief_state=logging_config.enable_belief_state
+        )
+# [/DEF:get_logging_config:Function]
 
-        logger.info(f"[validate_backup_path][Entry] Validating path: {path}")
+# [DEF:update_logging_config:Function]
+# @PURPOSE: Updates logging configuration.
+# @PRE:     New logging config is provided.
+# @POST:    Logging configuration is updated and saved.
+# @PARAM: config (LoggingConfig) - The new logging configuration.
+# @RETURN: LoggingConfigResponse - The updated logging config.
+@router.patch("/logging", response_model=LoggingConfigResponse)
+async def update_logging_config(
+    config: LoggingConfig,
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("update_logging_config"):
+        logger.info(f"[update_logging_config][Entry] Updating logging config: level={config.level}, task_log_level={config.task_log_level}")
         
-    valid, message = config_manager.validate_path(path)
+        # Get current settings and update logging config
+        settings = config_manager.get_config().settings
+        settings.logging = config
+        config_manager.update_global_settings(settings)
         
-    if not valid:
+        return LoggingConfigResponse(
-        return {"status": "error", "message": message}
+            level=config.level,
+            task_log_level=config.task_log_level,
+            enable_belief_state=config.enable_belief_state
+        )
+# [/DEF:update_logging_config:Function]
 
-    return {"status": "success", "message": message}
+# [DEF:ConsolidatedSettingsResponse:Class]
-# [/DEF:validate_backup_path:Function]
+class ConsolidatedSettingsResponse(BaseModel):
+    environments: List[dict]
+    connections: List[dict]
+    llm: dict
+    llm_providers: List[dict]
+    logging: dict
+    storage: dict
+# [/DEF:ConsolidatedSettingsResponse:Class]
+
+# [DEF:get_consolidated_settings:Function]
+# @PURPOSE: Retrieves all settings categories in a single call
+# @PRE:     Config manager is available.
+# @POST:    Returns all consolidated settings.
+# @RETURN: ConsolidatedSettingsResponse - All settings categories.
+@router.get("/consolidated", response_model=ConsolidatedSettingsResponse)
+async def get_consolidated_settings(
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "READ"))
+):
+    with belief_scope("get_consolidated_settings"):
+        logger.info("[get_consolidated_settings][Entry] Fetching all consolidated settings")
+        
+        config = config_manager.get_config()
+        
+        from ...services.llm_provider import LLMProviderService
+        from ...core.database import SessionLocal
+        db = SessionLocal()
+        try:
+            llm_service = LLMProviderService(db)
+            providers = llm_service.get_all_providers()
+            llm_providers_list = [
+                {
+                    "id": p.id,
+                    "provider_type": p.provider_type,
+                    "name": p.name,
+                    "base_url": p.base_url,
+                    "api_key": "********",
+                    "default_model": p.default_model,
+                    "is_active": p.is_active
+                } for p in providers
+            ]
+        finally:
+            db.close()
+
+        return ConsolidatedSettingsResponse(
+            environments=[env.dict() for env in config.environments],
+            connections=config.settings.connections,
+            llm=config.settings.llm,
+            llm_providers=llm_providers_list,
+            logging=config.settings.logging.dict(),
+            storage=config.settings.storage.dict()
+        )
+# [/DEF:get_consolidated_settings:Function]
+
+# [DEF:update_consolidated_settings:Function]
+# @PURPOSE: Bulk update application settings from the consolidated view.
+# @PRE:     User has admin permissions, config is valid.
+# @POST:    Settings are updated and saved via ConfigManager.
+@router.patch("/consolidated")
+async def update_consolidated_settings(
+    settings_patch: dict,
+    config_manager: ConfigManager = Depends(get_config_manager),
+    _ = Depends(has_permission("admin:settings", "WRITE"))
+):
+    with belief_scope("update_consolidated_settings"):
+        logger.info("[update_consolidated_settings][Entry] Applying consolidated settings patch")
+        
+        current_config = config_manager.get_config()
+        current_settings = current_config.settings
+        
+        # Update connections if provided
+        if "connections" in settings_patch:
+            current_settings.connections = settings_patch["connections"]
+            
+        # Update LLM if provided
+        if "llm" in settings_patch:
+            current_settings.llm = settings_patch["llm"]
+            
+        # Update Logging if provided
+        if "logging" in settings_patch:
+            current_settings.logging = LoggingConfig(**settings_patch["logging"])
+            
+        # Update Storage if provided
+        if "storage" in settings_patch:
+            new_storage = StorageConfig(**settings_patch["storage"])
+            is_valid, message = config_manager.validate_path(new_storage.root_path)
+            if not is_valid:
+                 raise HTTPException(status_code=400, detail=message)
+            current_settings.storage = new_storage
+
+        config_manager.update_global_settings(current_settings)
+        return {"status": "success", "message": "Settings updated"}
+# [/DEF:update_consolidated_settings:Function]
 
 # [/DEF:SettingsRouter:Module]

backend/src/api/routes/storage.py

@@ -0,0 +1,146 @@
+# [DEF:storage_routes:Module]
+#
+# @TIER: STANDARD
+# @SEMANTICS: storage, files, upload, download, backup, repository
+# @PURPOSE:   API endpoints for file storage management (backups and repositories).
+# @LAYER:     API
+# @RELATION:  DEPENDS_ON -> backend.src.models.storage
+#
+# @INVARIANT: All paths must be validated against path traversal.
+
+# [SECTION: IMPORTS]
+from pathlib import Path
+from fastapi import APIRouter, Depends, UploadFile, File, Form, HTTPException
+from fastapi.responses import FileResponse
+from typing import List, Optional
+from ...models.storage import StoredFile, FileCategory
+from ...dependencies import get_plugin_loader, has_permission
+from ...plugins.storage.plugin import StoragePlugin
+from ...core.logger import belief_scope
+# [/SECTION]
+
+router = APIRouter(tags=["storage"])
+
+# [DEF:list_files:Function]
+# @PURPOSE:     List all files and directories in the storage system.
+#
+# @PRE:         None.
+# @POST:        Returns a list of StoredFile objects.
+#
+# @PARAM:       category (Optional[FileCategory]) - Filter by category.
+# @PARAM:       path (Optional[str]) - Subpath within the category.
+# @RETURN:      List[StoredFile] - List of files/directories.
+#
+# @RELATION:    CALLS -> StoragePlugin.list_files
+@router.get("/files", response_model=List[StoredFile])
+async def list_files(
+    category: Optional[FileCategory] = None,
+    path: Optional[str] = None,
+    plugin_loader=Depends(get_plugin_loader),
+    _ = Depends(has_permission("plugin:storage", "READ"))
+):
+    with belief_scope("list_files"):
+        storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
+        if not storage_plugin:
+            raise HTTPException(status_code=500, detail="Storage plugin not loaded")
+        return storage_plugin.list_files(category, path)
+# [/DEF:list_files:Function]
+
+# [DEF:upload_file:Function]
+# @PURPOSE:     Upload a file to the storage system.
+#
+# @PRE:         category must be a valid FileCategory.
+# @PRE:         file must be a valid UploadFile.
+# @POST:        Returns the StoredFile object of the uploaded file.
+#
+# @PARAM:       category (FileCategory) - Target category.
+# @PARAM:       path (Optional[str]) - Target subpath.
+# @PARAM:       file (UploadFile) - The file content.
+# @RETURN:      StoredFile - Metadata of the uploaded file.
+#
+# @SIDE_EFFECT: Writes file to the filesystem.
+#
+# @RELATION:    CALLS -> StoragePlugin.save_file
+@router.post("/upload", response_model=StoredFile, status_code=201)
+async def upload_file(
+    category: FileCategory = Form(...),
+    path: Optional[str] = Form(None),
+    file: UploadFile = File(...),
+    plugin_loader=Depends(get_plugin_loader),
+    _ = Depends(has_permission("plugin:storage", "WRITE"))
+):
+    with belief_scope("upload_file"):
+        storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
+        if not storage_plugin:
+            raise HTTPException(status_code=500, detail="Storage plugin not loaded")
+        try:
+            return await storage_plugin.save_file(file, category, path)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:upload_file:Function]
+
+# [DEF:delete_file:Function]
+# @PURPOSE:     Delete a specific file or directory.
+#
+# @PRE:         category must be a valid FileCategory.
+# @POST:        Item is removed from storage.
+#
+# @PARAM:       category (FileCategory) - File category.
+# @PARAM:       path (str) - Relative path of the item.
+# @RETURN:      None
+#
+# @SIDE_EFFECT: Deletes item from the filesystem.
+#
+# @RELATION:    CALLS -> StoragePlugin.delete_file
+@router.delete("/files/{category}/{path:path}", status_code=204)
+async def delete_file(
+    category: FileCategory,
+    path: str,
+    plugin_loader=Depends(get_plugin_loader),
+    _ = Depends(has_permission("plugin:storage", "WRITE"))
+):
+    with belief_scope("delete_file"):
+        storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
+        if not storage_plugin:
+            raise HTTPException(status_code=500, detail="Storage plugin not loaded")
+        try:
+            storage_plugin.delete_file(category, path)
+        except FileNotFoundError:
+            raise HTTPException(status_code=404, detail="File not found")
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:delete_file:Function]
+
+# [DEF:download_file:Function]
+# @PURPOSE:     Retrieve a file for download.
+#
+# @PRE:         category must be a valid FileCategory.
+# @POST:        Returns a FileResponse.
+#
+# @PARAM:       category (FileCategory) - File category.
+# @PARAM:       path (str) - Relative path of the file.
+# @RETURN:      FileResponse - The file content.
+#
+# @RELATION:    CALLS -> StoragePlugin.get_file_path
+@router.get("/download/{category}/{path:path}")
+async def download_file(
+    category: FileCategory,
+    path: str,
+    plugin_loader=Depends(get_plugin_loader),
+    _ = Depends(has_permission("plugin:storage", "READ"))
+):
+    with belief_scope("download_file"):
+        storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
+        if not storage_plugin:
+            raise HTTPException(status_code=500, detail="Storage plugin not loaded")
+        try:
+            abs_path = storage_plugin.get_file_path(category, path)
+            filename = Path(path).name
+            return FileResponse(path=abs_path, filename=filename)
+        except FileNotFoundError:
+            raise HTTPException(status_code=404, detail="File not found")
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+# [/DEF:download_file:Function]
+
+# [/DEF:storage_routes:Module]

backend/src/api/routes/tasks.py

@@ -1,15 +1,17 @@
 # [DEF:TasksRouter:Module]
-# @SEMANTICS: api, router, tasks, create, list, get
+# @TIER: STANDARD
+# @SEMANTICS: api, router, tasks, create, list, get, logs
 # @PURPOSE: Defines the FastAPI router for task-related endpoints, allowing clients to create, list, and get the status of tasks.
 # @LAYER: UI (API)
 # @RELATION: Depends on the TaskManager. It is included by the main app.
 from typing import List, Dict, Any, Optional
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Query
 from pydantic import BaseModel
 from ...core.logger import belief_scope
 
 from ...core.task_manager import TaskManager, Task, TaskStatus, LogEntry
-from ...dependencies import get_task_manager
+from ...core.task_manager.models import LogFilter, LogStats
+from ...dependencies import get_task_manager, has_permission, get_current_user
 
 router = APIRouter()
 
@@ -33,13 +35,31 @@ class ResumeTaskRequest(BaseModel):
 # @RETURN: Task - The created task instance.
 async def create_task(
     request: CreateTaskRequest,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    current_user = Depends(get_current_user)
 ):
+    # Dynamic permission check based on plugin_id
+    has_permission(f"plugin:{request.plugin_id}", "EXECUTE")(current_user)
     """
     Create and start a new task for a given plugin.
     """
     with belief_scope("create_task"):
         try:
+            # Special handling for validation task to include provider config
+            if request.plugin_id == "llm_dashboard_validation":
+                from ...core.database import SessionLocal
+                from ...services.llm_provider import LLMProviderService
+                db = SessionLocal()
+                try:
+                    llm_service = LLMProviderService(db)
+                    provider_id = request.params.get("provider_id")
+                    if provider_id:
+                        db_provider = llm_service.get_provider(provider_id)
+                        if not db_provider:
+                            raise ValueError(f"LLM Provider {provider_id} not found")
+                finally:
+                    db.close()
+
             task = await task_manager.create_task(
                 plugin_id=request.plugin_id,
                 params=request.params
@@ -63,7 +83,8 @@ async def list_tasks(
     limit: int = 10,
     offset: int = 0,
     status: Optional[TaskStatus] = None,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "READ"))
 ):
     """
     Retrieve a list of tasks with pagination and optional status filter.
@@ -82,7 +103,8 @@ async def list_tasks(
 # @RETURN: Task - The task details.
 async def get_task(
     task_id: str,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "READ"))
 ):
     """
     Retrieve the details of a specific task.
@@ -96,26 +118,93 @@ async def get_task(
 
 @router.get("/{task_id}/logs", response_model=List[LogEntry])
 # [DEF:get_task_logs:Function]
-# @PURPOSE: Retrieve logs for a specific task.
+# @PURPOSE: Retrieve logs for a specific task with optional filtering.
 # @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: level (Optional[str]) - Filter by log level (DEBUG, INFO, WARNING, ERROR).
+# @PARAM: source (Optional[str]) - Filter by source component.
+# @PARAM: search (Optional[str]) - Text search in message.
+# @PARAM: offset (int) - Number of logs to skip.
+# @PARAM: limit (int) - Maximum number of logs to return.
 # @PARAM: task_manager (TaskManager) - The task manager instance.
 # @PRE: task_id must exist.
 # @POST: Returns a list of log entries or raises 404.
 # @RETURN: List[LogEntry] - List of log entries.
+# @TIER: CRITICAL
 async def get_task_logs(
     task_id: str,
-    task_manager: TaskManager = Depends(get_task_manager)
+    level: Optional[str] = Query(None, description="Filter by log level (DEBUG, INFO, WARNING, ERROR)"),
+    source: Optional[str] = Query(None, description="Filter by source component"),
+    search: Optional[str] = Query(None, description="Text search in message"),
+    offset: int = Query(0, ge=0, description="Number of logs to skip"),
+    limit: int = Query(100, ge=1, le=1000, description="Maximum number of logs to return"),
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "READ"))
 ):
     """
-    Retrieve logs for a specific task.
+    Retrieve logs for a specific task with optional filtering.
+    Supports filtering by level, source, and text search.
     """
     with belief_scope("get_task_logs"):
         task = task_manager.get_task(task_id)
         if not task:
             raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
-        return task_manager.get_task_logs(task_id)
+        
+        log_filter = LogFilter(
+            level=level.upper() if level else None,
+            source=source,
+            search=search,
+            offset=offset,
+            limit=limit
+        )
+        return task_manager.get_task_logs(task_id, log_filter)
 # [/DEF:get_task_logs:Function]
 
+@router.get("/{task_id}/logs/stats", response_model=LogStats)
+# [DEF:get_task_log_stats:Function]
+# @PURPOSE: Get statistics about logs for a task (counts by level and source).
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_id must exist.
+# @POST: Returns log statistics or raises 404.
+# @RETURN: LogStats - Statistics about task logs.
+async def get_task_log_stats(
+    task_id: str,
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "READ"))
+):
+    """
+    Get statistics about logs for a task (counts by level and source).
+    """
+    with belief_scope("get_task_log_stats"):
+        task = task_manager.get_task(task_id)
+        if not task:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
+        return task_manager.get_task_log_stats(task_id)
+# [/DEF:get_task_log_stats:Function]
+
+@router.get("/{task_id}/logs/sources", response_model=List[str])
+# [DEF:get_task_log_sources:Function]
+# @PURPOSE: Get unique sources for a task's logs.
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_id must exist.
+# @POST: Returns list of unique source names or raises 404.
+# @RETURN: List[str] - Unique source names.
+async def get_task_log_sources(
+    task_id: str,
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "READ"))
+):
+    """
+    Get unique sources for a task's logs.
+    """
+    with belief_scope("get_task_log_sources"):
+        task = task_manager.get_task(task_id)
+        if not task:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
+        return task_manager.get_task_log_sources(task_id)
+# [/DEF:get_task_log_sources:Function]
+
 @router.post("/{task_id}/resolve", response_model=Task)
 # [DEF:resolve_task:Function]
 # @PURPOSE: Resolve a task that is awaiting mapping.
@@ -128,7 +217,8 @@ async def get_task_logs(
 async def resolve_task(
     task_id: str,
     request: ResolveTaskRequest,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "WRITE"))
 ):
     """
     Resolve a task that is awaiting mapping.
@@ -153,7 +243,8 @@ async def resolve_task(
 async def resume_task(
     task_id: str,
     request: ResumeTaskRequest,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "WRITE"))
 ):
     """
     Resume a task that is awaiting input (e.g., passwords).
@@ -175,7 +266,8 @@ async def resume_task(
 # @POST: Tasks are removed from memory/persistence.
 async def clear_tasks(
     status: Optional[TaskStatus] = None,
-    task_manager: TaskManager = Depends(get_task_manager)
+    task_manager: TaskManager = Depends(get_task_manager),
+    _ = Depends(has_permission("tasks", "WRITE"))
 ):
     """
     Clear tasks matching the status filter. If no filter, clears all non-running tasks.

backend/src/app.py

@@ -1,25 +1,28 @@
 # [DEF:AppModule:Module]
+# @TIER: CRITICAL
 # @SEMANTICS: app, main, entrypoint, fastapi
 # @PURPOSE: The main entry point for the FastAPI application. It initializes the app, configures CORS, sets up dependencies, includes API routers, and defines the WebSocket endpoint for log streaming.
 # @LAYER: UI (API)
 # @RELATION: Depends on the dependency module and API route modules.
-import sys
+# @INVARIANT: Only one FastAPI app instance exists per process.
+# @INVARIANT: All WebSocket connections must be properly cleaned up on disconnect.
 from pathlib import Path
 
 # project_root is used for static files mounting
 project_root = Path(__file__).resolve().parent.parent.parent
 
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Depends, Request, HTTPException
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request, HTTPException
+from starlette.middleware.sessions import SessionMiddleware
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
 import asyncio
-import os
 
 from .dependencies import get_task_manager, get_scheduler_service
+from .core.utils.network import NetworkError
 from .core.logger import logger, belief_scope
-from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections
+from .api.routes import plugins, tasks, settings, environments, mappings, migration, connections, git, storage, admin, llm, dashboards, datasets
-from .core.database import init_db
+from .api import auth
 
 # [DEF:App:Global]
 # @SEMANTICS: app, fastapi, instance
@@ -55,6 +58,10 @@ async def shutdown_event():
     scheduler.stop()
 # [/DEF:shutdown_event:Function]
 
+# Configure Session Middleware (required by Authlib for OAuth2 flow)
+from .core.auth.config import auth_config
+app.add_middleware(SessionMiddleware, secret_key=auth_config.SECRET_KEY)
+
 # Configure CORS
 app.add_middleware(
     CORSMiddleware,
@@ -71,45 +78,119 @@ app.add_middleware(
 # @POST: Logs request and response details.
 # @PARAM: request (Request) - The incoming request object.
 # @PARAM: call_next (Callable) - The next middleware or route handler.
+@app.exception_handler(NetworkError)
+async def network_error_handler(request: Request, exc: NetworkError):
+    with belief_scope("network_error_handler"):
+        logger.error(f"Network error: {exc}")
+        return HTTPException(
+            status_code=503,
+            detail="Environment unavailable. Please check if the Superset instance is running."
+        )
+
 @app.middleware("http")
 async def log_requests(request: Request, call_next):
-    with belief_scope("log_requests", f"{request.method} {request.url.path}"):
+    # Avoid spamming logs for polling endpoints
-        logger.info(f"[DEBUG] Incoming request: {request.method} {request.url.path}")
+    is_polling = request.url.path.endswith("/api/tasks") and request.method == "GET"
+    
+    if not is_polling:
+        logger.info(f"Incoming request: {request.method} {request.url.path}")
+    
+    try:
         response = await call_next(request)
-        logger.info(f"[DEBUG] Response status: {response.status_code} for {request.url.path}")
+        if not is_polling:
+            logger.info(f"Response status: {response.status_code} for {request.url.path}")
         return response
+    except NetworkError as e:
+        logger.error(f"Network error caught in middleware: {e}")
+        raise HTTPException(
+            status_code=503,
+            detail="Environment unavailable. Please check if the Superset instance is running."
+        )
 # [/DEF:log_requests:Function]
 
 # Include API routes
+app.include_router(auth.router)
+app.include_router(admin.router)
 app.include_router(plugins.router, prefix="/api/plugins", tags=["Plugins"])
 app.include_router(tasks.router, prefix="/api/tasks", tags=["Tasks"])
 app.include_router(settings.router, prefix="/api/settings", tags=["Settings"])
 app.include_router(connections.router, prefix="/api/settings/connections", tags=["Connections"])
-app.include_router(environments.router, prefix="/api/environments", tags=["Environments"])
+app.include_router(environments.router, tags=["Environments"])
-app.include_router(mappings.router)
+app.include_router(mappings.router, prefix="/api/mappings", tags=["Mappings"])
 app.include_router(migration.router)
+app.include_router(git.router, prefix="/api/git", tags=["Git"])
+app.include_router(llm.router, prefix="/api/llm", tags=["LLM"])
+app.include_router(storage.router, prefix="/api/storage", tags=["Storage"])
+app.include_router(dashboards.router)
+app.include_router(datasets.router)
+
+
+# [DEF:api.include_routers:Action]
+# @PURPOSE: Registers all API routers with the FastAPI application.
+# @LAYER: API
+# @SEMANTICS: routes, registration, api
+# [/DEF:api.include_routers:Action]
 
 # [DEF:websocket_endpoint:Function]
-# @PURPOSE: Provides a WebSocket endpoint for real-time log streaming of a task.
+# @PURPOSE: Provides a WebSocket endpoint for real-time log streaming of a task with server-side filtering.
 # @PRE: task_id must be a valid task ID.
 # @POST: WebSocket connection is managed and logs are streamed until disconnect.
+# @TIER: CRITICAL
+# @UX_STATE: Connecting -> Streaming -> (Disconnected)
 @app.websocket("/ws/logs/{task_id}")
-async def websocket_endpoint(websocket: WebSocket, task_id: str):
+async def websocket_endpoint(
+    websocket: WebSocket,
+    task_id: str,
+    source: str = None,
+    level: str = None
+):
+    """
+    WebSocket endpoint for real-time log streaming with optional server-side filtering.
+    
+    Query Parameters:
+        source: Filter logs by source component (e.g., "plugin", "superset_api")
+        level: Filter logs by minimum level (DEBUG, INFO, WARNING, ERROR)
+    """
     with belief_scope("websocket_endpoint", f"task_id={task_id}"):
         await websocket.accept()
-    logger.info(f"WebSocket connection accepted for task {task_id}")
+    
+    # Normalize filter parameters
+    source_filter = source.lower() if source else None
+    level_filter = level.upper() if level else None
+    
+    # Level hierarchy for filtering
+    level_hierarchy = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3}
+    min_level = level_hierarchy.get(level_filter, 0) if level_filter else 0
+    
+    logger.info(f"WebSocket connection accepted for task {task_id} (source={source_filter}, level={level_filter})")
     task_manager = get_task_manager()
     queue = await task_manager.subscribe_logs(task_id)
+    
+    def matches_filters(log_entry) -> bool:
+        """Check if log entry matches the filter criteria."""
+        # Check source filter
+        if source_filter and log_entry.source.lower() != source_filter:
+            return False
+        
+        # Check level filter
+        if level_filter:
+            log_level = level_hierarchy.get(log_entry.level.upper(), 0)
+            if log_level < min_level:
+                return False
+        
+        return True
+    
     try:
         # Stream new logs
         logger.info(f"Starting log stream for task {task_id}")
         
-        # Send initial logs first to build context
+        # Send initial logs first to build context (apply filters)
         initial_logs = task_manager.get_task_logs(task_id)
         for log_entry in initial_logs:
-            log_dict = log_entry.dict()
+            if matches_filters(log_entry):
-            log_dict['timestamp'] = log_dict['timestamp'].isoformat()
+                log_dict = log_entry.dict()
-            await websocket.send_json(log_dict)
+                log_dict['timestamp'] = log_dict['timestamp'].isoformat()
+                await websocket.send_json(log_dict)
 
         # Force a check for AWAITING_INPUT status immediately upon connection
         # This ensures that if the task is already waiting when the user connects, they get the prompt.
@@ -127,6 +208,11 @@ async def websocket_endpoint(websocket: WebSocket, task_id: str):
 
         while True:
             log_entry = await queue.get()
+            
+            # Apply server-side filtering
+            if not matches_filters(log_entry):
+                continue
+            
             log_dict = log_entry.dict()
             log_dict['timestamp'] = log_dict['timestamp'].isoformat()
             await websocket.send_json(log_dict)
@@ -155,24 +241,19 @@ frontend_path = project_root / "frontend" / "build"
 if frontend_path.exists():
     app.mount("/_app", StaticFiles(directory=str(frontend_path / "_app")), name="static")
 
-    # Serve other static files from the root of build directory
+    @app.get("/{file_path:path}", include_in_schema=False)
-    # [DEF:serve_spa:Function]
-    # @PURPOSE: Serves frontend static files or index.html for SPA routing.
-    # @PRE: file_path is requested by the client.
-    # @POST: Returns the requested file or index.html as a fallback.
-    @app.get("/{file_path:path}")
     async def serve_spa(file_path: str):
-        with belief_scope("serve_spa", f"path={file_path}"):
+        # Only serve SPA for non-API paths
-            # Don't serve SPA for API routes that fell through
+        # API routes are registered separately and should be matched by FastAPI first
-            if file_path.startswith("api/"):
+        if file_path and (file_path.startswith("api/") or file_path.startswith("/api/") or file_path == "api"):
-                logger.info(f"[DEBUG] API route fell through to serve_spa: {file_path}")
+            # This should not happen if API routers are properly registered
-                raise HTTPException(status_code=404, detail=f"API endpoint not found: {file_path}")
+            # Return 404 instead of serving HTML
+            raise HTTPException(status_code=404, detail=f"API endpoint not found: {file_path}")
         
-            full_path = frontend_path / file_path
+        full_path = frontend_path / file_path
-            if full_path.is_file():
+        if file_path and full_path.is_file():
-                return FileResponse(str(full_path))
+            return FileResponse(str(full_path))
-            # Fallback to index.html for SPA routing
+        return FileResponse(str(frontend_path / "index.html"))
-            return FileResponse(str(frontend_path / "index.html"))
     # [/DEF:serve_spa:Function]
 else:
     # [DEF:read_root:Function]

backend/src/core/auth/__tests__/test_auth.py

@@ -0,0 +1,179 @@
+# [DEF:test_auth:Module]
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for authentication module
+# @LAYER: Domain
+# @RELATION: VERIFIES -> src.core.auth
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent.parent.parent.parent / "src"))
+
+import pytest
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from src.core.database import Base
+from src.models.auth import User, Role, Permission, ADGroupMapping
+from src.services.auth_service import AuthService
+from src.core.auth.repository import AuthRepository
+from src.core.auth.security import verify_password, get_password_hash
+
+# Create in-memory SQLite database for testing
+SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"
+
+engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
+TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+# Create all tables
+Base.metadata.create_all(bind=engine)
+
+
+@pytest.fixture
+def db_session():
+    """Create a new database session with a transaction, rollback after test"""
+    connection = engine.connect()
+    transaction = connection.begin()
+    session = TestingSessionLocal(bind=connection)
+    
+    yield session
+    
+    session.close()
+    transaction.rollback()
+    connection.close()
+
+
+@pytest.fixture
+def auth_service(db_session):
+    return AuthService(db_session)
+
+
+@pytest.fixture
+def auth_repo(db_session):
+    return AuthRepository(db_session)
+
+
+def test_create_user(auth_repo):
+    """Test user creation"""
+    user = User(
+        username="testuser",
+        email="test@example.com",
+        password_hash=get_password_hash("testpassword123"),
+        auth_source="LOCAL"
+    )
+    
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+    
+    retrieved_user = auth_repo.get_user_by_username("testuser")
+    assert retrieved_user is not None
+    assert retrieved_user.username == "testuser"
+    assert retrieved_user.email == "test@example.com"
+    assert verify_password("testpassword123", retrieved_user.password_hash)
+
+
+def test_authenticate_user(auth_service, auth_repo):
+    """Test user authentication with valid and invalid credentials"""
+    user = User(
+        username="testuser",
+        email="test@example.com",
+        password_hash=get_password_hash("testpassword123"),
+        auth_source="LOCAL"
+    )
+    
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+    
+    # Test valid credentials
+    authenticated_user = auth_service.authenticate_user("testuser", "testpassword123")
+    assert authenticated_user is not None
+    assert authenticated_user.username == "testuser"
+    
+    # Test invalid password
+    invalid_user = auth_service.authenticate_user("testuser", "wrongpassword")
+    assert invalid_user is None
+    
+    # Test invalid username
+    invalid_user = auth_service.authenticate_user("nonexistent", "testpassword123")
+    assert invalid_user is None
+
+
+def test_create_session(auth_service, auth_repo):
+    """Test session token creation"""
+    user = User(
+        username="testuser",
+        email="test@example.com",
+        password_hash=get_password_hash("testpassword123"),
+        auth_source="LOCAL"
+    )
+    
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+    
+    session = auth_service.create_session(user)
+    assert "access_token" in session
+    assert "token_type" in session
+    assert session["token_type"] == "bearer"
+    assert len(session["access_token"]) > 0
+
+
+def test_role_permission_association(auth_repo):
+    """Test role and permission association"""
+    role = Role(name="Admin", description="System administrator")
+    perm1 = Permission(resource="admin:users", action="READ")
+    perm2 = Permission(resource="admin:users", action="WRITE")
+    
+    role.permissions.extend([perm1, perm2])
+    
+    auth_repo.db.add(role)
+    auth_repo.db.commit()
+    
+    retrieved_role = auth_repo.get_role_by_name("Admin")
+    assert retrieved_role is not None
+    assert len(retrieved_role.permissions) == 2
+    
+    permissions = [f"{p.resource}:{p.action}" for p in retrieved_role.permissions]
+    assert "admin:users:READ" in permissions
+    assert "admin:users:WRITE" in permissions
+
+
+def test_user_role_association(auth_repo):
+    """Test user and role association"""
+    role = Role(name="Admin", description="System administrator")
+    user = User(
+        username="adminuser",
+        email="admin@example.com",
+        password_hash=get_password_hash("adminpass123"),
+        auth_source="LOCAL"
+    )
+    
+    user.roles.append(role)
+    
+    auth_repo.db.add(role)
+    auth_repo.db.add(user)
+    auth_repo.db.commit()
+    
+    retrieved_user = auth_repo.get_user_by_username("adminuser")
+    assert retrieved_user is not None
+    assert len(retrieved_user.roles) == 1
+    assert retrieved_user.roles[0].name == "Admin"
+
+
+def test_ad_group_mapping(auth_repo):
+    """Test AD group mapping"""
+    role = Role(name="ADFS_Admin", description="ADFS administrators")
+    
+    auth_repo.db.add(role)
+    auth_repo.db.commit()
+    
+    mapping = ADGroupMapping(ad_group="DOMAIN\\ADFS_Admins", role_id=role.id)
+    
+    auth_repo.db.add(mapping)
+    auth_repo.db.commit()
+    
+    retrieved_mapping = auth_repo.db.query(ADGroupMapping).filter_by(ad_group="DOMAIN\\ADFS_Admins").first()
+    assert retrieved_mapping is not None
+    assert retrieved_mapping.role_id == role.id
+
+
+# [/DEF:test_auth:Module]

backend/src/core/auth/config.py

@@ -0,0 +1,44 @@
+# [DEF:backend.src.core.auth.config:Module]
+#
+# @SEMANTICS: auth, config, settings, jwt, adfs
+# @PURPOSE:   Centralized configuration for authentication and authorization.
+# @LAYER:     Core
+# @RELATION:  DEPENDS_ON -> pydantic
+#
+# @INVARIANT: All sensitive configuration must have defaults or be loaded from environment.
+
+# [SECTION: IMPORTS]
+from pydantic import Field
+from pydantic_settings import BaseSettings
+# [/SECTION]
+
+# [DEF:AuthConfig:Class]
+# @PURPOSE: Holds authentication-related settings.
+# @PRE:     Environment variables may be provided via .env file.
+# @POST:    Returns a configuration object with validated settings.
+class AuthConfig(BaseSettings):
+    # JWT Settings
+    SECRET_KEY: str = Field(default="super-secret-key-change-in-production", env="AUTH_SECRET_KEY")
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 480
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+
+    # Database Settings
+    AUTH_DATABASE_URL: str = Field(default="sqlite:///./backend/auth.db", env="AUTH_DATABASE_URL")
+
+    # ADFS Settings
+    ADFS_CLIENT_ID: str = Field(default="", env="ADFS_CLIENT_ID")
+    ADFS_CLIENT_SECRET: str = Field(default="", env="ADFS_CLIENT_SECRET")
+    ADFS_METADATA_URL: str = Field(default="", env="ADFS_METADATA_URL")
+    
+    class Config:
+        env_file = ".env"
+        extra = "ignore"
+# [/DEF:AuthConfig:Class]
+
+# [DEF:auth_config:Variable]
+# @PURPOSE: Singleton instance of AuthConfig.
+auth_config = AuthConfig()
+# [/DEF:auth_config:Variable]
+
+# [/DEF:backend.src.core.auth.config:Module]

backend/src/core/auth/jwt.py

@@ -0,0 +1,55 @@
+# [DEF:backend.src.core.auth.jwt:Module]
+#
+# @TIER:      STANDARD
+# @SEMANTICS: jwt, token, session, auth
+# @PURPOSE:   JWT token generation and validation logic.
+# @LAYER:     Core
+# @RELATION:  DEPENDS_ON -> jose
+# @RELATION:  USES -> backend.src.core.auth.config.auth_config
+#
+# @INVARIANT: Tokens must include expiration time and user identifier.
+
+# [SECTION: IMPORTS]
+from datetime import datetime, timedelta
+from typing import Optional
+from jose import jwt
+from .config import auth_config
+from ..logger import belief_scope
+# [/SECTION]
+
+# [DEF:create_access_token:Function]
+# @PURPOSE: Generates a new JWT access token.
+# @PRE:     data dict contains 'sub' (user_id) and optional 'scopes' (roles).
+# @POST:    Returns a signed JWT string.
+#
+# @PARAM:   data (dict) - Payload data for the token.
+# @PARAM:   expires_delta (Optional[timedelta]) - Custom expiration time.
+# @RETURN:  str - The encoded JWT.
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    with belief_scope("create_access_token"):
+        to_encode = data.copy()
+        if expires_delta:
+            expire = datetime.utcnow() + expires_delta
+        else:
+            expire = datetime.utcnow() + timedelta(minutes=auth_config.ACCESS_TOKEN_EXPIRE_MINUTES)
+        
+        to_encode.update({"exp": expire})
+        encoded_jwt = jwt.encode(to_encode, auth_config.SECRET_KEY, algorithm=auth_config.ALGORITHM)
+        return encoded_jwt
+# [/DEF:create_access_token:Function]
+
+# [DEF:decode_token:Function]
+# @PURPOSE: Decodes and validates a JWT token.
+# @PRE:     token is a signed JWT string.
+# @POST:    Returns the decoded payload if valid.
+#
+# @PARAM:   token (str) - The JWT to decode.
+# @RETURN:  dict - The decoded payload.
+# @THROW:   jose.JWTError - If token is invalid or expired.
+def decode_token(token: str) -> dict:
+    with belief_scope("decode_token"):
+        payload = jwt.decode(token, auth_config.SECRET_KEY, algorithms=[auth_config.ALGORITHM])
+        return payload
+# [/DEF:decode_token:Function]
+
+# [/DEF:backend.src.core.auth.jwt:Module]

backend/src/core/auth/logger.py

@@ -0,0 +1,32 @@
+# [DEF:backend.src.core.auth.logger:Module]
+#
+# @TIER:      STANDARD
+# @SEMANTICS: auth, logger, audit, security
+# @PURPOSE:   Audit logging for security-related events.
+# @LAYER:     Core
+# @RELATION:  USES -> backend.src.core.logger.belief_scope
+#
+# @INVARIANT: Must not log sensitive data like passwords or full tokens.
+
+# [SECTION: IMPORTS]
+from ..logger import logger, belief_scope
+from datetime import datetime
+# [/SECTION]
+
+# [DEF:log_security_event:Function]
+# @PURPOSE: Logs a security-related event for audit trails.
+# @PRE:     event_type and username are strings.
+# @POST:    Security event is written to the application log.
+# @PARAM:   event_type (str) - Type of event (e.g., LOGIN_SUCCESS, PERMISSION_DENIED).
+# @PARAM:   username (str) - The user involved in the event.
+# @PARAM:   details (dict) - Additional non-sensitive metadata.
+def log_security_event(event_type: str, username: str, details: dict = None):
+    with belief_scope("log_security_event", f"{event_type}:{username}"):
+        timestamp = datetime.utcnow().isoformat()
+        msg = f"[AUDIT][{timestamp}][{event_type}] User: {username}"
+        if details:
+            msg += f" Details: {details}"
+        logger.info(msg)
+# [/DEF:log_security_event:Function]
+
+# [/DEF:backend.src.core.auth.logger:Module]

backend/src/core/auth/oauth.py

@@ -0,0 +1,51 @@
+# [DEF:backend.src.core.auth.oauth:Module]
+#
+# @SEMANTICS: auth, oauth, oidc, adfs
+# @PURPOSE:   ADFS OIDC configuration and client using Authlib.
+# @LAYER:     Core
+# @RELATION:  DEPENDS_ON -> authlib
+# @RELATION:  USES -> backend.src.core.auth.config.auth_config
+#
+# @INVARIANT: Must use secure OIDC flows.
+
+# [SECTION: IMPORTS]
+from authlib.integrations.starlette_client import OAuth
+from .config import auth_config
+# [/SECTION]
+
+# [DEF:oauth:Variable]
+# @PURPOSE: Global Authlib OAuth registry.
+oauth = OAuth()
+# [/DEF:oauth:Variable]
+
+# [DEF:register_adfs:Function]
+# @PURPOSE: Registers the ADFS OIDC client.
+# @PRE:     ADFS configuration is provided in auth_config.
+# @POST:    ADFS client is registered in oauth registry.
+def register_adfs():
+    if auth_config.ADFS_CLIENT_ID:
+        oauth.register(
+            name='adfs',
+            client_id=auth_config.ADFS_CLIENT_ID,
+            client_secret=auth_config.ADFS_CLIENT_SECRET,
+            server_metadata_url=auth_config.ADFS_METADATA_URL,
+            client_kwargs={
+                'scope': 'openid email profile groups'
+            }
+        )
+# [/DEF:register_adfs:Function]
+
+# [DEF:is_adfs_configured:Function]
+# @PURPOSE: Checks if ADFS is properly configured.
+# @PRE:     None.
+# @POST:    Returns True if ADFS client is registered, False otherwise.
+# @RETURN:  bool - Configuration status.
+def is_adfs_configured() -> bool:
+    """Check if ADFS OAuth client is registered."""
+    return 'adfs' in oauth._registry
+# [/DEF:is_adfs_configured:Function]
+
+# Initial registration
+register_adfs()
+
+# [/DEF:backend.src.core.auth.oauth:Module]

backend/src/core/auth/repository.py

@@ -0,0 +1,123 @@
+# [DEF:backend.src.core.auth.repository:Module]
+#
+# @SEMANTICS: auth, repository, database, user, role
+# @PURPOSE:   Data access layer for authentication-related entities.
+# @LAYER:     Core
+# @RELATION:  DEPENDS_ON -> sqlalchemy
+# @RELATION:  USES -> backend.src.models.auth
+#
+# @INVARIANT: All database operations must be performed within a session.
+
+# [SECTION: IMPORTS]
+from typing import Optional, List
+from sqlalchemy.orm import Session
+from ...models.auth import User, Role, Permission
+from ..logger import belief_scope
+# [/SECTION]
+
+# [DEF:AuthRepository:Class]
+# @PURPOSE: Encapsulates database operations for authentication.
+class AuthRepository:
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the repository with a database session.
+    # @PARAM:   db (Session) - SQLAlchemy session.
+    def __init__(self, db: Session):
+        self.db = db
+    # [/DEF:__init__:Function]
+
+    # [DEF:get_user_by_username:Function]
+    # @PURPOSE: Retrieves a user by their username.
+    # @PRE:     username is a string.
+    # @POST:    Returns User object if found, else None.
+    # @PARAM:   username (str) - The username to search for.
+    # @RETURN:  Optional[User] - The found user or None.
+    def get_user_by_username(self, username: str) -> Optional[User]:
+        with belief_scope("AuthRepository.get_user_by_username"):
+            return self.db.query(User).filter(User.username == username).first()
+    # [/DEF:get_user_by_username:Function]
+
+    # [DEF:get_user_by_id:Function]
+    # @PURPOSE: Retrieves a user by their unique ID.
+    # @PRE:     user_id is a valid UUID string.
+    # @POST:    Returns User object if found, else None.
+    # @PARAM:   user_id (str) - The user's unique identifier.
+    # @RETURN:  Optional[User] - The found user or None.
+    def get_user_by_id(self, user_id: str) -> Optional[User]:
+        with belief_scope("AuthRepository.get_user_by_id"):
+            return self.db.query(User).filter(User.id == user_id).first()
+    # [/DEF:get_user_by_id:Function]
+
+    # [DEF:get_role_by_name:Function]
+    # @PURPOSE: Retrieves a role by its name.
+    # @PRE:     name is a string.
+    # @POST:    Returns Role object if found, else None.
+    # @PARAM:   name (str) - The role name to search for.
+    # @RETURN:  Optional[Role] - The found role or None.
+    def get_role_by_name(self, name: str) -> Optional[Role]:
+        with belief_scope("AuthRepository.get_role_by_name"):
+            return self.db.query(Role).filter(Role.name == name).first()
+    # [/DEF:get_role_by_name:Function]
+
+    # [DEF:update_last_login:Function]
+    # @PURPOSE: Updates the last_login timestamp for a user.
+    # @PRE:     user object is a valid User instance.
+    # @POST:    User's last_login is updated in the database.
+    # @SIDE_EFFECT: Commits the transaction.
+    # @PARAM:   user (User) - The user to update.
+    def update_last_login(self, user: User):
+        with belief_scope("AuthRepository.update_last_login"):
+            from datetime import datetime
+            user.last_login = datetime.utcnow()
+            self.db.add(user)
+            self.db.commit()
+    # [/DEF:update_last_login:Function]
+
+    # [DEF:get_role_by_id:Function]
+    # @PURPOSE: Retrieves a role by its unique ID.
+    # @PRE:     role_id is a string.
+    # @POST:    Returns Role object if found, else None.
+    # @PARAM:   role_id (str) - The role's unique identifier.
+    # @RETURN:  Optional[Role] - The found role or None.
+    def get_role_by_id(self, role_id: str) -> Optional[Role]:
+        with belief_scope("AuthRepository.get_role_by_id"):
+            return self.db.query(Role).filter(Role.id == role_id).first()
+    # [/DEF:get_role_by_id:Function]
+
+    # [DEF:get_permission_by_id:Function]
+    # @PURPOSE: Retrieves a permission by its unique ID.
+    # @PRE:     perm_id is a string.
+    # @POST:    Returns Permission object if found, else None.
+    # @PARAM:   perm_id (str) - The permission's unique identifier.
+    # @RETURN:  Optional[Permission] - The found permission or None.
+    def get_permission_by_id(self, perm_id: str) -> Optional[Permission]:
+        with belief_scope("AuthRepository.get_permission_by_id"):
+            return self.db.query(Permission).filter(Permission.id == perm_id).first()
+    # [/DEF:get_permission_by_id:Function]
+
+    # [DEF:get_permission_by_resource_action:Function]
+    # @PURPOSE: Retrieves a permission by resource and action.
+    # @PRE:     resource and action are strings.
+    # @POST:    Returns Permission object if found, else None.
+    # @PARAM:   resource (str) - The resource name.
+    # @PARAM:   action (str) - The action name.
+    # @RETURN:  Optional[Permission] - The found permission or None.
+    def get_permission_by_resource_action(self, resource: str, action: str) -> Optional[Permission]:
+        with belief_scope("AuthRepository.get_permission_by_resource_action"):
+            return self.db.query(Permission).filter(
+                Permission.resource == resource,
+                Permission.action == action
+            ).first()
+    # [/DEF:get_permission_by_resource_action:Function]
+
+    # [DEF:list_permissions:Function]
+    # @PURPOSE: Lists all available permissions.
+    # @POST:    Returns a list of all Permission objects.
+    # @RETURN:  List[Permission] - List of permissions.
+    def list_permissions(self) -> List[Permission]:
+        with belief_scope("AuthRepository.list_permissions"):
+            return self.db.query(Permission).all()
+    # [/DEF:list_permissions:Function]
+
+# [/DEF:AuthRepository:Class]
+
+# [/DEF:backend.src.core.auth.repository:Module]

backend/src/core/auth/security.py

@@ -0,0 +1,42 @@
+# [DEF:backend.src.core.auth.security:Module]
+#
+# @SEMANTICS: security, password, hashing, bcrypt
+# @PURPOSE:   Utility for password hashing and verification using Passlib.
+# @LAYER:     Core
+# @RELATION:  DEPENDS_ON -> passlib
+#
+# @INVARIANT: Uses bcrypt for hashing with standard work factor.
+
+# [SECTION: IMPORTS]
+from passlib.context import CryptContext
+# [/SECTION]
+
+# [DEF:pwd_context:Variable]
+# @PURPOSE: Passlib CryptContext for password management.
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+# [/DEF:pwd_context:Variable]
+
+# [DEF:verify_password:Function]
+# @PURPOSE: Verifies a plain password against a hashed password.
+# @PRE:     plain_password is a string, hashed_password is a bcrypt hash.
+# @POST:    Returns True if password matches, False otherwise.
+#
+# @PARAM:   plain_password (str) - The unhashed password.
+# @PARAM:   hashed_password (str) - The stored hash.
+# @RETURN:  bool - Verification result.
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(plain_password, hashed_password)
+# [/DEF:verify_password:Function]
+
+# [DEF:get_password_hash:Function]
+# @PURPOSE: Generates a bcrypt hash for a plain password.
+# @PRE:     password is a string.
+# @POST:    Returns a secure bcrypt hash string.
+#
+# @PARAM:   password (str) - The password to hash.
+# @RETURN:  str - The generated hash.
+def get_password_hash(password: str) -> str:
+    return pwd_context.hash(password)
+# [/DEF:get_password_hash:Function]
+
+# [/DEF:backend.src.core.auth.security:Module]

backend/src/core/config_manager.py

@@ -15,7 +15,7 @@ import json
 import os
 from pathlib import Path
 from typing import Optional, List
-from .config_models import AppConfig, Environment, GlobalSettings
+from .config_models import AppConfig, Environment, GlobalSettings, StorageConfig
 from .logger import logger, configure_logger, belief_scope
 # [/SECTION]
 
@@ -46,7 +46,7 @@ class ConfigManager:
             # 3. Runtime check of @POST
             assert isinstance(self.config, AppConfig), "self.config must be an instance of AppConfig"
 
-            logger.info(f"[ConfigManager][Exit] Initialized")
+            logger.info("[ConfigManager][Exit] Initialized")
     # [/DEF:__init__:Function]
 
     # [DEF:_load_config:Function]
@@ -59,19 +59,23 @@ class ConfigManager:
             logger.debug(f"[_load_config][Entry] Loading from {self.config_path}")
         
         if not self.config_path.exists():
-            logger.info(f"[_load_config][Action] Config file not found. Creating default.")
+            logger.info("[_load_config][Action] Config file not found. Creating default.")
             default_config = AppConfig(
                 environments=[],
-                settings=GlobalSettings(backup_path="backups")
+                settings=GlobalSettings()
             )
             self._save_config_to_disk(default_config)
             return default_config
-        
         try:
             with open(self.config_path, "r") as f:
                 data = json.load(f)
+                
+                # Check for deprecated field
+                if "settings" in data and "backup_path" in data["settings"]:
+                    del data["settings"]["backup_path"]
+
                 config = AppConfig(**data)
-                logger.info(f"[_load_config][Coherence:OK] Configuration loaded")
+                logger.info("[_load_config][Coherence:OK] Configuration loaded")
                 return config
         except Exception as e:
             logger.error(f"[_load_config][Coherence:Failed] Error loading config: {e}")
@@ -79,7 +83,7 @@ class ConfigManager:
             # For now, return default to be safe, but log the error prominently.
             return AppConfig(
                 environments=[],
-                settings=GlobalSettings(backup_path="backups")
+                settings=GlobalSettings(storage=StorageConfig())
             )
     # [/DEF:_load_config:Function]
 
@@ -99,7 +103,7 @@ class ConfigManager:
         try:
             with open(self.config_path, "w") as f:
                 json.dump(config.dict(), f, indent=4)
-            logger.info(f"[_save_config_to_disk][Action] Configuration saved")
+            logger.info("[_save_config_to_disk][Action] Configuration saved")
         except Exception as e:
             logger.error(f"[_save_config_to_disk][Coherence:Failed] Failed to save: {e}")
     # [/DEF:_save_config_to_disk:Function]
@@ -130,7 +134,7 @@ class ConfigManager:
     # @PARAM: settings (GlobalSettings) - The new global settings.
     def update_global_settings(self, settings: GlobalSettings):
         with belief_scope("update_global_settings"):
-            logger.info(f"[update_global_settings][Entry] Updating settings")
+            logger.info("[update_global_settings][Entry] Updating settings")
         
         # 1. Runtime check of @PRE
         assert isinstance(settings, GlobalSettings), "settings must be an instance of GlobalSettings"
@@ -142,7 +146,7 @@ class ConfigManager:
         # Reconfigure logger with new settings
         configure_logger(settings.logging)
 
-        logger.info(f"[update_global_settings][Exit] Settings updated")
+        logger.info("[update_global_settings][Exit] Settings updated")
     # [/DEF:update_global_settings:Function]
 
     # [DEF:validate_path:Function]
@@ -218,7 +222,7 @@ class ConfigManager:
         self.config.environments.append(env)
         self.save()
         
-        logger.info(f"[add_environment][Exit] Environment added")
+        logger.info("[add_environment][Exit] Environment added")
     # [/DEF:add_environment:Function]
 
     # [DEF:update_environment:Function]

backend/src/core/config_models.py

@@ -1,4 +1,5 @@
 # [DEF:ConfigModels:Module]
+# @TIER: STANDARD
 # @SEMANTICS: config, models, pydantic
 # @PURPOSE: Defines the data models for application configuration using Pydantic.
 # @LAYER: Core
@@ -7,6 +8,7 @@
 
 from pydantic import BaseModel, Field
 from typing import List, Optional
+from ..models.storage import StorageConfig
 
 # [DEF:Schedule:DataClass]
 # @PURPOSE: Represents a backup schedule configuration.
@@ -33,6 +35,7 @@ class Environment(BaseModel):
 # @PURPOSE: Defines the configuration for the application's logging system.
 class LoggingConfig(BaseModel):
     level: str = "INFO"
+    task_log_level: str = "INFO"  # Minimum level for task-specific logs (DEBUG, INFO, WARNING, ERROR)
     file_path: Optional[str] = "logs/app.log"
     max_bytes: int = 10 * 1024 * 1024
     backup_count: int = 5
@@ -42,9 +45,11 @@ class LoggingConfig(BaseModel):
 # [DEF:GlobalSettings:DataClass]
 # @PURPOSE: Represents global application settings.
 class GlobalSettings(BaseModel):
-    backup_path: str
+    storage: StorageConfig = Field(default_factory=StorageConfig)
     default_environment_id: Optional[str] = None
     logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    connections: List[dict] = []
+    llm: dict = Field(default_factory=lambda: {"providers": [], "default_provider": ""})
     
     # Task retention settings
     task_retention_days: int = 30

backend/src/core/database.py

@@ -5,54 +5,90 @@
 # @LAYER:     Core
 # @RELATION:  DEPENDS_ON -> sqlalchemy
 # @RELATION:  USES -> backend.src.models.mapping
+# @RELATION:  USES -> backend.src.core.auth.config
 #
 # @INVARIANT: A single engine instance is used for the entire application.
 
 # [SECTION: IMPORTS]
 from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker, Session
+from sqlalchemy.orm import sessionmaker
 from ..models.mapping import Base
 # Import models to ensure they're registered with Base
-from ..models.task import TaskRecord
-from ..models.connection import ConnectionConfig
 from .logger import belief_scope
+from .auth.config import auth_config
 import os
+from pathlib import Path
 # [/SECTION]
 
+# [DEF:BASE_DIR:Variable]
+# @PURPOSE: Base directory for the backend (where .db files should reside).
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+# [/DEF:BASE_DIR:Variable]
+
 # [DEF:DATABASE_URL:Constant]
-DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./mappings.db")
+# @PURPOSE: URL for the main mappings database.
+DATABASE_URL = os.getenv("DATABASE_URL", f"sqlite:///{BASE_DIR}/mappings.db")
 # [/DEF:DATABASE_URL:Constant]
 
 # [DEF:TASKS_DATABASE_URL:Constant]
-TASKS_DATABASE_URL = os.getenv("TASKS_DATABASE_URL", "sqlite:///./tasks.db")
+# @PURPOSE: URL for the tasks execution database.
+TASKS_DATABASE_URL = os.getenv("TASKS_DATABASE_URL", f"sqlite:///{BASE_DIR}/tasks.db")
 # [/DEF:TASKS_DATABASE_URL:Constant]
 
+# [DEF:AUTH_DATABASE_URL:Constant]
+# @PURPOSE: URL for the authentication database.
+AUTH_DATABASE_URL = os.getenv("AUTH_DATABASE_URL", auth_config.AUTH_DATABASE_URL)
+# If it's a relative sqlite path starting with ./backend/, fix it to be absolute or relative to BASE_DIR
+if AUTH_DATABASE_URL.startswith("sqlite:///./backend/"):
+    AUTH_DATABASE_URL = AUTH_DATABASE_URL.replace("sqlite:///./backend/", f"sqlite:///{BASE_DIR}/")
+elif AUTH_DATABASE_URL.startswith("sqlite:///./") and not AUTH_DATABASE_URL.startswith("sqlite:///./backend/"):
+    # If it's just ./ but we are in backend, it's fine, but let's make it absolute for robustness
+    AUTH_DATABASE_URL = AUTH_DATABASE_URL.replace("sqlite:///./", f"sqlite:///{BASE_DIR}/")
+# [/DEF:AUTH_DATABASE_URL:Constant]
+
 # [DEF:engine:Variable]
+# @PURPOSE: SQLAlchemy engine for mappings database.
 engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
 # [/DEF:engine:Variable]
 
 # [DEF:tasks_engine:Variable]
+# @PURPOSE: SQLAlchemy engine for tasks database.
 tasks_engine = create_engine(TASKS_DATABASE_URL, connect_args={"check_same_thread": False})
 # [/DEF:tasks_engine:Variable]
 
+# [DEF:auth_engine:Variable]
+# @PURPOSE: SQLAlchemy engine for authentication database.
+auth_engine = create_engine(AUTH_DATABASE_URL, connect_args={"check_same_thread": False})
+# [/DEF:auth_engine:Variable]
+
 # [DEF:SessionLocal:Class]
 # @PURPOSE: A session factory for the main mappings database.
+# @PRE: engine is initialized.
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 # [/DEF:SessionLocal:Class]
 
 # [DEF:TasksSessionLocal:Class]
 # @PURPOSE: A session factory for the tasks execution database.
+# @PRE: tasks_engine is initialized.
 TasksSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=tasks_engine)
 # [/DEF:TasksSessionLocal:Class]
 
+# [DEF:AuthSessionLocal:Class]
+# @PURPOSE: A session factory for the authentication database.
+# @PRE: auth_engine is initialized.
+AuthSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=auth_engine)
+# [/DEF:AuthSessionLocal:Class]
+
 # [DEF:init_db:Function]
 # @PURPOSE: Initializes the database by creating all tables.
-# @PRE: engine and tasks_engine are initialized.
+# @PRE: engine, tasks_engine and auth_engine are initialized.
-# @POST: Database tables created.
+# @POST: Database tables created in all databases.
+# @SIDE_EFFECT: Creates physical database files if they don't exist.
 def init_db():
     with belief_scope("init_db"):
         Base.metadata.create_all(bind=engine)
         Base.metadata.create_all(bind=tasks_engine)
+        Base.metadata.create_all(bind=auth_engine)
 # [/DEF:init_db:Function]
 
 # [DEF:get_db:Function]
@@ -83,4 +119,18 @@ def get_tasks_db():
             db.close()
 # [/DEF:get_tasks_db:Function]
 
+# [DEF:get_auth_db:Function]
+# @PURPOSE: Dependency for getting an authentication database session.
+# @PRE: AuthSessionLocal is initialized.
+# @POST:    Session is closed after use.
+# @RETURN:  Generator[Session, None, None]
+def get_auth_db():
+    with belief_scope("get_auth_db"):
+        db = AuthSessionLocal()
+        try:
+            yield db
+        finally:
+            db.close()
+# [/DEF:get_auth_db:Function]
+
 # [/DEF:backend.src.core.database:Module]

backend/src/core/logger.py

@@ -19,6 +19,9 @@ _belief_state = threading.local()
 # Global flag for belief state logging
 _enable_belief_state = True
 
+# Global task log level filter
+_task_log_level = "INFO"
+
 # [DEF:BeliefFormatter:Class]
 # @PURPOSE: Custom logging formatter that adds belief state prefixes to log messages.
 class BeliefFormatter(logging.Formatter):
@@ -28,6 +31,7 @@ class BeliefFormatter(logging.Formatter):
     # @POST: Returns formatted string.
     # @PARAM: record (logging.LogRecord) - The log record to format.
     # @RETURN: str - The formatted log message.
+    # @SEMANTICS: logging, formatter, context
     def format(self, record):
         anchor_id = getattr(_belief_state, 'anchor_id', None)
         if anchor_id:
@@ -54,14 +58,15 @@ class LogEntry(BaseModel):
 # @PARAM: message (str) - Optional entry message.
 # @PRE: anchor_id must be provided.
 # @POST: Thread-local belief state is updated and entry/exit logs are generated.
+# @SEMANTICS: logging, context, belief_state
 @contextmanager
 def belief_scope(anchor_id: str, message: str = ""):
-    # Log Entry if enabled
+    # Log Entry if enabled (DEBUG level to reduce noise)
     if _enable_belief_state:
         entry_msg = f"[{anchor_id}][Entry]"
         if message:
             entry_msg += f" {message}"
-        logger.info(entry_msg)
+        logger.debug(entry_msg)
 
     # Set thread-local anchor_id
     old_anchor = getattr(_belief_state, 'anchor_id', None)
@@ -69,13 +74,13 @@ def belief_scope(anchor_id: str, message: str = ""):
 
     try:
         yield
-        # Log Coherence OK and Exit
+        # Log Coherence OK and Exit (DEBUG level to reduce noise)
-        logger.info(f"[{anchor_id}][Coherence:OK]")
+        logger.debug(f"[{anchor_id}][Coherence:OK]")
         if _enable_belief_state:
-            logger.info(f"[{anchor_id}][Exit]")
+            logger.debug(f"[{anchor_id}][Exit]")
     except Exception as e:
-        # Log Coherence Failed
+        # Log Coherence Failed (DEBUG level to reduce noise)
-        logger.info(f"[{anchor_id}][Coherence:Failed] {str(e)}")
+        logger.debug(f"[{anchor_id}][Coherence:Failed] {str(e)}")
         raise
     finally:
         # Restore old anchor
@@ -86,11 +91,13 @@ def belief_scope(anchor_id: str, message: str = ""):
 # [DEF:configure_logger:Function]
 # @PURPOSE: Configures the logger with the provided logging settings.
 # @PRE: config is a valid LoggingConfig instance.
-# @POST: Logger level, handlers, and belief state flag are updated.
+# @POST: Logger level, handlers, belief state flag, and task log level are updated.
 # @PARAM: config (LoggingConfig) - The logging configuration.
+# @SEMANTICS: logging, configuration, initialization
 def configure_logger(config):
-    global _enable_belief_state
+    global _enable_belief_state, _task_log_level
     _enable_belief_state = config.enable_belief_state
+    _task_log_level = config.task_log_level.upper()
 
     # Set logger level
     level = getattr(logging, config.level.upper(), logging.INFO)
@@ -104,7 +111,6 @@ def configure_logger(config):
 
     # Add file handler if file_path is set
     if config.file_path:
-        import os
         from pathlib import Path
         log_file = Path(config.file_path)
         log_file.parent.mkdir(parents=True, exist_ok=True)
@@ -127,6 +133,36 @@ def configure_logger(config):
             ))
 # [/DEF:configure_logger:Function]
 
+# [DEF:get_task_log_level:Function]
+# @PURPOSE: Returns the current task log level filter.
+# @PRE: None.
+# @POST: Returns the task log level string.
+# @RETURN: str - The current task log level (DEBUG, INFO, WARNING, ERROR).
+# @SEMANTICS: logging, configuration, getter
+def get_task_log_level() -> str:
+    """Returns the current task log level filter."""
+    return _task_log_level
+# [/DEF:get_task_log_level:Function]
+
+# [DEF:should_log_task_level:Function]
+# @PURPOSE: Checks if a log level should be recorded based on task_log_level setting.
+# @PRE: level is a valid log level string.
+# @POST: Returns True if level meets or exceeds task_log_level threshold.
+# @PARAM: level (str) - The log level to check.
+# @RETURN: bool - True if the level should be logged.
+# @SEMANTICS: logging, filter, level
+def should_log_task_level(level: str) -> bool:
+    """Checks if a log level should be recorded based on task_log_level setting."""
+    level_order = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3}
+    current_level = _task_log_level.upper()
+    check_level = level.upper()
+    
+    current_order = level_order.get(current_level, 1)  # Default to INFO
+    check_order = level_order.get(check_level, 1)
+    
+    return check_order >= current_order
+# [/DEF:should_log_task_level:Function]
+
 # [DEF:WebSocketLogHandler:Class]
 # @SEMANTICS: logging, handler, websocket, buffer
 # @PURPOSE: A custom logging handler that captures log records into a buffer. It is designed to be extended for real-time log streaming over WebSockets.
@@ -140,6 +176,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: capacity is an integer.
     # @POST: Instance initialized with empty deque.
     # @PARAM: capacity (int) - Maximum number of logs to keep in memory.
+    # @SEMANTICS: logging, initialization, buffer
     def __init__(self, capacity: int = 1000):
         super().__init__()
         self.log_buffer: deque[LogEntry] = deque(maxlen=capacity)
@@ -152,6 +189,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: record is a logging.LogRecord.
     # @POST: Log is added to the log_buffer.
     # @PARAM: record (logging.LogRecord) - The log record to emit.
+    # @SEMANTICS: logging, handler, buffer
     def emit(self, record: logging.LogRecord):
         try:
             log_entry = LogEntry(
@@ -179,6 +217,7 @@ class WebSocketLogHandler(logging.Handler):
     # @PRE: None.
     # @POST: Returns list of LogEntry objects.
     # @RETURN: List[LogEntry] - List of buffered log entries.
+    # @SEMANTICS: logging, buffer, retrieval
     def get_recent_logs(self) -> List[LogEntry]:
         """
         Returns a list of recent log entries from the buffer.
@@ -196,12 +235,24 @@ logger = logging.getLogger("superset_tools_app")
 # [DEF:believed:Function]
 # @PURPOSE: A decorator that wraps a function in a belief scope.
 # @PARAM: anchor_id (str) - The identifier for the semantic block.
+# @PRE: anchor_id must be a string.
+# @POST: Returns a decorator function.
 def believed(anchor_id: str):
+    # [DEF:decorator:Function]
+    # @PURPOSE: Internal decorator for belief scope.
+    # @PRE: func must be a callable.
+    # @POST: Returns the wrapped function.
     def decorator(func):
+        # [DEF:wrapper:Function]
+        # @PURPOSE: Internal wrapper that enters belief scope.
+        # @PRE: None.
+        # @POST: Executes the function within a belief scope.
         def wrapper(*args, **kwargs):
             with belief_scope(anchor_id):
                 return func(*args, **kwargs)
+        # [/DEF:wrapper:Function]
         return wrapper
+    # [/DEF:decorator:Function]
     return decorator
 # [/DEF:believed:Function]
 logger.setLevel(logging.INFO)

backend/src/core/logger/__tests__/test_logger.py

@@ -0,0 +1,228 @@
+# [DEF:test_logger:Module]
+# @TIER: STANDARD
+# @PURPOSE: Unit tests for logger module
+# @LAYER: Infra
+# @RELATION: VERIFIES -> src.core.logger
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent.parent.parent.parent / "src"))
+
+import pytest
+from src.core.logger import (
+    belief_scope,
+    logger,
+    configure_logger,
+    get_task_log_level,
+    should_log_task_level
+)
+from src.core.config_models import LoggingConfig
+
+
+# [DEF:test_belief_scope_logs_entry_action_exit_at_debug:Function]
+# @PURPOSE: Test that belief_scope generates [ID][Entry], [ID][Action], and [ID][Exit] logs at DEBUG level.
+# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
+# @POST: Logs are verified to contain Entry, Action, and Exit tags at DEBUG level.
+def test_belief_scope_logs_entry_action_exit_at_debug(caplog):
+    """Test that belief_scope generates [ID][Entry], [ID][Action], and [ID][Exit] logs at DEBUG level."""
+    # Configure logger to DEBUG level
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+    
+    caplog.set_level("DEBUG")
+
+    with belief_scope("TestFunction"):
+        logger.info("Doing something important")
+
+    # Check that the logs contain the expected patterns
+    log_messages = [record.message for record in caplog.records]
+
+    assert any("[TestFunction][Entry]" in msg for msg in log_messages), "Entry log not found"
+    assert any("[TestFunction][Action] Doing something important" in msg for msg in log_messages), "Action log not found"
+    assert any("[TestFunction][Exit]" in msg for msg in log_messages), "Exit log not found"
+    
+    # Reset to INFO
+    config = LoggingConfig(level="INFO", task_log_level="INFO", enable_belief_state=True)
+    configure_logger(config)
+# [/DEF:test_belief_scope_logs_entry_action_exit_at_debug:Function]
+
+
+# [DEF:test_belief_scope_error_handling:Function]
+# @PURPOSE: Test that belief_scope logs Coherence:Failed on exception.
+# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
+# @POST: Logs are verified to contain Coherence:Failed tag.
+def test_belief_scope_error_handling(caplog):
+    """Test that belief_scope logs Coherence:Failed on exception."""
+    # Configure logger to DEBUG level
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+    
+    caplog.set_level("DEBUG")
+
+    with pytest.raises(ValueError):
+        with belief_scope("FailingFunction"):
+            raise ValueError("Something went wrong")
+
+    log_messages = [record.message for record in caplog.records]
+
+    assert any("[FailingFunction][Entry]" in msg for msg in log_messages), "Entry log not found"
+    assert any("[FailingFunction][Coherence:Failed]" in msg for msg in log_messages), "Failed coherence log not found"
+    # Exit should not be logged on failure
+    
+    # Reset to INFO
+    config = LoggingConfig(level="INFO", task_log_level="INFO", enable_belief_state=True)
+    configure_logger(config)
+# [/DEF:test_belief_scope_error_handling:Function]
+
+
+# [DEF:test_belief_scope_success_coherence:Function]
+# @PURPOSE: Test that belief_scope logs Coherence:OK on success.
+# @PRE: belief_scope is available. caplog fixture is used. Logger configured to DEBUG.
+# @POST: Logs are verified to contain Coherence:OK tag.
+def test_belief_scope_success_coherence(caplog):
+    """Test that belief_scope logs Coherence:OK on success."""
+    # Configure logger to DEBUG level
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+    
+    caplog.set_level("DEBUG")
+
+    with belief_scope("SuccessFunction"):
+        pass
+
+    log_messages = [record.message for record in caplog.records]
+
+    assert any("[SuccessFunction][Coherence:OK]" in msg for msg in log_messages), "Success coherence log not found"
+    
+    # Reset to INFO
+    config = LoggingConfig(level="INFO", task_log_level="INFO", enable_belief_state=True)
+    configure_logger(config)
+# [/DEF:test_belief_scope_success_coherence:Function]
+
+
+# [DEF:test_belief_scope_not_visible_at_info:Function]
+# @PURPOSE: Test that belief_scope Entry/Exit/Coherence logs are NOT visible at INFO level.
+# @PRE: belief_scope is available. caplog fixture is used.
+# @POST: Entry/Exit/Coherence logs are not captured at INFO level.
+def test_belief_scope_not_visible_at_info(caplog):
+    """Test that belief_scope Entry/Exit/Coherence logs are NOT visible at INFO level."""
+    caplog.set_level("INFO")
+
+    with belief_scope("InfoLevelFunction"):
+        logger.info("Doing something important")
+
+    log_messages = [record.message for record in caplog.records]
+
+    # Action log should be visible
+    assert any("[InfoLevelFunction][Action] Doing something important" in msg for msg in log_messages), "Action log not found"
+    # Entry/Exit/Coherence should NOT be visible at INFO level
+    assert not any("[InfoLevelFunction][Entry]" in msg for msg in log_messages), "Entry log should not be visible at INFO"
+    assert not any("[InfoLevelFunction][Exit]" in msg for msg in log_messages), "Exit log should not be visible at INFO"
+    assert not any("[InfoLevelFunction][Coherence:OK]" in msg for msg in log_messages), "Coherence log should not be visible at INFO"
+# [/DEF:test_belief_scope_not_visible_at_info:Function]
+
+
+# [DEF:test_task_log_level_default:Function]
+# @PURPOSE: Test that default task log level is INFO.
+# @PRE: None.
+# @POST: Default level is INFO.
+def test_task_log_level_default():
+    """Test that default task log level is INFO."""
+    level = get_task_log_level()
+    assert level == "INFO"
+# [/DEF:test_task_log_level_default:Function]
+
+
+# [DEF:test_should_log_task_level:Function]
+# @PURPOSE: Test that should_log_task_level correctly filters log levels.
+# @PRE: None.
+# @POST: Filtering works correctly for all level combinations.
+def test_should_log_task_level():
+    """Test that should_log_task_level correctly filters log levels."""
+    # Default level is INFO
+    assert should_log_task_level("ERROR") is True, "ERROR should be logged at INFO threshold"
+    assert should_log_task_level("WARNING") is True, "WARNING should be logged at INFO threshold"
+    assert should_log_task_level("INFO") is True, "INFO should be logged at INFO threshold"
+    assert should_log_task_level("DEBUG") is False, "DEBUG should NOT be logged at INFO threshold"
+# [/DEF:test_should_log_task_level:Function]
+
+
+# [DEF:test_configure_logger_task_log_level:Function]
+# @PURPOSE: Test that configure_logger updates task_log_level.
+# @PRE: LoggingConfig is available.
+# @POST: task_log_level is updated correctly.
+def test_configure_logger_task_log_level():
+    """Test that configure_logger updates task_log_level."""
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+    
+    assert get_task_log_level() == "DEBUG", "task_log_level should be DEBUG"
+    assert should_log_task_level("DEBUG") is True, "DEBUG should be logged at DEBUG threshold"
+    
+    # Reset to INFO
+    config = LoggingConfig(
+        level="INFO",
+        task_log_level="INFO",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+    assert get_task_log_level() == "INFO", "task_log_level should be reset to INFO"
+# [/DEF:test_configure_logger_task_log_level:Function]
+
+
+# [DEF:test_enable_belief_state_flag:Function]
+# @PURPOSE: Test that enable_belief_state flag controls belief_scope logging.
+# @PRE: LoggingConfig is available. caplog fixture is used.
+# @POST: belief_scope logs are controlled by the flag.
+def test_enable_belief_state_flag(caplog):
+    """Test that enable_belief_state flag controls belief_scope logging."""
+    # Disable belief state
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=False
+    )
+    configure_logger(config)
+    
+    caplog.set_level("DEBUG")
+    
+    with belief_scope("DisabledFunction"):
+        logger.info("Doing something")
+    
+    log_messages = [record.message for record in caplog.records]
+    
+    # Entry and Exit should NOT be logged when disabled
+    assert not any("[DisabledFunction][Entry]" in msg for msg in log_messages), "Entry should not be logged when disabled"
+    assert not any("[DisabledFunction][Exit]" in msg for msg in log_messages), "Exit should not be logged when disabled"
+    # Coherence:OK should still be logged (internal tracking)
+    assert any("[DisabledFunction][Coherence:OK]" in msg for msg in log_messages), "Coherence should still be logged"
+    
+    # Re-enable for other tests
+    config = LoggingConfig(
+        level="DEBUG",
+        task_log_level="DEBUG",
+        enable_belief_state=True
+    )
+    configure_logger(config)
+# [/DEF:test_enable_belief_state_flag:Function]
+
+
+# [/DEF:test_logger:Module]

backend/src/core/migration_engine.py

@@ -11,12 +11,10 @@
 import zipfile
 import yaml
 import os
-import shutil
 import tempfile
 from pathlib import Path
 from typing import Dict
 from .logger import logger, belief_scope
-import yaml
 # [/SECTION]
 
 # [DEF:MigrationEngine:Class]

backend/src/core/plugin_base.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 from .logger import belief_scope
 
 from pydantic import BaseModel, Field
@@ -68,6 +68,33 @@ class PluginBase(ABC):
             pass
     # [/DEF:version:Function]
 
+    @property
+    # [DEF:required_permission:Function]
+    # @PURPOSE: Returns the required permission string to execute this plugin.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string permission.
+    # @RETURN: str - Required permission (e.g., "plugin:backup:execute").
+    def required_permission(self) -> str:
+        """The permission string required to execute this plugin."""
+        with belief_scope("required_permission"):
+            return f"plugin:{self.id}:execute"
+    # [/DEF:required_permission:Function]
+
+    @property
+    # [DEF:ui_route:Function]
+    # @PURPOSE: Returns the frontend route for the plugin's UI, if applicable.
+    # @PRE: Plugin instance exists.
+    # @POST: Returns string route or None.
+    # @RETURN: Optional[str] - Frontend route.
+    def ui_route(self) -> Optional[str]:
+        """
+        The frontend route for the plugin's UI.
+        Returns None if the plugin does not have a dedicated UI page.
+        """
+        with belief_scope("ui_route"):
+            return None
+    # [/DEF:ui_route:Function]
+
     @abstractmethod
     # [DEF:get_schema:Function]
     # @PURPOSE: Returns the JSON schema for the plugin's input parameters.
@@ -111,5 +138,6 @@ class PluginConfig(BaseModel):
     name: str = Field(..., description="Human-readable name for the plugin")
     description: str = Field(..., description="Brief description of what the plugin does")
     version: str = Field(..., description="Version of the plugin")
+    ui_route: Optional[str] = Field(None, description="Frontend route for the plugin UI")
     input_schema: Dict[str, Any] = Field(..., description="JSON schema for input parameters", alias="schema")
 # [/DEF:PluginConfig:Class]

backend/src/core/plugin_loader.py

@@ -1,12 +1,12 @@
 import importlib.util
 import os
 import sys # Added this line
-from typing import Dict, Type, List, Optional
+from typing import Dict, List, Optional
 from .plugin_base import PluginBase, PluginConfig
-from jsonschema import validate
 from .logger import belief_scope
 
 # [DEF:PluginLoader:Class]
+# @TIER: STANDARD
 # @SEMANTICS: plugin, loader, dynamic, import
 # @PURPOSE: Scans a specified directory for Python modules, dynamically loads them, and registers any classes that are valid implementations of the PluginBase interface.
 # @LAYER: Core
@@ -50,9 +50,18 @@ class PluginLoader:
             sys.path.insert(0, plugin_parent_dir)
 
         for filename in os.listdir(self.plugin_dir):
+            file_path = os.path.join(self.plugin_dir, filename)
+            
+            # Handle directory-based plugins (packages)
+            if os.path.isdir(file_path):
+                init_file = os.path.join(file_path, "__init__.py")
+                if os.path.exists(init_file):
+                    self._load_module(filename, init_file)
+                continue
+
+            # Handle single-file plugins
             if filename.endswith(".py") and filename != "__init__.py":
                 module_name = filename[:-3]
-                file_path = os.path.join(self.plugin_dir, filename)
                 self._load_module(module_name, file_path)
     # [/DEF:_load_plugins:Function]
 
@@ -132,6 +141,7 @@ class PluginLoader:
                 name=plugin_instance.name,
                 description=plugin_instance.description,
                 version=plugin_instance.version,
+                ui_route=plugin_instance.ui_route,
                 schema=schema,
             )
             # The following line is commented out because it requires a schema to be passed to validate against.

backend/src/core/scheduler.py

@@ -1,4 +1,5 @@
 # [DEF:SchedulerModule:Module]
+# @TIER: STANDARD
 # @SEMANTICS: scheduler, apscheduler, cron, backup
 # @PURPOSE: Manages scheduled tasks using APScheduler.
 # @LAYER: Core
@@ -9,11 +10,11 @@ from apscheduler.schedulers.background import BackgroundScheduler
 from apscheduler.triggers.cron import CronTrigger
 from .logger import logger, belief_scope
 from .config_manager import ConfigManager
-from typing import Optional
 import asyncio
 # [/SECTION]
 
 # [DEF:SchedulerService:Class]
+# @TIER: STANDARD
 # @SEMANTICS: scheduler, service, apscheduler
 # @PURPOSE: Provides a service to manage scheduled backup tasks.
 class SchedulerService:

backend/src/core/superset_client.py

@@ -13,10 +13,10 @@
 import json
 import zipfile
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union, cast
+from typing import Dict, List, Optional, Tuple, Union, cast
 from requests import Response
 from .logger import logger as app_logger, belief_scope
-from .utils.network import APIClient, SupersetAPIError, AuthenticationError, DashboardNotFoundError, NetworkError
+from .utils.network import APIClient, SupersetAPIError
 from .utils.fileio import get_filename_from_headers
 from .config_models import Environment
 # [/SECTION]
@@ -65,6 +65,8 @@ class SupersetClient:
     @property
     # [DEF:headers:Function]
     # @PURPOSE: Возвращает базовые HTTP-заголовки, используемые сетевым клиентом.
+    # @PRE: APIClient is initialized and authenticated.
+    # @POST: Returns a dictionary of HTTP headers.
     def headers(self) -> dict:
         with belief_scope("headers"):
             return self.network.headers
@@ -75,6 +77,8 @@ class SupersetClient:
     # [DEF:get_dashboards:Function]
     # @PURPOSE: Получает полный список дашбордов, автоматически обрабатывая пагинацию.
     # @PARAM: query (Optional[Dict]) - Дополнительные параметры запроса для API.
+    # @PRE: Client is authenticated.
+    # @POST: Returns a tuple with total count and list of dashboards.
     # @RETURN: Tuple[int, List[Dict]] - Кортеж (общее количество, список дашбордов).
     def get_dashboards(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
         with belief_scope("get_dashboards"):
@@ -83,17 +87,19 @@ class SupersetClient:
             if 'columns' not in validated_query:
                 validated_query['columns'] = ["slug", "id", "changed_on_utc", "dashboard_title", "published"]
             
-            total_count = self._fetch_total_object_count(endpoint="/dashboard/")
             paginated_data = self._fetch_all_pages(
                 endpoint="/dashboard/",
-                pagination_options={"base_query": validated_query, "total_count": total_count, "results_field": "result"},
+                pagination_options={"base_query": validated_query, "results_field": "result"},
             )
+            total_count = len(paginated_data)
             app_logger.info("[get_dashboards][Exit] Found %d dashboards.", total_count)
             return total_count, paginated_data
     # [/DEF:get_dashboards:Function]
 
     # [DEF:get_dashboards_summary:Function]
     # @PURPOSE: Fetches dashboard metadata optimized for the grid.
+    # @PRE: Client is authenticated.
+    # @POST: Returns a list of dashboard metadata summaries.
     # @RETURN: List[Dict]
     def get_dashboards_summary(self) -> List[Dict]:
         with belief_scope("SupersetClient.get_dashboards_summary"):
@@ -117,6 +123,8 @@ class SupersetClient:
     # [DEF:export_dashboard:Function]
     # @PURPOSE: Экспортирует дашборд в виде ZIP-архива.
     # @PARAM: dashboard_id (int) - ID дашборда для экспорта.
+    # @PRE: dashboard_id must exist in Superset.
+    # @POST: Returns ZIP content and filename.
     # @RETURN: Tuple[bytes, str] - Бинарное содержимое ZIP-архива и имя файла.
     def export_dashboard(self, dashboard_id: int) -> Tuple[bytes, str]:
         with belief_scope("export_dashboard"):
@@ -140,6 +148,8 @@ class SupersetClient:
     # @PARAM: file_name (Union[str, Path]) - Путь к ZIP-архиву.
     # @PARAM: dash_id (Optional[int]) - ID дашборда для удаления при сбое.
     # @PARAM: dash_slug (Optional[str]) - Slug дашборда для поиска ID.
+    # @PRE: file_name must be a valid ZIP dashboard export.
+    # @POST: Dashboard is imported or re-imported after deletion.
     # @RETURN: Dict - Ответ API в случае успеха.
     def import_dashboard(self, file_name: Union[str, Path], dash_id: Optional[int] = None, dash_slug: Optional[str] = None) -> Dict:
         with belief_scope("import_dashboard"):
@@ -165,6 +175,8 @@ class SupersetClient:
     # [DEF:delete_dashboard:Function]
     # @PURPOSE: Удаляет дашборд по его ID или slug.
     # @PARAM: dashboard_id (Union[int, str]) - ID или slug дашборда.
+    # @PRE: dashboard_id must exist.
+    # @POST: Dashboard is removed from Superset.
     def delete_dashboard(self, dashboard_id: Union[int, str]) -> None:
         with belief_scope("delete_dashboard"):
             app_logger.info("[delete_dashboard][Enter] Deleting dashboard %s.", dashboard_id)
@@ -183,24 +195,134 @@ class SupersetClient:
     # [DEF:get_datasets:Function]
     # @PURPOSE: Получает полный список датасетов, автоматически обрабатывая пагинацию.
     # @PARAM: query (Optional[Dict]) - Дополнительные параметры запроса.
+    # @PRE: Client is authenticated.
+    # @POST: Returns total count and list of datasets.
     # @RETURN: Tuple[int, List[Dict]] - Кортеж (общее количество, список датасетов).
     def get_datasets(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
         with belief_scope("get_datasets"):
             app_logger.info("[get_datasets][Enter] Fetching datasets.")
             validated_query = self._validate_query_params(query)
 
-            total_count = self._fetch_total_object_count(endpoint="/dataset/")
             paginated_data = self._fetch_all_pages(
                 endpoint="/dataset/",
-                pagination_options={"base_query": validated_query, "total_count": total_count, "results_field": "result"},
+                pagination_options={"base_query": validated_query, "results_field": "result"},
             )
+            total_count = len(paginated_data)
             app_logger.info("[get_datasets][Exit] Found %d datasets.", total_count)
             return total_count, paginated_data
     # [/DEF:get_datasets:Function]
 
+    # [DEF:get_datasets_summary:Function]
+    # @PURPOSE: Fetches dataset metadata optimized for the Dataset Hub grid.
+    # @PRE: Client is authenticated.
+    # @POST: Returns a list of dataset metadata summaries.
+    # @RETURN: List[Dict]
+    def get_datasets_summary(self) -> List[Dict]:
+        with belief_scope("SupersetClient.get_datasets_summary"):
+            query = {
+                "columns": ["id", "table_name", "schema", "database"]
+            }
+            _, datasets = self.get_datasets(query=query)
+
+            # Map fields to match the contracts
+            result = []
+            for ds in datasets:
+                result.append({
+                    "id": ds.get("id"),
+                    "table_name": ds.get("table_name"),
+                    "schema": ds.get("schema"),
+                    "database": ds.get("database", {}).get("database_name", "Unknown")
+                })
+            return result
+    # [/DEF:get_datasets_summary:Function]
+
+    # [DEF:get_dataset_detail:Function]
+    # @PURPOSE: Fetches detailed dataset information including columns and linked dashboards
+    # @PRE: Client is authenticated and dataset_id exists.
+    # @POST: Returns detailed dataset info with columns and linked dashboards.
+    # @PARAM: dataset_id (int) - The dataset ID to fetch details for.
+    # @RETURN: Dict - Dataset details with columns and linked_dashboards.
+    # @RELATION: CALLS -> self.get_dataset
+    # @RELATION: CALLS -> self.network.request (for related_objects)
+    def get_dataset_detail(self, dataset_id: int) -> Dict:
+        with belief_scope("SupersetClient.get_dataset_detail", f"id={dataset_id}"):
+            # Get base dataset info
+            response = self.get_dataset(dataset_id)
+            
+            # If the response is a dict and has a 'result' key, use that (standard Superset API)
+            if isinstance(response, dict) and 'result' in response:
+                dataset = response['result']
+            else:
+                dataset = response
+
+            # Extract columns information
+            columns = dataset.get("columns", [])
+            column_info = []
+            for col in columns:
+                column_info.append({
+                    "id": col.get("id"),
+                    "name": col.get("column_name"),
+                    "type": col.get("type"),
+                    "is_dttm": col.get("is_dttm", False),
+                    "is_active": col.get("is_active", True),
+                    "description": col.get("description", "")
+                })
+            
+            # Get linked dashboards using related_objects endpoint
+            linked_dashboards = []
+            try:
+                related_objects = self.network.request(
+                    method="GET",
+                    endpoint=f"/dataset/{dataset_id}/related_objects"
+                )
+                
+                # Handle different response formats
+                if isinstance(related_objects, dict):
+                    if "dashboards" in related_objects:
+                        dashboards_data = related_objects["dashboards"]
+                    elif "result" in related_objects and isinstance(related_objects["result"], dict):
+                        dashboards_data = related_objects["result"].get("dashboards", [])
+                    else:
+                        dashboards_data = []
+                    
+                    for dash in dashboards_data:
+                        linked_dashboards.append({
+                            "id": dash.get("id"),
+                            "title": dash.get("dashboard_title") or dash.get("title", "Unknown"),
+                            "slug": dash.get("slug")
+                        })
+            except Exception as e:
+                app_logger.warning(f"[get_dataset_detail][Warning] Failed to fetch related dashboards: {e}")
+                linked_dashboards = []
+            
+            # Extract SQL table information
+            sql = dataset.get("sql", "")
+            
+            result = {
+                "id": dataset.get("id"),
+                "table_name": dataset.get("table_name"),
+                "schema": dataset.get("schema"),
+                "database": dataset.get("database", {}).get("database_name", "Unknown"),
+                "description": dataset.get("description", ""),
+                "columns": column_info,
+                "column_count": len(column_info),
+                "sql": sql,
+                "linked_dashboards": linked_dashboards,
+                "linked_dashboard_count": len(linked_dashboards),
+                "is_sqllab_view": dataset.get("is_sqllab_view", False),
+                "created_on": dataset.get("created_on"),
+                "changed_on": dataset.get("changed_on")
+            }
+            
+            app_logger.info(f"[get_dataset_detail][Exit] Got dataset {dataset_id} with {len(column_info)} columns and {len(linked_dashboards)} linked dashboards")
+            return result
+    # [/DEF:get_dataset_detail:Function]
+
     # [DEF:get_dataset:Function]
     # @PURPOSE: Получает информацию о конкретном датасете по его ID.
     # @PARAM: dataset_id (int) - ID датасета.
+    # @PRE: dataset_id must exist.
+    # @POST: Returns dataset details.
     # @RETURN: Dict - Информация о датасете.
     def get_dataset(self, dataset_id: int) -> Dict:
         with belief_scope("SupersetClient.get_dataset", f"id={dataset_id}"):
@@ -215,6 +337,8 @@ class SupersetClient:
     # @PURPOSE: Обновляет данные датасета по его ID.
     # @PARAM: dataset_id (int) - ID датасета.
     # @PARAM: data (Dict) - Данные для обновления.
+    # @PRE: dataset_id must exist.
+    # @POST: Dataset is updated in Superset.
     # @RETURN: Dict - Ответ API.
     def update_dataset(self, dataset_id: int, data: Dict) -> Dict:
         with belief_scope("SupersetClient.update_dataset", f"id={dataset_id}"):
@@ -237,6 +361,8 @@ class SupersetClient:
     # [DEF:get_databases:Function]
     # @PURPOSE: Получает полный список баз данных.
     # @PARAM: query (Optional[Dict]) - Дополнительные параметры запроса.
+    # @PRE: Client is authenticated.
+    # @POST: Returns total count and list of databases.
     # @RETURN: Tuple[int, List[Dict]] - Кортеж (общее количество, список баз данных).
     def get_databases(self, query: Optional[Dict] = None) -> Tuple[int, List[Dict]]:
         with belief_scope("get_databases"):
@@ -244,11 +370,12 @@ class SupersetClient:
             validated_query = self._validate_query_params(query or {})
             if 'columns' not in validated_query:
                 validated_query['columns'] = []
-            total_count = self._fetch_total_object_count(endpoint="/database/")
+            
             paginated_data = self._fetch_all_pages(
                 endpoint="/database/",
-                pagination_options={"base_query": validated_query, "total_count": total_count, "results_field": "result"},
+                pagination_options={"base_query": validated_query, "results_field": "result"},
             )
+            total_count = len(paginated_data)
             app_logger.info("[get_databases][Exit] Found %d databases.", total_count)
             return total_count, paginated_data
     # [/DEF:get_databases:Function]
@@ -256,6 +383,8 @@ class SupersetClient:
     # [DEF:get_database:Function]
     # @PURPOSE: Получает информацию о конкретной базе данных по её ID.
     # @PARAM: database_id (int) - ID базы данных.
+    # @PRE: database_id must exist.
+    # @POST: Returns database details.
     # @RETURN: Dict - Информация о базе данных.
     def get_database(self, database_id: int) -> Dict:
         with belief_scope("get_database"):
@@ -268,6 +397,8 @@ class SupersetClient:
 
     # [DEF:get_databases_summary:Function]
     # @PURPOSE: Fetch a summary of databases including uuid, name, and engine.
+    # @PRE: Client is authenticated.
+    # @POST: Returns list of database summaries.
     # @RETURN: List[Dict] - Summary of databases.
     def get_databases_summary(self) -> List[Dict]:
         with belief_scope("SupersetClient.get_databases_summary"):
@@ -286,6 +417,8 @@ class SupersetClient:
     # [DEF:get_database_by_uuid:Function]
     # @PURPOSE: Find a database by its UUID.
     # @PARAM: db_uuid (str) - The UUID of the database.
+    # @PRE: db_uuid must be a valid UUID string.
+    # @POST: Returns database info or None.
     # @RETURN: Optional[Dict] - Database info if found, else None.
     def get_database_by_uuid(self, db_uuid: str) -> Optional[Dict]:
         with belief_scope("SupersetClient.get_database_by_uuid", f"uuid={db_uuid}"):
@@ -301,6 +434,9 @@ class SupersetClient:
     # [SECTION: HELPERS]
 
     # [DEF:_resolve_target_id_for_delete:Function]
+    # @PURPOSE: Resolves a dashboard ID from either an ID or a slug.
+    # @PRE: Either dash_id or dash_slug should be provided.
+    # @POST: Returns the resolved ID or None.
     def _resolve_target_id_for_delete(self, dash_id: Optional[int], dash_slug: Optional[str]) -> Optional[int]:
         with belief_scope("_resolve_target_id_for_delete"):
             if dash_id is not None:
@@ -319,6 +455,9 @@ class SupersetClient:
     # [/DEF:_resolve_target_id_for_delete:Function]
 
     # [DEF:_do_import:Function]
+    # @PURPOSE: Performs the actual multipart upload for import.
+    # @PRE: file_name must be a path to an existing ZIP file.
+    # @POST: Returns the API response from the upload.
     def _do_import(self, file_name: Union[str, Path]) -> Dict:
         with belief_scope("_do_import"):
             app_logger.debug(f"[_do_import][State] Uploading file: {file_name}")
@@ -336,6 +475,9 @@ class SupersetClient:
     # [/DEF:_do_import:Function]
 
     # [DEF:_validate_export_response:Function]
+    # @PURPOSE: Validates that the export response is a non-empty ZIP archive.
+    # @PRE: response must be a valid requests.Response object.
+    # @POST: Raises SupersetAPIError if validation fails.
     def _validate_export_response(self, response: Response, dashboard_id: int) -> None:
         with belief_scope("_validate_export_response"):
             content_type = response.headers.get("Content-Type", "")
@@ -346,6 +488,9 @@ class SupersetClient:
     # [/DEF:_validate_export_response:Function]
 
     # [DEF:_resolve_export_filename:Function]
+    # @PURPOSE: Determines the filename for an exported dashboard.
+    # @PRE: response must contain Content-Disposition header or dashboard_id must be provided.
+    # @POST: Returns a sanitized filename string.
     def _resolve_export_filename(self, response: Response, dashboard_id: int) -> str:
         with belief_scope("_resolve_export_filename"):
             filename = get_filename_from_headers(dict(response.headers))
@@ -358,6 +503,9 @@ class SupersetClient:
     # [/DEF:_resolve_export_filename:Function]
 
     # [DEF:_validate_query_params:Function]
+    # @PURPOSE: Ensures query parameters have default page and page_size.
+    # @PRE: query can be None or a dictionary.
+    # @POST: Returns a dictionary with at least page and page_size.
     def _validate_query_params(self, query: Optional[Dict]) -> Dict:
         with belief_scope("_validate_query_params"):
             base_query = {"page": 0, "page_size": 1000}
@@ -365,6 +513,9 @@ class SupersetClient:
     # [/DEF:_validate_query_params:Function]
 
     # [DEF:_fetch_total_object_count:Function]
+    # @PURPOSE: Fetches the total number of items for a given endpoint.
+    # @PRE: endpoint must be a valid Superset API path.
+    # @POST: Returns the total count as an integer.
     def _fetch_total_object_count(self, endpoint: str) -> int:
         with belief_scope("_fetch_total_object_count"):
             return self.network.fetch_paginated_count(
@@ -375,12 +526,18 @@ class SupersetClient:
     # [/DEF:_fetch_total_object_count:Function]
 
     # [DEF:_fetch_all_pages:Function]
+    # @PURPOSE: Iterates through all pages to collect all data items.
+    # @PRE: pagination_options must contain base_query, total_count, and results_field.
+    # @POST: Returns a combined list of all items.
     def _fetch_all_pages(self, endpoint: str, pagination_options: Dict) -> List[Dict]:
         with belief_scope("_fetch_all_pages"):
             return self.network.fetch_paginated_data(endpoint=endpoint, pagination_options=pagination_options)
     # [/DEF:_fetch_all_pages:Function]
 
     # [DEF:_validate_import_file:Function]
+    # @PURPOSE: Validates that the file to be imported is a valid ZIP with metadata.yaml.
+    # @PRE: zip_path must be a path to a file.
+    # @POST: Raises error if file is missing, not a ZIP, or missing metadata.
     def _validate_import_file(self, zip_path: Union[str, Path]) -> None:
         with belief_scope("_validate_import_file"):
             path = Path(zip_path)

backend/src/core/task_manager/__init__.py

@@ -1,4 +1,5 @@
 # [DEF:TaskManagerPackage:Module]
+# @TIER: TRIVIAL
 # @SEMANTICS: task, manager, package, exports
 # @PURPOSE: Exports the public API of the task manager package.
 # @LAYER: Core

backend/src/core/task_manager/cleanup.py

@@ -1,47 +1,75 @@
 # [DEF:TaskCleanupModule:Module]
-# @SEMANTICS: task, cleanup, retention
+# @TIER: STANDARD
-# @PURPOSE: Implements task cleanup and retention policies.
+# @SEMANTICS: task, cleanup, retention, logs
+# @PURPOSE: Implements task cleanup and retention policies, including associated logs.
 # @LAYER: Core
-# @RELATION: Uses TaskPersistenceService to delete old tasks.
+# @RELATION: Uses TaskPersistenceService and TaskLogPersistenceService to delete old tasks and logs.
 
-from datetime import datetime, timedelta
+from typing import List
-from .persistence import TaskPersistenceService
+from .persistence import TaskPersistenceService, TaskLogPersistenceService
 from ..logger import logger, belief_scope
 from ..config_manager import ConfigManager
 
 # [DEF:TaskCleanupService:Class]
-# @PURPOSE: Provides methods to clean up old task records.
+# @PURPOSE: Provides methods to clean up old task records and their associated logs.
+# @TIER: STANDARD
 class TaskCleanupService:
     # [DEF:__init__:Function]
     # @PURPOSE: Initializes the cleanup service with dependencies.
     # @PRE:     persistence_service and config_manager are valid.
     # @POST:    Cleanup service is ready.
-    def __init__(self, persistence_service: TaskPersistenceService, config_manager: ConfigManager):
+    def __init__(
+        self,
+        persistence_service: TaskPersistenceService,
+        log_persistence_service: TaskLogPersistenceService,
+        config_manager: ConfigManager
+    ):
         self.persistence_service = persistence_service
+        self.log_persistence_service = log_persistence_service
         self.config_manager = config_manager
     # [/DEF:__init__:Function]
 
     # [DEF:run_cleanup:Function]
-    # @PURPOSE: Deletes tasks older than the configured retention period.
+    # @PURPOSE: Deletes tasks older than the configured retention period and their logs.
     # @PRE:     Config manager has valid settings.
-    # @POST:    Old tasks are deleted from persistence.
+    # @POST:    Old tasks and their logs are deleted from persistence.
     def run_cleanup(self):
         with belief_scope("TaskCleanupService.run_cleanup"):
             settings = self.config_manager.get_config().settings
             retention_days = settings.task_retention_days
             
-            # This is a simplified implementation. 
-            # In a real scenario, we would query IDs of tasks older than retention_days.
-            # For now, we'll log the action.
             logger.info(f"Cleaning up tasks older than {retention_days} days.")
             
-            # Re-loading tasks to check for limit
+            # Load tasks to check for limit
             tasks = self.persistence_service.load_tasks(limit=1000)
             if len(tasks) > settings.task_retention_limit:
-                to_delete = [t.id for t in tasks[settings.task_retention_limit:]]
+                to_delete: List[str] = [t.id for t in tasks[settings.task_retention_limit:]]
+                
+                # Delete logs first (before task records)
+                self.log_persistence_service.delete_logs_for_tasks(to_delete)
+                
+                # Then delete task records
                 self.persistence_service.delete_tasks(to_delete)
-                logger.info(f"Deleted {len(to_delete)} tasks exceeding limit of {settings.task_retention_limit}")
+                
+                logger.info(f"Deleted {len(to_delete)} tasks and their logs exceeding limit of {settings.task_retention_limit}")
     # [/DEF:run_cleanup:Function]
     
+    # [DEF:delete_task_with_logs:Function]
+    # @PURPOSE: Delete a single task and all its associated logs.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Task and all its logs are deleted.
+    # @PARAM: task_id (str) - The task ID to delete.
+    def delete_task_with_logs(self, task_id: str) -> None:
+        """Delete a single task and all its associated logs."""
+        with belief_scope("TaskCleanupService.delete_task_with_logs", f"task_id={task_id}"):
+            # Delete logs first
+            self.log_persistence_service.delete_logs_for_task(task_id)
+            
+            # Then delete task record
+            self.persistence_service.delete_tasks([task_id])
+            
+            logger.info(f"Deleted task {task_id} and its associated logs")
+    # [/DEF:delete_task_with_logs:Function]
+
 # [/DEF:TaskCleanupService:Class]
 # [/DEF:TaskCleanupModule:Module]

backend/src/core/task_manager/context.py

@@ -0,0 +1,115 @@
+# [DEF:TaskContextModule:Module]
+# @SEMANTICS: task, context, plugin, execution, logger
+# @PURPOSE: Provides execution context passed to plugins during task execution.
+# @LAYER: Core
+# @RELATION: DEPENDS_ON -> TaskLogger, USED_BY -> plugins
+# @TIER: CRITICAL
+# @INVARIANT: Each TaskContext is bound to a single task execution.
+
+# [SECTION: IMPORTS]
+from typing import Dict, Any, Callable
+from .task_logger import TaskLogger
+# [/SECTION]
+
+# [DEF:TaskContext:Class]
+# @SEMANTICS: context, task, execution, plugin
+# @PURPOSE: A container passed to plugin.execute() providing the logger and other task-specific utilities.
+# @TIER: CRITICAL
+# @INVARIANT: logger is always a valid TaskLogger instance.
+# @UX_STATE: Idle -> Active -> Complete
+class TaskContext:
+    """
+    Execution context provided to plugins during task execution.
+    
+    Usage:
+        def execute(params: dict, context: TaskContext = None):
+            if context:
+                context.logger.info("Starting process")
+                context.logger.progress("Processing items", percent=50)
+            # ... plugin logic
+    """
+    
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initialize the TaskContext with task-specific resources.
+    # @PRE: task_id is a valid task identifier, add_log_fn is callable.
+    # @POST: TaskContext is ready to be passed to plugin.execute().
+    # @PARAM: task_id (str) - The ID of the task.
+    # @PARAM: add_log_fn (Callable) - Function to add log to TaskManager.
+    # @PARAM: params (Dict) - Task parameters.
+    # @PARAM: default_source (str) - Default source for logs (default: "plugin").
+    def __init__(
+        self,
+        task_id: str,
+        add_log_fn: Callable,
+        params: Dict[str, Any],
+        default_source: str = "plugin"
+    ):
+        self._task_id = task_id
+        self._params = params
+        self._logger = TaskLogger(
+            task_id=task_id,
+            add_log_fn=add_log_fn,
+            source=default_source
+        )
+    # [/DEF:__init__:Function]
+    
+    # [DEF:task_id:Function]
+    # @PURPOSE: Get the task ID.
+    # @PRE: TaskContext must be initialized.
+    # @POST: Returns the task ID string.
+    # @RETURN: str - The task ID.
+    @property
+    def task_id(self) -> str:
+        return self._task_id
+    # [/DEF:task_id:Function]
+    
+    # [DEF:logger:Function]
+    # @PURPOSE: Get the TaskLogger instance for this context.
+    # @PRE: TaskContext must be initialized.
+    # @POST: Returns the TaskLogger instance.
+    # @RETURN: TaskLogger - The logger instance.
+    @property
+    def logger(self) -> TaskLogger:
+        return self._logger
+    # [/DEF:logger:Function]
+    
+    # [DEF:params:Function]
+    # @PURPOSE: Get the task parameters.
+    # @PRE: TaskContext must be initialized.
+    # @POST: Returns the parameters dictionary.
+    # @RETURN: Dict[str, Any] - The task parameters.
+    @property
+    def params(self) -> Dict[str, Any]:
+        return self._params
+    # [/DEF:params:Function]
+    
+    # [DEF:get_param:Function]
+    # @PURPOSE: Get a specific parameter value with optional default.
+    # @PRE: TaskContext must be initialized.
+    # @POST: Returns parameter value or default.
+    # @PARAM: key (str) - Parameter key.
+    # @PARAM: default (Any) - Default value if key not found.
+    # @RETURN: Any - Parameter value or default.
+    def get_param(self, key: str, default: Any = None) -> Any:
+        return self._params.get(key, default)
+    # [/DEF:get_param:Function]
+    
+    # [DEF:create_sub_context:Function]
+    # @PURPOSE: Create a sub-context with a different default source.
+    # @PRE: source is a non-empty string.
+    # @POST: Returns new TaskContext with different logger source.
+    # @PARAM: source (str) - New default source for logging.
+    # @RETURN: TaskContext - New context with different source.
+    def create_sub_context(self, source: str) -> "TaskContext":
+        """Create a sub-context with a different default source for logging."""
+        return TaskContext(
+            task_id=self._task_id,
+            add_log_fn=self._logger._add_log,
+            params=self._params,
+            default_source=source
+        )
+    # [/DEF:create_sub_context:Function]
+
+# [/DEF:TaskContext:Class]
+
+# [/DEF:TaskContextModule:Module]

backend/src/core/task_manager/manager.py

@@ -8,23 +8,33 @@
 
 # [SECTION: IMPORTS]
 import asyncio
+import threading
+import inspect
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime
 from typing import Dict, Any, List, Optional
-from concurrent.futures import ThreadPoolExecutor
 
-from .models import Task, TaskStatus, LogEntry
+from .models import Task, TaskStatus, LogEntry, LogFilter, LogStats
-from .persistence import TaskPersistenceService
+from .persistence import TaskPersistenceService, TaskLogPersistenceService
-from ..logger import logger, belief_scope
+from .context import TaskContext
+from ..logger import logger, belief_scope, should_log_task_level
 # [/SECTION]
 
 # [DEF:TaskManager:Class]
 # @SEMANTICS: task, manager, lifecycle, execution, state
 # @PURPOSE: Manages the lifecycle of tasks, including their creation, execution, and state tracking.
+# @TIER: CRITICAL
+# @INVARIANT: Task IDs are unique within the registry.
+# @INVARIANT: Each task has exactly one status at any time.
+# @INVARIANT: Log entries are never deleted after being added to a task.
 class TaskManager:
     """
     Manages the lifecycle of tasks, including their creation, execution, and state tracking.
     """
     
+    # Log flush interval in seconds
+    LOG_FLUSH_INTERVAL = 2.0
+    
     # [DEF:__init__:Function]
     # @PURPOSE: Initialize the TaskManager with dependencies.
     # @PRE:     plugin_loader is initialized.
@@ -35,8 +45,18 @@ class TaskManager:
             self.plugin_loader = plugin_loader
             self.tasks: Dict[str, Task] = {}
             self.subscribers: Dict[str, List[asyncio.Queue]] = {}
-            self.executor = ThreadPoolExecutor(max_workers=5) # For CPU-bound plugin execution
+            self.executor = ThreadPoolExecutor(max_workers=5)  # For CPU-bound plugin execution
             self.persistence_service = TaskPersistenceService()
+            self.log_persistence_service = TaskLogPersistenceService()
+            
+            # Log buffer: task_id -> List[LogEntry]
+            self._log_buffer: Dict[str, List[LogEntry]] = {}
+            self._log_buffer_lock = threading.Lock()
+            
+            # Flusher thread for batch writing logs
+            self._flusher_stop_event = threading.Event()
+            self._flusher_thread = threading.Thread(target=self._flusher_loop, daemon=True)
+            self._flusher_thread.start()
             
             try:
                 self.loop = asyncio.get_running_loop()
@@ -48,6 +68,59 @@ class TaskManager:
             self.load_persisted_tasks()
     # [/DEF:__init__:Function]
     
+    # [DEF:_flusher_loop:Function]
+    # @PURPOSE: Background thread that periodically flushes log buffer to database.
+    # @PRE: TaskManager is initialized.
+    # @POST: Logs are batch-written to database every LOG_FLUSH_INTERVAL seconds.
+    def _flusher_loop(self):
+        """Background thread that flushes log buffer to database."""
+        while not self._flusher_stop_event.is_set():
+            self._flush_logs()
+            self._flusher_stop_event.wait(self.LOG_FLUSH_INTERVAL)
+    # [/DEF:_flusher_loop:Function]
+    
+    # [DEF:_flush_logs:Function]
+    # @PURPOSE: Flush all buffered logs to the database.
+    # @PRE: None.
+    # @POST: All buffered logs are written to task_logs table.
+    def _flush_logs(self):
+        """Flush all buffered logs to the database."""
+        with self._log_buffer_lock:
+            task_ids = list(self._log_buffer.keys())
+        
+        for task_id in task_ids:
+            with self._log_buffer_lock:
+                logs = self._log_buffer.pop(task_id, [])
+            
+            if logs:
+                try:
+                    self.log_persistence_service.add_logs(task_id, logs)
+                except Exception as e:
+                    logger.error(f"Failed to flush logs for task {task_id}: {e}")
+                    # Re-add logs to buffer on failure
+                    with self._log_buffer_lock:
+                        if task_id not in self._log_buffer:
+                            self._log_buffer[task_id] = []
+                        self._log_buffer[task_id].extend(logs)
+    # [/DEF:_flush_logs:Function]
+    
+    # [DEF:_flush_task_logs:Function]
+    # @PURPOSE: Flush logs for a specific task immediately.
+    # @PRE: task_id exists.
+    # @POST: Task's buffered logs are written to database.
+    # @PARAM: task_id (str) - The task ID.
+    def _flush_task_logs(self, task_id: str):
+        """Flush logs for a specific task immediately."""
+        with self._log_buffer_lock:
+            logs = self._log_buffer.pop(task_id, [])
+        
+        if logs:
+            try:
+                self.log_persistence_service.add_logs(task_id, logs)
+            except Exception as e:
+                logger.error(f"Failed to flush logs for task {task_id}: {e}")
+    # [/DEF:_flush_task_logs:Function]
+
     # [DEF:create_task:Function]
     # @PURPOSE: Creates and queues a new task for execution.
     # @PRE:     Plugin with plugin_id exists. Params are valid.
@@ -63,7 +136,7 @@ class TaskManager:
                 logger.error(f"Plugin with ID '{plugin_id}' not found.")
                 raise ValueError(f"Plugin with ID '{plugin_id}' not found.")
 
-            plugin = self.plugin_loader.get_plugin(plugin_id)
+            self.plugin_loader.get_plugin(plugin_id)
             
             if not isinstance(params, dict):
                  logger.error("Task parameters must be a dictionary.")
@@ -78,7 +151,7 @@ class TaskManager:
     # [/DEF:create_task:Function]
 
     # [DEF:_run_task:Function]
-    # @PURPOSE: Internal method to execute a task.
+    # @PURPOSE: Internal method to execute a task with TaskContext support.
     # @PRE:     Task exists in registry.
     # @POST:    Task is executed, status updated to SUCCESS or FAILED.
     # @PARAM:   task_id (str) - The ID of the task to run.
@@ -91,30 +164,54 @@ class TaskManager:
             task.status = TaskStatus.RUNNING
             task.started_at = datetime.utcnow()
             self.persistence_service.persist_task(task)
-            self._add_log(task_id, "INFO", f"Task started for plugin '{plugin.name}'")
+            self._add_log(task_id, "INFO", f"Task started for plugin '{plugin.name}'", source="system")
 
             try:
-                # Execute plugin
+                # Prepare params and check if plugin supports new TaskContext
                 params = {**task.params, "_task_id": task_id}
                 
-                if asyncio.iscoroutinefunction(plugin.execute):
+                # Check if plugin's execute method accepts 'context' parameter
-                    task.result = await plugin.execute(params)
+                sig = inspect.signature(plugin.execute)
-                else:
+                accepts_context = 'context' in sig.parameters
-                    task.result = await self.loop.run_in_executor(
+                
-                        self.executor,
+                if accepts_context:
-                        plugin.execute,
+                    # Create TaskContext for new-style plugins
-                        params
+                    context = TaskContext(
+                        task_id=task_id,
+                        add_log_fn=self._add_log,
+                        params=params,
+                        default_source="plugin"
                     )
                     
+                    if asyncio.iscoroutinefunction(plugin.execute):
+                        task.result = await plugin.execute(params, context=context)
+                    else:
+                        task.result = await self.loop.run_in_executor(
+                            self.executor,
+                            lambda: plugin.execute(params, context=context)
+                        )
+                else:
+                    # Backward compatibility: old-style plugins without context
+                    if asyncio.iscoroutinefunction(plugin.execute):
+                        task.result = await plugin.execute(params)
+                    else:
+                        task.result = await self.loop.run_in_executor(
+                            self.executor,
+                            plugin.execute,
+                            params
+                        )
+                
                 logger.info(f"Task {task_id} completed successfully")
                 task.status = TaskStatus.SUCCESS
-                self._add_log(task_id, "INFO", f"Task completed successfully for plugin '{plugin.name}'")
+                self._add_log(task_id, "INFO", f"Task completed successfully for plugin '{plugin.name}'", source="system")
             except Exception as e:
                 logger.error(f"Task {task_id} failed: {e}")
                 task.status = TaskStatus.FAILED
-                self._add_log(task_id, "ERROR", f"Task failed: {e}", {"error_type": type(e).__name__})
+                self._add_log(task_id, "ERROR", f"Task failed: {e}", source="system", metadata={"error_type": type(e).__name__})
             finally:
                 task.finished_at = datetime.utcnow()
+                # Flush any remaining buffered logs before persisting task
+                self._flush_task_logs(task_id)
                 self.persistence_service.persist_task(task)
                 logger.info(f"Task {task_id} execution finished with status: {task.status}")
     # [/DEF:_run_task:Function]
@@ -151,7 +248,8 @@ class TaskManager:
     async def wait_for_resolution(self, task_id: str):
         with belief_scope("TaskManager.wait_for_resolution", f"task_id={task_id}"):
             task = self.tasks.get(task_id)
-            if not task: return
+            if not task:
+                return
             
             task.status = TaskStatus.AWAITING_MAPPING
             self.persistence_service.persist_task(task)
@@ -172,7 +270,8 @@ class TaskManager:
     async def wait_for_input(self, task_id: str):
         with belief_scope("TaskManager.wait_for_input", f"task_id={task_id}"):
             task = self.tasks.get(task_id)
-            if not task: return
+            if not task:
+                return
             
             # Status is already set to AWAITING_INPUT by await_input()
             self.task_futures[task_id] = self.loop.create_future()
@@ -224,36 +323,106 @@ class TaskManager:
     # [/DEF:get_tasks:Function]
 
     # [DEF:get_task_logs:Function]
-    # @PURPOSE: Retrieves logs for a specific task.
+    # @PURPOSE: Retrieves logs for a specific task (from memory for running, persistence for completed).
     # @PRE:     task_id is a string.
-    # @POST:    Returns list of LogEntry objects.
+    # @POST:    Returns list of LogEntry or TaskLog objects.
     # @PARAM:   task_id (str) - ID of the task.
+    # @PARAM:   log_filter (Optional[LogFilter]) - Filter parameters.
     # @RETURN:  List[LogEntry] - List of log entries.
-    def get_task_logs(self, task_id: str) -> List[LogEntry]:
+    def get_task_logs(self, task_id: str, log_filter: Optional[LogFilter] = None) -> List[LogEntry]:
         with belief_scope("TaskManager.get_task_logs", f"task_id={task_id}"):
             task = self.tasks.get(task_id)
+            
+            # For completed tasks, fetch from persistence
+            if task and task.status in [TaskStatus.SUCCESS, TaskStatus.FAILED]:
+                if log_filter is None:
+                    log_filter = LogFilter()
+                task_logs = self.log_persistence_service.get_logs(task_id, log_filter)
+                # Convert TaskLog to LogEntry for backward compatibility
+                return [
+                    LogEntry(
+                        timestamp=log.timestamp,
+                        level=log.level,
+                        message=log.message,
+                        source=log.source,
+                        metadata=log.metadata
+                    )
+                    for log in task_logs
+                ]
+            
+            # For running/pending tasks, return from memory
             return task.logs if task else []
     # [/DEF:get_task_logs:Function]
     
+    # [DEF:get_task_log_stats:Function]
+    # @PURPOSE: Get statistics about logs for a task.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Returns LogStats with counts by level and source.
+    # @PARAM: task_id (str) - The task ID.
+    # @RETURN: LogStats - Statistics about task logs.
+    def get_task_log_stats(self, task_id: str) -> LogStats:
+        with belief_scope("TaskManager.get_task_log_stats", f"task_id={task_id}"):
+            return self.log_persistence_service.get_log_stats(task_id)
+    # [/DEF:get_task_log_stats:Function]
+    
+    # [DEF:get_task_log_sources:Function]
+    # @PURPOSE: Get unique sources for a task's logs.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Returns list of unique source strings.
+    # @PARAM: task_id (str) - The task ID.
+    # @RETURN: List[str] - Unique source names.
+    def get_task_log_sources(self, task_id: str) -> List[str]:
+        with belief_scope("TaskManager.get_task_log_sources", f"task_id={task_id}"):
+            return self.log_persistence_service.get_sources(task_id)
+    # [/DEF:get_task_log_sources:Function]
+
     # [DEF:_add_log:Function]
-    # @PURPOSE: Adds a log entry to a task and notifies subscribers.
+    # @PURPOSE: Adds a log entry to a task buffer and notifies subscribers.
     # @PRE:     Task exists.
-    # @POST:    Log added to task and pushed to queues.
+    # @POST:    Log added to buffer and pushed to queues (if level meets task_log_level filter).
     # @PARAM:   task_id (str) - ID of the task.
     # @PARAM:   level (str) - Log level.
     # @PARAM:   message (str) - Log message.
-    # @PARAM:   context (Optional[Dict]) - Log context.
+    # @PARAM:   source (str) - Source component (default: "system").
-    def _add_log(self, task_id: str, level: str, message: str, context: Optional[Dict[str, Any]] = None):
+    # @PARAM:   metadata (Optional[Dict]) - Additional structured data.
+    # @PARAM:   context (Optional[Dict]) - Legacy context (for backward compatibility).
+    def _add_log(
+        self,
+        task_id: str,
+        level: str,
+        message: str,
+        source: str = "system",
+        metadata: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None
+    ):
         with belief_scope("TaskManager._add_log", f"task_id={task_id}"):
             task = self.tasks.get(task_id)
             if not task:
                 return
 
-            log_entry = LogEntry(level=level, message=message, context=context)
+            # Filter logs based on task_log_level configuration
-            task.logs.append(log_entry)
+            if not should_log_task_level(level):
-            self.persistence_service.persist_task(task)
+                return
 
-            # Notify subscribers
+            # Create log entry with new fields
+            log_entry = LogEntry(
+                level=level,
+                message=message,
+                source=source,
+                metadata=metadata,
+                context=context  # Keep for backward compatibility
+            )
+            
+            # Add to in-memory logs (for backward compatibility with legacy JSON field)
+            task.logs.append(log_entry)
+            
+            # Add to buffer for batch persistence
+            with self._log_buffer_lock:
+                if task_id not in self._log_buffer:
+                    self._log_buffer[task_id] = []
+                self._log_buffer[task_id].append(log_entry)
+
+            # Notify subscribers (for real-time WebSocket updates)
             if task_id in self.subscribers:
                 for queue in self.subscribers[task_id]:
                     self.loop.call_soon_threadsafe(queue.put_nowait, log_entry)
@@ -353,7 +522,7 @@ class TaskManager:
     # [/DEF:resume_task_with_password:Function]
 
     # [DEF:clear_tasks:Function]
-    # @PURPOSE: Clears tasks based on status filter.
+    # @PURPOSE: Clears tasks based on status filter (also deletes associated logs).
     # @PRE:     status is Optional[TaskStatus].
     # @POST:    Tasks matching filter (or all non-active) cleared from registry and database.
     # @PARAM:   status (Optional[TaskStatus]) - Filter by task status.
@@ -387,9 +556,13 @@ class TaskManager:
                 
                 del self.tasks[tid]
 
-            # Remove from persistence
+            # Remove from persistence (task_records and task_logs via CASCADE)
             self.persistence_service.delete_tasks(tasks_to_remove)
             
+            # Also explicitly delete logs (in case CASCADE is not set up)
+            if tasks_to_remove:
+                self.log_persistence_service.delete_logs_for_tasks(tasks_to_remove)
+            
             logger.info(f"Cleared {len(tasks_to_remove)} tasks.")
             return len(tasks_to_remove)
     # [/DEF:clear_tasks:Function]

backend/src/core/task_manager/models.py

@@ -1,4 +1,5 @@
 # [DEF:TaskManagerModels:Module]
+# @TIER: STANDARD
 # @SEMANTICS: task, models, pydantic, enum, state
 # @PURPOSE: Defines the data models and enumerations used by the Task Manager.
 # @LAYER: Core
@@ -16,6 +17,7 @@ from pydantic import BaseModel, Field
 # [/SECTION]
 
 # [DEF:TaskStatus:Enum]
+# @TIER: TRIVIAL
 # @SEMANTICS: task, status, state, enum
 # @PURPOSE: Defines the possible states a task can be in during its lifecycle.
 class TaskStatus(str, Enum):
@@ -27,17 +29,73 @@ class TaskStatus(str, Enum):
     AWAITING_INPUT = "AWAITING_INPUT"
 # [/DEF:TaskStatus:Enum]
 
+# [DEF:LogLevel:Enum]
+# @SEMANTICS: log, level, severity, enum
+# @PURPOSE: Defines the possible log levels for task logging.
+# @TIER: STANDARD
+class LogLevel(str, Enum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+# [/DEF:LogLevel:Enum]
+
 # [DEF:LogEntry:Class]
 # @SEMANTICS: log, entry, record, pydantic
 # @PURPOSE: A Pydantic model representing a single, structured log entry associated with a task.
+# @TIER: CRITICAL
+# @INVARIANT: Each log entry has a unique timestamp and source.
 class LogEntry(BaseModel):
     timestamp: datetime = Field(default_factory=datetime.utcnow)
-    level: str
+    level: str = Field(default="INFO")
     message: str
-    context: Optional[Dict[str, Any]] = None
+    source: str = Field(default="system")  # Component attribution: plugin, superset_api, git, etc.
+    context: Optional[Dict[str, Any]] = None  # Legacy field, kept for backward compatibility
+    metadata: Optional[Dict[str, Any]] = None  # Structured metadata (e.g., dashboard_id, progress)
 # [/DEF:LogEntry:Class]
 
+# [DEF:TaskLog:Class]
+# @SEMANTICS: task, log, persistent, pydantic
+# @PURPOSE: A Pydantic model representing a persisted log entry from the database.
+# @TIER: STANDARD
+# @RELATION: MAPS_TO -> TaskLogRecord
+class TaskLog(BaseModel):
+    id: int
+    task_id: str
+    timestamp: datetime
+    level: str
+    source: str
+    message: str
+    metadata: Optional[Dict[str, Any]] = None
+
+    class Config:
+        from_attributes = True
+# [/DEF:TaskLog:Class]
+
+# [DEF:LogFilter:Class]
+# @SEMANTICS: log, filter, query, pydantic
+# @PURPOSE: Filter parameters for querying task logs.
+# @TIER: STANDARD
+class LogFilter(BaseModel):
+    level: Optional[str] = None  # Filter by log level
+    source: Optional[str] = None  # Filter by source component
+    search: Optional[str] = None  # Text search in message
+    offset: int = Field(default=0, ge=0)
+    limit: int = Field(default=100, ge=1, le=1000)
+# [/DEF:LogFilter:Class]
+
+# [DEF:LogStats:Class]
+# @SEMANTICS: log, stats, aggregation, pydantic
+# @PURPOSE: Statistics about log entries for a task.
+# @TIER: STANDARD
+class LogStats(BaseModel):
+    total_count: int
+    by_level: Dict[str, int]  # {"INFO": 10, "ERROR": 2}
+    by_source: Dict[str, int]  # {"plugin": 5, "superset_api": 7}
+# [/DEF:LogStats:Class]
+
 # [DEF:Task:Class]
+# @TIER: STANDARD
 # @SEMANTICS: task, job, execution, state, pydantic
 # @PURPOSE: A Pydantic model representing a single execution instance of a plugin, including its status, parameters, and logs.
 class Task(BaseModel):

backend/src/core/task_manager/persistence.py

@@ -7,13 +7,13 @@
 
 # [SECTION: IMPORTS]
 from datetime import datetime
-from typing import List, Optional, Dict, Any
+from typing import List, Optional
 import json
 
 from sqlalchemy.orm import Session
-from ...models.task import TaskRecord
+from ...models.task import TaskRecord, TaskLogRecord
 from ..database import TasksSessionLocal
-from .models import Task, TaskStatus, LogEntry
+from .models import Task, TaskStatus, LogEntry, TaskLog, LogFilter, LogStats
 from ..logger import logger, belief_scope
 # [/SECTION]
 
@@ -36,6 +36,7 @@ class TaskPersistenceService:
     # @PRE:     isinstance(task, Task)
     # @POST:    Task record created or updated in database.
     # @PARAM:   task (Task) - The task object to persist.
+    # @SIDE_EFFECT: Writes to task_records table in tasks.db
     def persist_task(self, task: Task) -> None:
         with belief_scope("TaskPersistenceService.persist_task", f"task_id={task.id}"):
             session: Session = TasksSessionLocal()
@@ -50,8 +51,19 @@ class TaskPersistenceService:
                 record.environment_id = task.params.get("environment_id") or task.params.get("source_env_id")
                 record.started_at = task.started_at
                 record.finished_at = task.finished_at
-                record.params = task.params
+                
-                record.result = task.result
+                # Ensure params and result are JSON serializable
+                def json_serializable(obj):
+                    if isinstance(obj, dict):
+                        return {k: json_serializable(v) for k, v in obj.items()}
+                    elif isinstance(obj, list):
+                        return [json_serializable(v) for v in obj]
+                    elif isinstance(obj, datetime):
+                        return obj.isoformat()
+                    return obj
+
+                record.params = json_serializable(task.params)
+                record.result = json_serializable(task.result)
                 
                 # Store logs as JSON, converting datetime to string
                 record.logs = []
@@ -59,6 +71,9 @@ class TaskPersistenceService:
                     log_dict = log.dict()
                     if isinstance(log_dict.get('timestamp'), datetime):
                         log_dict['timestamp'] = log_dict['timestamp'].isoformat()
+                    # Also clean up any datetimes in context
+                    if log_dict.get('context'):
+                        log_dict['context'] = json_serializable(log_dict['context'])
                     record.logs.append(log_dict)
                 
                 # Extract error if failed
@@ -155,4 +170,215 @@ class TaskPersistenceService:
     # [/DEF:delete_tasks:Function]
 
 # [/DEF:TaskPersistenceService:Class]
+
+# [DEF:TaskLogPersistenceService:Class]
+# @SEMANTICS: persistence, service, database, log, sqlalchemy
+# @PURPOSE: Provides methods to save and query task logs from the task_logs table.
+# @TIER: CRITICAL
+# @RELATION: DEPENDS_ON -> TaskLogRecord
+# @INVARIANT: Log entries are batch-inserted for performance.
+class TaskLogPersistenceService:
+    """
+    Service for persisting and querying task logs.
+    Supports batch inserts, filtering, and statistics.
+    """
+    
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initialize the log persistence service.
+    # @POST: Service is ready.
+    def __init__(self):
+        pass
+    # [/DEF:__init__:Function]
+    
+    # [DEF:add_logs:Function]
+    # @PURPOSE: Batch insert log entries for a task.
+    # @PRE: logs is a list of LogEntry objects.
+    # @POST: All logs inserted into task_logs table.
+    # @PARAM: task_id (str) - The task ID.
+    # @PARAM: logs (List[LogEntry]) - Log entries to insert.
+    # @SIDE_EFFECT: Writes to task_logs table.
+    def add_logs(self, task_id: str, logs: List[LogEntry]) -> None:
+        if not logs:
+            return
+        with belief_scope("TaskLogPersistenceService.add_logs", f"task_id={task_id}"):
+            session: Session = TasksSessionLocal()
+            try:
+                for log in logs:
+                    record = TaskLogRecord(
+                        task_id=task_id,
+                        timestamp=log.timestamp,
+                        level=log.level,
+                        source=log.source or "system",
+                        message=log.message,
+                        metadata_json=json.dumps(log.metadata) if log.metadata else None
+                    )
+                    session.add(record)
+                session.commit()
+            except Exception as e:
+                session.rollback()
+                logger.error(f"Failed to add logs for task {task_id}: {e}")
+            finally:
+                session.close()
+    # [/DEF:add_logs:Function]
+    
+    # [DEF:get_logs:Function]
+    # @PURPOSE: Query logs for a task with filtering and pagination.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Returns list of TaskLog objects matching filters.
+    # @PARAM: task_id (str) - The task ID.
+    # @PARAM: log_filter (LogFilter) - Filter parameters.
+    # @RETURN: List[TaskLog] - Filtered log entries.
+    def get_logs(self, task_id: str, log_filter: LogFilter) -> List[TaskLog]:
+        with belief_scope("TaskLogPersistenceService.get_logs", f"task_id={task_id}"):
+            session: Session = TasksSessionLocal()
+            try:
+                query = session.query(TaskLogRecord).filter(TaskLogRecord.task_id == task_id)
+                
+                # Apply filters
+                if log_filter.level:
+                    query = query.filter(TaskLogRecord.level == log_filter.level.upper())
+                if log_filter.source:
+                    query = query.filter(TaskLogRecord.source == log_filter.source)
+                if log_filter.search:
+                    search_pattern = f"%{log_filter.search}%"
+                    query = query.filter(TaskLogRecord.message.ilike(search_pattern))
+                
+                # Order by timestamp ascending (oldest first)
+                query = query.order_by(TaskLogRecord.timestamp.asc())
+                
+                # Apply pagination
+                records = query.offset(log_filter.offset).limit(log_filter.limit).all()
+                
+                logs = []
+                for record in records:
+                    metadata = None
+                    if record.metadata_json:
+                        try:
+                            metadata = json.loads(record.metadata_json)
+                        except json.JSONDecodeError:
+                            metadata = None
+                    
+                    logs.append(TaskLog(
+                        id=record.id,
+                        task_id=record.task_id,
+                        timestamp=record.timestamp,
+                        level=record.level,
+                        source=record.source,
+                        message=record.message,
+                        metadata=metadata
+                    ))
+                
+                return logs
+            finally:
+                session.close()
+    # [/DEF:get_logs:Function]
+    
+    # [DEF:get_log_stats:Function]
+    # @PURPOSE: Get statistics about logs for a task.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Returns LogStats with counts by level and source.
+    # @PARAM: task_id (str) - The task ID.
+    # @RETURN: LogStats - Statistics about task logs.
+    def get_log_stats(self, task_id: str) -> LogStats:
+        with belief_scope("TaskLogPersistenceService.get_log_stats", f"task_id={task_id}"):
+            session: Session = TasksSessionLocal()
+            try:
+                # Get total count
+                total_count = session.query(TaskLogRecord).filter(
+                    TaskLogRecord.task_id == task_id
+                ).count()
+                
+                # Get counts by level
+                from sqlalchemy import func
+                level_counts = session.query(
+                    TaskLogRecord.level,
+                    func.count(TaskLogRecord.id)
+                ).filter(
+                    TaskLogRecord.task_id == task_id
+                ).group_by(TaskLogRecord.level).all()
+                
+                by_level = {level: count for level, count in level_counts}
+                
+                # Get counts by source
+                source_counts = session.query(
+                    TaskLogRecord.source,
+                    func.count(TaskLogRecord.id)
+                ).filter(
+                    TaskLogRecord.task_id == task_id
+                ).group_by(TaskLogRecord.source).all()
+                
+                by_source = {source: count for source, count in source_counts}
+                
+                return LogStats(
+                    total_count=total_count,
+                    by_level=by_level,
+                    by_source=by_source
+                )
+            finally:
+                session.close()
+    # [/DEF:get_log_stats:Function]
+    
+    # [DEF:get_sources:Function]
+    # @PURPOSE: Get unique sources for a task's logs.
+    # @PRE: task_id is a valid task ID.
+    # @POST: Returns list of unique source strings.
+    # @PARAM: task_id (str) - The task ID.
+    # @RETURN: List[str] - Unique source names.
+    def get_sources(self, task_id: str) -> List[str]:
+        with belief_scope("TaskLogPersistenceService.get_sources", f"task_id={task_id}"):
+            session: Session = TasksSessionLocal()
+            try:
+                from sqlalchemy import distinct
+                sources = session.query(distinct(TaskLogRecord.source)).filter(
+                    TaskLogRecord.task_id == task_id
+                ).all()
+                return [s[0] for s in sources]
+            finally:
+                session.close()
+    # [/DEF:get_sources:Function]
+    
+    # [DEF:delete_logs_for_task:Function]
+    # @PURPOSE: Delete all logs for a specific task.
+    # @PRE: task_id is a valid task ID.
+    # @POST: All logs for the task are deleted.
+    # @PARAM: task_id (str) - The task ID.
+    # @SIDE_EFFECT: Deletes from task_logs table.
+    def delete_logs_for_task(self, task_id: str) -> None:
+        with belief_scope("TaskLogPersistenceService.delete_logs_for_task", f"task_id={task_id}"):
+            session: Session = TasksSessionLocal()
+            try:
+                session.query(TaskLogRecord).filter(
+                    TaskLogRecord.task_id == task_id
+                ).delete(synchronize_session=False)
+                session.commit()
+            except Exception as e:
+                session.rollback()
+                logger.error(f"Failed to delete logs for task {task_id}: {e}")
+            finally:
+                session.close()
+    # [/DEF:delete_logs_for_task:Function]
+    
+    # [DEF:delete_logs_for_tasks:Function]
+    # @PURPOSE: Delete all logs for multiple tasks.
+    # @PRE: task_ids is a list of task IDs.
+    # @POST: All logs for the tasks are deleted.
+    # @PARAM: task_ids (List[str]) - List of task IDs.
+    def delete_logs_for_tasks(self, task_ids: List[str]) -> None:
+        if not task_ids:
+            return
+        with belief_scope("TaskLogPersistenceService.delete_logs_for_tasks"):
+            session: Session = TasksSessionLocal()
+            try:
+                session.query(TaskLogRecord).filter(
+                    TaskLogRecord.task_id.in_(task_ids)
+                ).delete(synchronize_session=False)
+                session.commit()
+            except Exception as e:
+                session.rollback()
+                logger.error(f"Failed to delete logs for tasks: {e}")
+            finally:
+                session.close()
+    # [/DEF:delete_logs_for_tasks:Function]
+
+# [/DEF:TaskLogPersistenceService:Class]
 # [/DEF:TaskPersistenceModule:Module]

backend/src/core/task_manager/task_logger.py

@@ -0,0 +1,167 @@
+# [DEF:TaskLoggerModule:Module]
+# @SEMANTICS: task, logger, context, plugin, attribution
+# @PURPOSE: Provides a dedicated logger for tasks with automatic source attribution.
+# @LAYER: Core
+# @RELATION: DEPENDS_ON -> TaskManager, CALLS -> TaskManager._add_log
+# @TIER: CRITICAL
+# @INVARIANT: Each TaskLogger instance is bound to a specific task_id and default source.
+
+# [SECTION: IMPORTS]
+from typing import Dict, Any, Optional, Callable
+# [/SECTION]
+
+# [DEF:TaskLogger:Class]
+# @SEMANTICS: logger, task, source, attribution
+# @PURPOSE: A wrapper around TaskManager._add_log that carries task_id and source context.
+# @TIER: CRITICAL
+# @INVARIANT: All log calls include the task_id and source.
+# @UX_STATE: Idle -> Logging -> (system records log)
+class TaskLogger:
+    """
+    A dedicated logger for tasks that automatically tags logs with source attribution.
+    
+    Usage:
+        logger = TaskLogger(task_id="abc123", add_log_fn=task_manager._add_log, source="plugin")
+        logger.info("Starting backup process")
+        logger.error("Failed to connect", metadata={"error_code": 500})
+        
+        # Create sub-logger with different source
+        api_logger = logger.with_source("superset_api")
+        api_logger.info("Fetching dashboards")
+    """
+    
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initialize the TaskLogger with task context.
+    # @PRE: add_log_fn is a callable that accepts (task_id, level, message, context, source, metadata).
+    # @POST: TaskLogger is ready to log messages.
+    # @PARAM: task_id (str) - The ID of the task.
+    # @PARAM: add_log_fn (Callable) - Function to add log to TaskManager.
+    # @PARAM: source (str) - Default source for logs (default: "plugin").
+    def __init__(
+        self, 
+        task_id: str, 
+        add_log_fn: Callable, 
+        source: str = "plugin"
+    ):
+        self._task_id = task_id
+        self._add_log = add_log_fn
+        self._default_source = source
+    # [/DEF:__init__:Function]
+    
+    # [DEF:with_source:Function]
+    # @PURPOSE: Create a sub-logger with a different default source.
+    # @PRE: source is a non-empty string.
+    # @POST: Returns new TaskLogger with the same task_id but different source.
+    # @PARAM: source (str) - New default source.
+    # @RETURN: TaskLogger - New logger instance.
+    def with_source(self, source: str) -> "TaskLogger":
+        """Create a sub-logger with a different source context."""
+        return TaskLogger(
+            task_id=self._task_id,
+            add_log_fn=self._add_log,
+            source=source
+        )
+    # [/DEF:with_source:Function]
+    
+    # [DEF:_log:Function]
+    # @PURPOSE: Internal method to log a message at a given level.
+    # @PRE: level is a valid log level string.
+    # @POST: Log entry added via add_log_fn.
+    # @PARAM: level (str) - Log level (DEBUG, INFO, WARNING, ERROR).
+    # @PARAM: message (str) - Log message.
+    # @PARAM: source (Optional[str]) - Override source for this log entry.
+    # @PARAM: metadata (Optional[Dict]) - Additional structured data.
+    def _log(
+        self, 
+        level: str, 
+        message: str, 
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Internal logging method."""
+        self._add_log(
+            task_id=self._task_id,
+            level=level,
+            message=message,
+            source=source or self._default_source,
+            metadata=metadata
+        )
+    # [/DEF:_log:Function]
+    
+    # [DEF:debug:Function]
+    # @PURPOSE: Log a DEBUG level message.
+    # @PARAM: message (str) - Log message.
+    # @PARAM: source (Optional[str]) - Override source.
+    # @PARAM: metadata (Optional[Dict]) - Additional data.
+    def debug(
+        self, 
+        message: str, 
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        self._log("DEBUG", message, source, metadata)
+    # [/DEF:debug:Function]
+    
+    # [DEF:info:Function]
+    # @PURPOSE: Log an INFO level message.
+    # @PARAM: message (str) - Log message.
+    # @PARAM: source (Optional[str]) - Override source.
+    # @PARAM: metadata (Optional[Dict]) - Additional data.
+    def info(
+        self, 
+        message: str, 
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        self._log("INFO", message, source, metadata)
+    # [/DEF:info:Function]
+    
+    # [DEF:warning:Function]
+    # @PURPOSE: Log a WARNING level message.
+    # @PARAM: message (str) - Log message.
+    # @PARAM: source (Optional[str]) - Override source.
+    # @PARAM: metadata (Optional[Dict]) - Additional data.
+    def warning(
+        self, 
+        message: str, 
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        self._log("WARNING", message, source, metadata)
+    # [/DEF:warning:Function]
+    
+    # [DEF:error:Function]
+    # @PURPOSE: Log an ERROR level message.
+    # @PARAM: message (str) - Log message.
+    # @PARAM: source (Optional[str]) - Override source.
+    # @PARAM: metadata (Optional[Dict]) - Additional data.
+    def error(
+        self, 
+        message: str, 
+        source: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        self._log("ERROR", message, source, metadata)
+    # [/DEF:error:Function]
+    
+    # [DEF:progress:Function]
+    # @PURPOSE: Log a progress update with percentage.
+    # @PRE: percent is between 0 and 100.
+    # @POST: Log entry with progress metadata added.
+    # @PARAM: message (str) - Progress message.
+    # @PARAM: percent (float) - Progress percentage (0-100).
+    # @PARAM: source (Optional[str]) - Override source.
+    def progress(
+        self, 
+        message: str, 
+        percent: float,
+        source: Optional[str] = None
+    ) -> None:
+        """Log a progress update with percentage."""
+        metadata = {"progress": min(100, max(0, percent))}
+        self._log("INFO", message, source, metadata)
+    # [/DEF:progress:Function]
+
+# [/DEF:TaskLogger:Class]
+
+# [/DEF:TaskLoggerModule:Module]

backend/src/core/utils/dataset_mapper.py

@@ -11,7 +11,7 @@
 # [SECTION: IMPORTS]
 import pandas as pd  # type: ignore
 import psycopg2  # type: ignore
-from typing import Dict, List, Optional, Any
+from typing import Dict, Optional, Any
 from ..logger import logger as app_logger, belief_scope
 # [/SECTION]
 

backend/src/core/utils/fileio.py

@@ -19,13 +19,14 @@ from datetime import date, datetime
 import shutil
 import zlib
 from dataclasses import dataclass
-import yaml
 from ..logger import logger as app_logger, belief_scope
 # [/SECTION]
 
 # [DEF:InvalidZipFormatError:Class]
+# @PURPOSE: Exception raised when a file is not a valid ZIP archive.
 class InvalidZipFormatError(Exception):
     pass
+# [/DEF:InvalidZipFormatError:Class]
 
 # [DEF:create_temp_file:Function]
 # @PURPOSE: Контекстный менеджер для создания временного файла или директории с гарантированным удалением.

backend/src/core/utils/matching.py

@@ -42,6 +42,8 @@ def suggest_mappings(source_databases: List[Dict], target_databases: List[Dict],
             name, score, index = match
             if score >= threshold:
                 suggestions.append({
+                    "source_db": s_db['database_name'],
+                    "target_db": target_databases[index]['database_name'],
                     "source_db_uuid": s_db['uuid'],
                     "target_db_uuid": target_databases[index]['uuid'],
                     "confidence": score / 100.0

backend/src/core/utils/network.py

@@ -20,31 +20,71 @@ from ..logger import logger as app_logger, belief_scope
 # [/SECTION]
 
 # [DEF:SupersetAPIError:Class]
+# @PURPOSE: Base exception for all Superset API related errors.
 class SupersetAPIError(Exception):
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the exception with a message and context.
+    # @PRE: message is a string, context is a dict.
+    # @POST: Exception is initialized with context.
     def __init__(self, message: str = "Superset API error", **context: Any):
-        self.context = context
+        with belief_scope("SupersetAPIError.__init__"):
-        super().__init__(f"[API_FAILURE] {message} | Context: {self.context}")
+            self.context = context
+            super().__init__(f"[API_FAILURE] {message} | Context: {self.context}")
+    # [/DEF:__init__:Function]
+# [/DEF:SupersetAPIError:Class]
 
 # [DEF:AuthenticationError:Class]
+# @PURPOSE: Exception raised when authentication fails.
 class AuthenticationError(SupersetAPIError):
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the authentication error.
+    # @PRE: message is a string, context is a dict.
+    # @POST: AuthenticationError is initialized.
     def __init__(self, message: str = "Authentication failed", **context: Any):
-        super().__init__(message, type="authentication", **context)
+        with belief_scope("AuthenticationError.__init__"):
+            super().__init__(message, type="authentication", **context)
+    # [/DEF:__init__:Function]
+# [/DEF:AuthenticationError:Class]
 
 # [DEF:PermissionDeniedError:Class]
+# @PURPOSE: Exception raised when access is denied.
 class PermissionDeniedError(AuthenticationError):
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the permission denied error.
+    # @PRE: message is a string, context is a dict.
+    # @POST: PermissionDeniedError is initialized.
     def __init__(self, message: str = "Permission denied", **context: Any):
-        super().__init__(message, **context)
+        with belief_scope("PermissionDeniedError.__init__"):
+            super().__init__(message, **context)
+    # [/DEF:__init__:Function]
+# [/DEF:PermissionDeniedError:Class]
 
 # [DEF:DashboardNotFoundError:Class]
+# @PURPOSE: Exception raised when a dashboard cannot be found.
 class DashboardNotFoundError(SupersetAPIError):
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the not found error with resource ID.
+    # @PRE: resource_id is provided.
+    # @POST: DashboardNotFoundError is initialized.
     def __init__(self, resource_id: Union[int, str], message: str = "Dashboard not found", **context: Any):
-        super().__init__(f"Dashboard '{resource_id}' {message}", subtype="not_found", resource_id=resource_id, **context)
+        with belief_scope("DashboardNotFoundError.__init__"):
+            super().__init__(f"Dashboard '{resource_id}' {message}", subtype="not_found", resource_id=resource_id, **context)
+    # [/DEF:__init__:Function]
+# [/DEF:DashboardNotFoundError:Class]
 
 # [DEF:NetworkError:Class]
+# @PURPOSE: Exception raised when a network level error occurs.
 class NetworkError(Exception):
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the network error.
+    # @PRE: message is a string.
+    # @POST: NetworkError is initialized.
     def __init__(self, message: str = "Network connection failed", **context: Any):
-        self.context = context
+        with belief_scope("NetworkError.__init__"):
-        super().__init__(f"[NETWORK_FAILURE] {message} | Context: {self.context}")
+            self.context = context
+            super().__init__(f"[NETWORK_FAILURE] {message} | Context: {self.context}")
+    # [/DEF:__init__:Function]
+# [/DEF:NetworkError:Class]
 
 # [DEF:APIClient:Class]
 # @PURPOSE: Инкапсулирует HTTP-логику для работы с API, включая сессии, аутентификацию, и обработку запросов.
@@ -78,14 +118,41 @@ class APIClient:
     def _init_session(self) -> requests.Session:
         with belief_scope("_init_session"):
             session = requests.Session()
+        
+        # Create a custom adapter that handles TLS issues
+        class TLSAdapter(HTTPAdapter):
+            def init_poolmanager(self, connections, maxsize, block=False):
+                from urllib3.poolmanager import PoolManager
+                import ssl
+                
+                # Create an SSL context that ignores TLSv1 unrecognized name errors
+                ctx = ssl.create_default_context()
+                ctx.set_ciphers('HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!SRP:!CAMELLIA')
+                
+                # Ignore TLSV1_UNRECOGNIZED_NAME errors by disabling hostname verification
+                # This is safe when verify_ssl is false (we're already not verifying the certificate)
+                ctx.check_hostname = False
+                
+                self.poolmanager = PoolManager(
+                    num_pools=connections,
+                    maxsize=maxsize,
+                    block=block,
+                    ssl_context=ctx
+                )
+        
         retries = Retry(total=3, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504])
-        adapter = HTTPAdapter(max_retries=retries)
+        adapter = TLSAdapter(max_retries=retries)
         session.mount('http://', adapter)
         session.mount('https://', adapter)
+        
         if not self.request_settings["verify_ssl"]:
             urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
             app_logger.warning("[_init_session][State] SSL verification disabled.")
-        session.verify = self.request_settings["verify_ssl"]
+            # When verify_ssl is false, we should also disable hostname verification
+            session.verify = False
+        else:
+            session.verify = True
+        
         return session
     # [/DEF:_init_session:Function]
 
@@ -100,7 +167,16 @@ class APIClient:
             app_logger.info("[authenticate][Enter] Authenticating to %s", self.base_url)
             try:
                 login_url = f"{self.base_url}/security/login"
+                # Log the payload keys and values (masking password)
+                masked_auth = {k: ("******" if k == "password" else v) for k, v in self.auth.items()}
+                app_logger.info(f"[authenticate][Debug] Login URL: {login_url}")
+                app_logger.info(f"[authenticate][Debug] Auth payload: {masked_auth}")
+                
                 response = self.session.post(login_url, json=self.auth, timeout=self.request_settings["timeout"])
+                
+                if response.status_code != 200:
+                    app_logger.error(f"[authenticate][Error] Status: {response.status_code}, Response: {response.text}")
+                
                 response.raise_for_status()
                 access_token = response.json()["access_token"]
                 
@@ -113,6 +189,9 @@ class APIClient:
                 app_logger.info("[authenticate][Exit] Authenticated successfully.")
                 return self._tokens
             except requests.exceptions.HTTPError as e:
+                status_code = e.response.status_code if e.response is not None else None
+                if status_code in [502, 503, 504]:
+                    raise NetworkError(f"Environment unavailable during authentication (Status {status_code})", status_code=status_code) from e
                 raise AuthenticationError(f"Authentication failed: {e}") from e
             except (requests.exceptions.RequestException, KeyError) as e:
                 raise NetworkError(f"Network or parsing error during authentication: {e}") from e
@@ -125,7 +204,8 @@ class APIClient:
     # @POST: Returns headers including auth tokens.
     def headers(self) -> Dict[str, str]:
         with belief_scope("headers"):
-            if not self._authenticated: self.authenticate()
+            if not self._authenticated:
+                self.authenticate()
             return {
             "Authorization": f"Bearer {self._tokens['access_token']}",
             "X-CSRFToken": self._tokens.get("csrf_token", ""),
@@ -148,7 +228,8 @@ class APIClient:
         with belief_scope("request"):
             full_url = f"{self.base_url}{endpoint}"
         _headers = self.headers.copy()
-        if headers: _headers.update(headers)
+        if headers:
+            _headers.update(headers)
         
         try:
             response = self.session.request(method, full_url, headers=_headers, **kwargs)
@@ -169,9 +250,14 @@ class APIClient:
     def _handle_http_error(self, e: requests.exceptions.HTTPError, endpoint: str):
         with belief_scope("_handle_http_error"):
             status_code = e.response.status_code
-        if status_code == 404: raise DashboardNotFoundError(endpoint) from e
+        if status_code == 502 or status_code == 503 or status_code == 504:
-        if status_code == 403: raise PermissionDeniedError() from e
+            raise NetworkError(f"Environment unavailable (Status {status_code})", status_code=status_code) from e
-        if status_code == 401: raise AuthenticationError() from e
+        if status_code == 404:
+            raise DashboardNotFoundError(endpoint) from e
+        if status_code == 403:
+            raise PermissionDeniedError() from e
+        if status_code == 401:
+            raise AuthenticationError() from e
         raise SupersetAPIError(f"API Error {status_code}: {e.response.text}") from e
     # [/DEF:_handle_http_error:Function]
 
@@ -183,9 +269,12 @@ class APIClient:
     # @POST: Raises a NetworkError.
     def _handle_network_error(self, e: requests.exceptions.RequestException, url: str):
         with belief_scope("_handle_network_error"):
-            if isinstance(e, requests.exceptions.Timeout): msg = "Request timeout"
+            if isinstance(e, requests.exceptions.Timeout):
-            elif isinstance(e, requests.exceptions.ConnectionError): msg = "Connection error"
+                msg = "Request timeout"
-            else: msg = f"Unknown network error: {e}"
+            elif isinstance(e, requests.exceptions.ConnectionError):
+                msg = "Connection error"
+            else:
+                msg = f"Unknown network error: {e}"
             raise NetworkError(msg, url=url) from e
     # [/DEF:_handle_network_error:Function]
 
@@ -202,7 +291,9 @@ class APIClient:
     def upload_file(self, endpoint: str, file_info: Dict[str, Any], extra_data: Optional[Dict] = None, timeout: Optional[int] = None) -> Dict:
         with belief_scope("upload_file"):
             full_url = f"{self.base_url}{endpoint}"
-        _headers = self.headers.copy(); _headers.pop('Content-Type', None)
+            _headers = self.headers.copy()
+            _headers.pop('Content-Type', None)
+        
         
         file_obj, file_name, form_field = file_info.get("file_obj"), file_info.get("file_name"), file_info.get("form_field", "file")
         
@@ -264,20 +355,40 @@ class APIClient:
     # @PURPOSE: Автоматически собирает данные со всех страниц пагинированного эндпоинта.
     # @PARAM: endpoint (str) - Эндпоинт.
     # @PARAM: pagination_options (Dict[str, Any]) - Опции пагинации.
-    # @PRE: pagination_options must contain 'base_query', 'total_count', 'results_field'.
+    # @PRE: pagination_options must contain 'base_query', 'results_field'. 'total_count' is optional.
     # @POST: Returns all items across all pages.
     # @RETURN: List[Any] - Список данных.
     def fetch_paginated_data(self, endpoint: str, pagination_options: Dict[str, Any]) -> List[Any]:
         with belief_scope("fetch_paginated_data"):
-            base_query, total_count = pagination_options["base_query"], pagination_options["total_count"]
+            base_query = pagination_options["base_query"]
-        results_field, page_size = pagination_options["results_field"], base_query.get('page_size')
+            total_count = pagination_options.get("total_count")
-        assert page_size and page_size > 0, "'page_size' must be a positive number."
+        
+        results_field = pagination_options["results_field"]
+        count_field = pagination_options.get("count_field", "count")
+        page_size = base_query.get('page_size', 1000)
+        assert page_size > 0, "'page_size' must be a positive number."
         
         results = []
-        for page in range((total_count + page_size - 1) // page_size):
+        page = 0
+        
+        # Fetch first page to get data and total count if not provided
+        query = {**base_query, 'page': page}
+        response_json = cast(Dict[str, Any], self.request("GET", endpoint, params={"q": json.dumps(query)}))
+        
+        first_page_results = response_json.get(results_field, [])
+        results.extend(first_page_results)
+        
+        if total_count is None:
+            total_count = response_json.get(count_field, len(first_page_results))
+            app_logger.debug(f"[fetch_paginated_data][State] Total count resolved from first page: {total_count}")
+
+        # Fetch remaining pages
+        total_pages = (total_count + page_size - 1) // page_size
+        for page in range(1, total_pages):
             query = {**base_query, 'page': page}
             response_json = cast(Dict[str, Any], self.request("GET", endpoint, params={"q": json.dumps(query)}))
             results.extend(response_json.get(results_field, []))
+            
         return results
     # [/DEF:fetch_paginated_data:Function]
 

backend/src/dependencies.py

@@ -1,16 +1,24 @@
 # [DEF:Dependencies:Module]
-# @SEMANTICS: dependency, injection, singleton, factory
+# @SEMANTICS: dependency, injection, singleton, factory, auth, jwt
-# @PURPOSE: Manages the creation and provision of shared application dependencies, such as the PluginLoader and TaskManager, to avoid circular imports.
+# @PURPOSE: Manages creation and provision of shared application dependencies, such as PluginLoader and TaskManager, to avoid circular imports.
 # @LAYER: Core
-# @RELATION: Used by the main app and API routers to get access to shared instances.
+# @RELATION: Used by main app and API routers to get access to shared instances.
 
 from pathlib import Path
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError
 from .core.plugin_loader import PluginLoader
 from .core.task_manager import TaskManager
 from .core.config_manager import ConfigManager
 from .core.scheduler import SchedulerService
-from .core.database import init_db
+from .services.resource_service import ResourceService
-from .core.logger import logger, belief_scope
+from .services.mapping_service import MappingService
+from .core.database import init_db, get_auth_db
+from .core.logger import logger
+from .core.auth.jwt import decode_token
+from .core.auth.repository import AuthRepository
+from .models.auth import User
 
 # Initialize singletons
 # Use absolute path relative to this file to ensure plugins are found regardless of CWD
@@ -22,14 +30,13 @@ config_manager = ConfigManager(config_path=str(config_path))
 init_db()
 
 # [DEF:get_config_manager:Function]
-# @PURPOSE: Dependency injector for the ConfigManager.
+# @PURPOSE: Dependency injector for ConfigManager.
 # @PRE: Global config_manager must be initialized.
 # @POST: Returns shared ConfigManager instance.
 # @RETURN: ConfigManager - The shared config manager instance.
 def get_config_manager() -> ConfigManager:
-    """Dependency injector for the ConfigManager."""
+    """Dependency injector for ConfigManager."""
-    with belief_scope("get_config_manager"):
+    return config_manager
-        return config_manager
 # [/DEF:get_config_manager:Function]
 
 plugin_dir = Path(__file__).parent / "plugins"
@@ -44,37 +51,121 @@ logger.info("TaskManager initialized")
 scheduler_service = SchedulerService(task_manager, config_manager)
 logger.info("SchedulerService initialized")
 
+resource_service = ResourceService()
+logger.info("ResourceService initialized")
+
 # [DEF:get_plugin_loader:Function]
-# @PURPOSE: Dependency injector for the PluginLoader.
+# @PURPOSE: Dependency injector for PluginLoader.
 # @PRE: Global plugin_loader must be initialized.
 # @POST: Returns shared PluginLoader instance.
 # @RETURN: PluginLoader - The shared plugin loader instance.
 def get_plugin_loader() -> PluginLoader:
-    """Dependency injector for the PluginLoader."""
+    """Dependency injector for PluginLoader."""
-    with belief_scope("get_plugin_loader"):
+    return plugin_loader
-        return plugin_loader
 # [/DEF:get_plugin_loader:Function]
 
 # [DEF:get_task_manager:Function]
-# @PURPOSE: Dependency injector for the TaskManager.
+# @PURPOSE: Dependency injector for TaskManager.
 # @PRE: Global task_manager must be initialized.
 # @POST: Returns shared TaskManager instance.
 # @RETURN: TaskManager - The shared task manager instance.
 def get_task_manager() -> TaskManager:
-    """Dependency injector for the TaskManager."""
+    """Dependency injector for TaskManager."""
-    with belief_scope("get_task_manager"):
+    return task_manager
-        return task_manager
 # [/DEF:get_task_manager:Function]
 
 # [DEF:get_scheduler_service:Function]
-# @PURPOSE: Dependency injector for the SchedulerService.
+# @PURPOSE: Dependency injector for SchedulerService.
 # @PRE: Global scheduler_service must be initialized.
 # @POST: Returns shared SchedulerService instance.
 # @RETURN: SchedulerService - The shared scheduler service instance.
 def get_scheduler_service() -> SchedulerService:
-    """Dependency injector for the SchedulerService."""
+    """Dependency injector for SchedulerService."""
-    with belief_scope("get_scheduler_service"):
+    return scheduler_service
-        return scheduler_service
 # [/DEF:get_scheduler_service:Function]
 
+# [DEF:get_resource_service:Function]
+# @PURPOSE: Dependency injector for ResourceService.
+# @PRE: Global resource_service must be initialized.
+# @POST: Returns shared ResourceService instance.
+# @RETURN: ResourceService - The shared resource service instance.
+def get_resource_service() -> ResourceService:
+    """Dependency injector for ResourceService."""
+    return resource_service
+# [/DEF:get_resource_service:Function]
+
+# [DEF:get_mapping_service:Function]
+# @PURPOSE: Dependency injector for MappingService.
+# @PRE: Global config_manager must be initialized.
+# @POST: Returns new MappingService instance.
+# @RETURN: MappingService - A new mapping service instance.
+def get_mapping_service() -> MappingService:
+    """Dependency injector for MappingService."""
+    return MappingService(config_manager)
+# [/DEF:get_mapping_service:Function]
+
+# [DEF:oauth2_scheme:Variable]
+# @PURPOSE: OAuth2 password bearer scheme for token extraction.
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+# [/DEF:oauth2_scheme:Variable]
+
+# [DEF:get_current_user:Function]
+# @PURPOSE: Dependency for retrieving currently authenticated user from a JWT.
+# @PRE:     JWT token provided in Authorization header.
+# @POST:    Returns User object if token is valid.
+# @THROW:   HTTPException 401 if token is invalid or user not found.
+# @PARAM:   token (str) - Extracted JWT token.
+# @PARAM:   db (Session) - Auth database session.
+# @RETURN:  User - The authenticated user.
+def get_current_user(token: str = Depends(oauth2_scheme), db = Depends(get_auth_db)):
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = decode_token(token)
+        username: str = payload.get("sub")
+        if username is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+        
+    repo = AuthRepository(db)
+    user = repo.get_user_by_username(username)
+    if user is None:
+        raise credentials_exception
+    return user
+# [/DEF:get_current_user:Function]
+
+# [DEF:has_permission:Function]
+# @PURPOSE: Dependency for checking if the current user has a specific permission.
+# @PRE:     User is authenticated.
+# @POST:    Returns True if user has permission.
+# @THROW:   HTTPException 403 if permission is denied.
+# @PARAM:   resource (str) - The resource identifier.
+# @PARAM:   action (str) - The action identifier (READ, EXECUTE, WRITE).
+# @RETURN:  User - The authenticated user if permission granted.
+def has_permission(resource: str, action: str):
+    def permission_checker(current_user: User = Depends(get_current_user)):
+        # Union of all permissions across all roles
+        for role in current_user.roles:
+            for perm in role.permissions:
+                if perm.resource == resource and perm.action == action:
+                    return current_user
+        
+        # Special case for Admin role (full access)
+        if any(role.name == "Admin" for role in current_user.roles):
+            return current_user
+        
+        from .core.auth.logger import log_security_event
+        log_security_event("PERMISSION_DENIED", current_user.username, {"resource": resource, "action": action})
+            
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Permission denied for {resource}:{action}"
+        )
+    return permission_checker
+# [/DEF:has_permission:Function]
+
 # [/DEF:Dependencies:Module]

backend/src/models/__tests__/test_models.py

@@ -0,0 +1,36 @@
+# [DEF:test_models:Module]
+# @TIER: TRIVIAL
+# @PURPOSE: Unit tests for data models
+# @LAYER: Domain
+# @RELATION: VERIFIES -> src.models
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent.parent.parent.parent / "src"))
+
+from src.core.config_models import Environment
+from src.core.logger import belief_scope
+
+
+# [DEF:test_environment_model:Function]
+# @PURPOSE: Tests that Environment model correctly stores values.
+# @PRE: Environment class is available.
+# @POST: Values are verified.
+def test_environment_model():
+    with belief_scope("test_environment_model"):
+        env = Environment(
+            id="test-id",
+            name="test-env",
+            url="http://localhost:8088/api/v1",
+            username="admin",
+            password="password"
+        )
+        assert env.id == "test-id"
+        assert env.name == "test-env"
+        assert env.url == "http://localhost:8088/api/v1"
+# [/DEF:test_environment_model:Function]
+
+
+# [/DEF:test_models:Module]

backend/src/models/auth.py

@@ -0,0 +1,105 @@
+# [DEF:backend.src.models.auth:Module]
+#
+# @TIER:      STANDARD
+# @SEMANTICS: auth, models, user, role, permission, sqlalchemy
+# @PURPOSE:   SQLAlchemy models for multi-user authentication and authorization.
+# @LAYER:     Domain
+# @RELATION:  INHERITS_FROM -> backend.src.models.mapping.Base
+#
+# @INVARIANT: Usernames and emails must be unique.
+
+# [SECTION: IMPORTS]
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey, Table
+from sqlalchemy.orm import relationship
+from .mapping import Base
+# [/SECTION]
+
+# [DEF:generate_uuid:Function]
+# @PURPOSE: Generates a unique UUID string.
+# @POST:    Returns a string representation of a new UUID.
+def generate_uuid():
+    return str(uuid.uuid4())
+# [/DEF:generate_uuid:Function]
+
+# [DEF:user_roles:Table]
+# @PURPOSE: Association table for many-to-many relationship between Users and Roles.
+user_roles = Table(
+    "user_roles",
+    Base.metadata,
+    Column("user_id", String, ForeignKey("users.id"), primary_key=True),
+    Column("role_id", String, ForeignKey("roles.id"), primary_key=True),
+)
+# [/DEF:user_roles:Table]
+
+# [DEF:role_permissions:Table]
+# @PURPOSE: Association table for many-to-many relationship between Roles and Permissions.
+role_permissions = Table(
+    "role_permissions",
+    Base.metadata,
+    Column("role_id", String, ForeignKey("roles.id"), primary_key=True),
+    Column("permission_id", String, ForeignKey("permissions.id"), primary_key=True),
+)
+# [/DEF:role_permissions:Table]
+
+# [DEF:User:Class]
+# @PURPOSE: Represents an identity that can authenticate to the system.
+# @RELATION: HAS_MANY -> Role (via user_roles)
+class User(Base):
+    __tablename__ = "users"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    username = Column(String, unique=True, index=True, nullable=False)
+    email = Column(String, unique=True, index=True, nullable=True)
+    password_hash = Column(String, nullable=True)
+    auth_source = Column(String, default="LOCAL") # LOCAL or ADFS
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    last_login = Column(DateTime, nullable=True)
+    
+    roles = relationship("Role", secondary=user_roles, back_populates="users")
+# [/DEF:User:Class]
+
+# [DEF:Role:Class]
+# @PURPOSE: Represents a collection of permissions.
+# @RELATION: HAS_MANY -> User (via user_roles)
+# @RELATION: HAS_MANY -> Permission (via role_permissions)
+class Role(Base):
+    __tablename__ = "roles"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    name = Column(String, unique=True, index=True, nullable=False)
+    description = Column(String, nullable=True)
+    
+    users = relationship("User", secondary=user_roles, back_populates="roles")
+    permissions = relationship("Permission", secondary=role_permissions, back_populates="roles")
+# [/DEF:Role:Class]
+
+# [DEF:Permission:Class]
+# @PURPOSE: Represents a specific capability within the system.
+# @RELATION: HAS_MANY -> Role (via role_permissions)
+class Permission(Base):
+    __tablename__ = "permissions"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    resource = Column(String, nullable=False) # e.g. "plugin:backup"
+    action = Column(String, nullable=False)   # e.g. "READ", "EXECUTE", "WRITE"
+    
+    roles = relationship("Role", secondary=role_permissions, back_populates="permissions")
+# [/DEF:Permission:Class]
+
+# [DEF:ADGroupMapping:Class]
+# @PURPOSE: Maps an Active Directory group to a local System Role.
+# @RELATION: DEPENDS_ON -> Role
+class ADGroupMapping(Base):
+    __tablename__ = "ad_group_mappings"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    ad_group = Column(String, unique=True, index=True, nullable=False)
+    role_id = Column(String, ForeignKey("roles.id"), nullable=False)
+    
+    role = relationship("Role")
+# [/DEF:ADGroupMapping:Class]
+
+# [/DEF:backend.src.models.auth:Module]

backend/src/models/connection.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.models.connection:Module]
 #
+# @TIER: TRIVIAL
 # @SEMANTICS: database, connection, configuration, sqlalchemy, sqlite
 # @PURPOSE:   Defines the database schema for external database connection configurations.
 # @LAYER:     Domain
@@ -15,6 +16,7 @@ import uuid
 # [/SECTION]
 
 # [DEF:ConnectionConfig:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Stores credentials for external databases used for column mapping.
 class ConnectionConfig(Base):
     __tablename__ = "connection_configs"

backend/src/models/dashboard.py

@@ -1,4 +1,5 @@
 # [DEF:backend.src.models.dashboard:Module]
+# @TIER:      STANDARD
 # @SEMANTICS: dashboard, model, metadata, migration
 # @PURPOSE:   Defines data models for dashboard metadata and selection.
 # @LAYER:     Model
@@ -8,6 +9,7 @@ from pydantic import BaseModel
 from typing import List
 
 # [DEF:DashboardMetadata:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents a dashboard available for migration.
 class DashboardMetadata(BaseModel):
     id: int
@@ -17,6 +19,7 @@ class DashboardMetadata(BaseModel):
 # [/DEF:DashboardMetadata:Class]
 
 # [DEF:DashboardSelection:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents the user's selection of dashboards to migrate.
 class DashboardSelection(BaseModel):
     selected_ids: List[int]

backend/src/models/git.py

@@ -0,0 +1,73 @@
+# [DEF:GitModels:Module]
+# @TIER: TRIVIAL
+# @SEMANTICS: git, models, sqlalchemy, database, schema
+# @PURPOSE: Git-specific SQLAlchemy models for configuration and repository tracking.
+# @LAYER: Model
+# @RELATION: specs/011-git-integration-dashboard/data-model.md
+
+import enum
+from datetime import datetime
+from sqlalchemy import Column, String, Integer, DateTime, Enum, ForeignKey, Boolean
+import uuid
+from src.core.database import Base
+
+class GitProvider(str, enum.Enum):
+    GITHUB = "GITHUB"
+    GITLAB = "GITLAB"
+    GITEA = "GITEA"
+
+class GitStatus(str, enum.Enum):
+    CONNECTED = "CONNECTED"
+    FAILED = "FAILED"
+    UNKNOWN = "UNKNOWN"
+
+class SyncStatus(str, enum.Enum):
+    CLEAN = "CLEAN"
+    DIRTY = "DIRTY"
+    CONFLICT = "CONFLICT"
+
+# [DEF:GitServerConfig:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Configuration for a Git server connection.
+class GitServerConfig(Base):
+    __tablename__ = "git_server_configs"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String(255), nullable=False)
+    provider = Column(Enum(GitProvider), nullable=False)
+    url = Column(String(255), nullable=False)
+    pat = Column(String(255), nullable=False)  # PERSONAL ACCESS TOKEN
+    default_repository = Column(String(255), nullable=True)
+    status = Column(Enum(GitStatus), default=GitStatus.UNKNOWN)
+    last_validated = Column(DateTime, default=datetime.utcnow)
+# [/DEF:GitServerConfig:Class]
+
+# [DEF:GitRepository:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Tracking for a local Git repository linked to a dashboard.
+class GitRepository(Base):
+    __tablename__ = "git_repositories"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    dashboard_id = Column(Integer, nullable=False, unique=True)
+    config_id = Column(String(36), ForeignKey("git_server_configs.id"), nullable=False)
+    remote_url = Column(String(255), nullable=False)
+    local_path = Column(String(255), nullable=False)
+    current_branch = Column(String(255), default="main")
+    sync_status = Column(Enum(SyncStatus), default=SyncStatus.CLEAN)
+# [/DEF:GitRepository:Class]
+
+# [DEF:DeploymentEnvironment:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Target Superset environments for dashboard deployment.
+class DeploymentEnvironment(Base):
+    __tablename__ = "deployment_environments"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    name = Column(String(255), nullable=False)
+    superset_url = Column(String(255), nullable=False)
+    superset_token = Column(String(255), nullable=False)
+    is_active = Column(Boolean, default=True)
+# [/DEF:DeploymentEnvironment:Class]
+
+# [/DEF:GitModels:Module]

backend/src/models/llm.py

@@ -0,0 +1,46 @@
+# [DEF:backend.src.models.llm:Module]
+# @TIER: STANDARD
+# @SEMANTICS: llm, models, sqlalchemy, persistence
+# @PURPOSE: SQLAlchemy models for LLM provider configuration and validation results.
+# @LAYER: Domain
+# @RELATION: INHERITS_FROM -> backend.src.models.mapping.Base
+
+from sqlalchemy import Column, String, Boolean, DateTime, JSON, Text
+from datetime import datetime
+import uuid
+from .mapping import Base
+
+def generate_uuid():
+    return str(uuid.uuid4())
+
+# [DEF:LLMProvider:Class]
+# @PURPOSE: SQLAlchemy model for LLM provider configuration.
+class LLMProvider(Base):
+    __tablename__ = "llm_providers"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    provider_type = Column(String, nullable=False) # openai, openrouter, kilo
+    name = Column(String, nullable=False)
+    base_url = Column(String, nullable=False)
+    api_key = Column(String, nullable=False) # Should be encrypted
+    default_model = Column(String, nullable=False)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+# [/DEF:LLMProvider:Class]
+
+# [DEF:ValidationRecord:Class]
+# @PURPOSE: SQLAlchemy model for dashboard validation history.
+class ValidationRecord(Base):
+    __tablename__ = "llm_validation_results"
+    
+    id = Column(String, primary_key=True, default=generate_uuid)
+    dashboard_id = Column(String, nullable=False, index=True)
+    timestamp = Column(DateTime, default=datetime.utcnow)
+    status = Column(String, nullable=False) # PASS, WARN, FAIL
+    screenshot_path = Column(String, nullable=True)
+    issues = Column(JSON, nullable=False)
+    summary = Column(Text, nullable=False)
+    raw_response = Column(Text, nullable=True)
+# [/DEF:ValidationRecord:Class]
+
+# [/DEF:backend.src.models.llm:Module]

backend/src/models/mapping.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.models.mapping:Module]
 #
+# @TIER:      STANDARD
 # @SEMANTICS: database, mapping, environment, migration, sqlalchemy, sqlite
 # @PURPOSE:   Defines the database schema for environment metadata and database mappings using SQLAlchemy.
 # @LAYER:     Domain
@@ -19,6 +20,7 @@ import enum
 Base = declarative_base()
 
 # [DEF:MigrationStatus:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Enumeration of possible migration job statuses.
 class MigrationStatus(enum.Enum):
     PENDING = "PENDING"
@@ -29,6 +31,7 @@ class MigrationStatus(enum.Enum):
 # [/DEF:MigrationStatus:Class]
 
 # [DEF:Environment:Class]
+# @TIER: STANDARD
 # @PURPOSE: Represents a Superset instance environment.
 class Environment(Base):
     __tablename__ = "environments"
@@ -40,6 +43,7 @@ class Environment(Base):
 # [/DEF:Environment:Class]
 
 # [DEF:DatabaseMapping:Class]
+# @TIER: STANDARD
 # @PURPOSE: Represents a mapping between source and target databases.
 class DatabaseMapping(Base):
     __tablename__ = "database_mappings"
@@ -55,6 +59,7 @@ class DatabaseMapping(Base):
 # [/DEF:DatabaseMapping:Class]
 
 # [DEF:MigrationJob:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents a single migration execution job.
 class MigrationJob(Base):
     __tablename__ = "migration_jobs"

backend/src/models/storage.py

@@ -0,0 +1,42 @@
+# [DEF:backend.src.models.storage:Module]
+# @TIER: TRIVIAL
+# @SEMANTICS: storage, file, model, pydantic
+# @PURPOSE: Data models for the storage system.
+# @LAYER: Domain
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+# [DEF:FileCategory:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Enumeration of supported file categories in the storage system.
+class FileCategory(str, Enum):
+    BACKUP = "backups"
+    REPOSITORY = "repositorys"
+# [/DEF:FileCategory:Class]
+
+# [DEF:StorageConfig:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Configuration model for the storage system, defining paths and naming patterns.
+class StorageConfig(BaseModel):
+    root_path: str = Field(default="backups", description="Absolute path to the storage root directory.")
+    backup_structure_pattern: str = Field(default="{category}/", description="Pattern for backup directory structure.")
+    repo_structure_pattern: str = Field(default="{category}/", description="Pattern for repository directory structure.")
+    filename_pattern: str = Field(default="{name}_{timestamp}", description="Pattern for filenames.")
+# [/DEF:StorageConfig:Class]
+
+# [DEF:StoredFile:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Data model representing metadata for a file stored in the system.
+class StoredFile(BaseModel):
+    name: str = Field(..., description="Name of the file (including extension).")
+    path: str = Field(..., description="Relative path from storage root.")
+    size: int = Field(..., ge=0, description="Size of the file in bytes.")
+    created_at: datetime = Field(..., description="Creation timestamp.")
+    category: FileCategory = Field(..., description="Category of the file.")
+    mime_type: Optional[str] = Field(None, description="MIME type of the file.")
+# [/DEF:StoredFile:Class]
+
+# [/DEF:backend.src.models.storage:Module]

backend/src/models/task.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.models.task:Module]
 #
+# @TIER: TRIVIAL
 # @SEMANTICS: database, task, record, sqlalchemy, sqlite
 # @PURPOSE:   Defines the database schema for task execution records.
 # @LAYER:     Domain
@@ -8,13 +9,14 @@
 # @INVARIANT: All primary keys are UUID strings.
 
 # [SECTION: IMPORTS]
-from sqlalchemy import Column, String, DateTime, JSON, ForeignKey
+from sqlalchemy import Column, String, DateTime, JSON, ForeignKey, Text, Integer, Index
 from sqlalchemy.sql import func
 from .mapping import Base
 import uuid
 # [/SECTION]
 
 # [DEF:TaskRecord:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents a persistent record of a task execution.
 class TaskRecord(Base):
     __tablename__ = "task_records"
@@ -25,11 +27,35 @@ class TaskRecord(Base):
     environment_id = Column(String, ForeignKey("environments.id"), nullable=True)
     started_at = Column(DateTime(timezone=True), nullable=True)
     finished_at = Column(DateTime(timezone=True), nullable=True)
-    logs = Column(JSON, nullable=True)  # Store structured logs as JSON
+    logs = Column(JSON, nullable=True)  # Store structured logs as JSON (legacy, kept for backward compatibility)
     error = Column(String, nullable=True)
     result = Column(JSON, nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     params = Column(JSON, nullable=True)
 # [/DEF:TaskRecord:Class]
 
+# [DEF:TaskLogRecord:Class]
+# @PURPOSE: Represents a single persistent log entry for a task.
+# @TIER: CRITICAL
+# @RELATION: DEPENDS_ON -> TaskRecord
+# @INVARIANT: Each log entry belongs to exactly one task.
+class TaskLogRecord(Base):
+    __tablename__ = "task_logs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    task_id = Column(String, ForeignKey("task_records.id", ondelete="CASCADE"), nullable=False, index=True)
+    timestamp = Column(DateTime(timezone=True), nullable=False, index=True)
+    level = Column(String(16), nullable=False)  # INFO, WARNING, ERROR, DEBUG
+    source = Column(String(64), nullable=False, default="system")  # plugin, superset_api, git, etc.
+    message = Column(Text, nullable=False)
+    metadata_json = Column(Text, nullable=True)  # JSON string for additional metadata
+
+    # Composite indexes for efficient filtering
+    __table_args__ = (
+        Index('ix_task_logs_task_timestamp', 'task_id', 'timestamp'),
+        Index('ix_task_logs_task_level', 'task_id', 'level'),
+        Index('ix_task_logs_task_source', 'task_id', 'source'),
+    )
+# [/DEF:TaskLogRecord:Class]
+
 # [/DEF:backend.src.models.task:Module]

backend/src/plugins/backup.py

@@ -5,13 +5,14 @@
 # @RELATION: IMPLEMENTS -> PluginBase
 # @RELATION: DEPENDS_ON -> superset_tool.client
 # @RELATION: DEPENDS_ON -> superset_tool.utils
+# @RELATION: USES -> TaskContext
 
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 from pathlib import Path
 from requests.exceptions import RequestException
 
 from ..core.plugin_base import PluginBase
-from ..core.logger import belief_scope
+from ..core.logger import belief_scope, logger as app_logger
 from ..core.superset_client import SupersetClient
 from ..core.utils.network import SupersetAPIError
 from ..core.utils.fileio import (
@@ -23,6 +24,7 @@ from ..core.utils.fileio import (
     RetentionPolicy
 )
 from ..dependencies import get_config_manager
+from ..core.task_manager.context import TaskContext
 
 # [DEF:BackupPlugin:Class]
 # @PURPOSE: Implementation of the backup plugin logic.
@@ -75,6 +77,15 @@ class BackupPlugin(PluginBase):
             return "1.0.0"
     # [/DEF:version:Function]
 
+    @property
+    # [DEF:ui_route:Function]
+    # @PURPOSE: Returns the frontend route for the backup plugin.
+    # @RETURN: str - "/tools/backups"
+    def ui_route(self) -> str:
+        with belief_scope("ui_route"):
+            return "/tools/backups"
+    # [/DEF:ui_route:Function]
+
     # [DEF:get_schema:Function]
     # @PURPOSE: Returns the JSON schema for backup plugin parameters.
     # @PRE: Plugin instance exists.
@@ -84,7 +95,7 @@ class BackupPlugin(PluginBase):
         with belief_scope("get_schema"):
             config_manager = get_config_manager()
             envs = [e.name for e in config_manager.get_environments()]
-        default_path = config_manager.get_config().settings.backup_path
+        config_manager.get_config().settings.storage.root_path
         
         return {
             "type": "object",
@@ -95,26 +106,28 @@ class BackupPlugin(PluginBase):
                     "description": "The Superset environment to back up.",
                     "enum": envs if envs else [],
                 },
-                "backup_path": {
-                    "type": "string",
-                    "title": "Backup Path",
-                    "description": "The root directory to save backups to.",
-                    "default": default_path
-                }
             },
-            "required": ["env", "backup_path"],
+            "required": ["env"],
         }
     # [/DEF:get_schema:Function]
 
     # [DEF:execute:Function]
-    # @PURPOSE: Executes the dashboard backup logic.
+    # @PURPOSE: Executes the dashboard backup logic with TaskContext support.
-    # @PARAM: params (Dict[str, Any]) - Backup parameters (env, backup_path).
+    # @PARAM: params (Dict[str, Any]) - Backup parameters (env, backup_path, dashboard_ids).
+    # @PARAM: context (Optional[TaskContext]) - Task context for logging with source attribution.
     # @PRE: Target environment must be configured. params must be a dictionary.
     # @POST: All dashboards are exported and archived.
-    async def execute(self, params: Dict[str, Any]):
+    async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None):
         with belief_scope("execute"):
             config_manager = get_config_manager()
-            env_id = params.get("environment_id")
+            
+            # Support both parameter names: environment_id (for task creation) and env (for direct calls)
+            env_id = params.get("environment_id") or params.get("env")
+            dashboard_ids = params.get("dashboard_ids") or params.get("dashboards")
+            
+            # Log the incoming parameters for debugging
+            log = context.logger if context else app_logger
+            log.info(f"Backup parameters received: env_id={env_id}, dashboard_ids={dashboard_ids}")
             
             # Resolve environment name if environment_id is provided
             if env_id:
@@ -126,11 +139,20 @@ class BackupPlugin(PluginBase):
             if not env:
                 raise KeyError("env")
             
-            backup_path_str = params.get("backup_path") or config_manager.get_config().settings.backup_path
+            log.info(f"Backup started for environment: {env}, selected dashboards: {dashboard_ids}")
-            backup_path = Path(backup_path_str)
 
-            from ..core.logger import logger as app_logger
+            storage_settings = config_manager.get_config().settings.storage
-            app_logger.info(f"[BackupPlugin][Entry] Starting backup for {env}.")
+            # Use 'backups' subfolder within the storage root
+            backup_path = Path(storage_settings.root_path) / "backups"
+            
+            # Use TaskContext logger if available, otherwise fall back to app_logger
+            log = context.logger if context else app_logger
+            
+            # Create sub-loggers for different components
+            superset_log = log.with_source("superset_api") if context else log
+            storage_log = log.with_source("storage") if context else log
+            
+            log.info(f"Starting backup for environment: {env}")
 
             try:
                 config_manager = get_config_manager()
@@ -143,25 +165,43 @@ class BackupPlugin(PluginBase):
                 
                 client = SupersetClient(env_config)
                 
-                dashboard_count, dashboard_meta = client.get_dashboards()
+                # Get all dashboards
-                app_logger.info(f"[BackupPlugin][Progress] Found {dashboard_count} dashboards to export in {env}.")
+                all_dashboard_count, all_dashboard_meta = client.get_dashboards()
+                superset_log.info(f"Found {all_dashboard_count} total dashboards in environment")
+                
+                # Filter dashboards if specific IDs are provided
+                if dashboard_ids:
+                    dashboard_ids_int = [int(did) for did in dashboard_ids]
+                    dashboard_meta = [db for db in all_dashboard_meta if db.get('id') in dashboard_ids_int]
+                    dashboard_count = len(dashboard_meta)
+                    superset_log.info(f"Filtered to {dashboard_count} selected dashboards: {dashboard_ids_int}")
+                else:
+                    dashboard_count = all_dashboard_count
+                    superset_log.info("No dashboard filter applied - backing up all dashboards")
+                    dashboard_meta = all_dashboard_meta
 
                 if dashboard_count == 0:
-                    app_logger.info("[BackupPlugin][Exit] No dashboards to back up.")
+                    log.info("No dashboards to back up")
                     return
 
-                for db in dashboard_meta:
+                total = len(dashboard_meta)
+                for idx, db in enumerate(dashboard_meta, 1):
                     dashboard_id = db.get('id')
                     dashboard_title = db.get('dashboard_title', 'Unknown Dashboard')
                     if not dashboard_id:
                         continue
 
+                    # Report progress
+                    progress_pct = (idx / total) * 100
+                    log.progress(f"Backing up dashboard: {dashboard_title}", percent=progress_pct)
+
                     try:
                         dashboard_base_dir_name = sanitize_filename(f"{dashboard_title}")
                         dashboard_dir = backup_path / env.upper() / dashboard_base_dir_name
                         dashboard_dir.mkdir(parents=True, exist_ok=True)
 
                         zip_content, filename = client.export_dashboard(dashboard_id)
+                        superset_log.debug(f"Exported dashboard: {dashboard_title}")
 
                         save_and_unpack_dashboard(
                             zip_content=zip_content,
@@ -171,18 +211,19 @@ class BackupPlugin(PluginBase):
                         )
 
                         archive_exports(str(dashboard_dir), policy=RetentionPolicy())
+                        storage_log.debug(f"Archived dashboard: {dashboard_title}")
 
                     except (SupersetAPIError, RequestException, IOError, OSError) as db_error:
-                        app_logger.error(f"[BackupPlugin][Failure] Failed to export dashboard {dashboard_title} (ID: {dashboard_id}): {db_error}", exc_info=True)
+                        log.error(f"Failed to export dashboard {dashboard_title} (ID: {dashboard_id}): {db_error}")
                         continue
                 
                 consolidate_archive_folders(backup_path / env.upper())
                 remove_empty_directories(str(backup_path / env.upper()))
 
-                app_logger.info(f"[BackupPlugin][CoherenceCheck:Passed] Backup logic completed for {env}.")
+                log.info(f"Backup completed successfully for {env}")
 
             except (RequestException, IOError, KeyError) as e:
-                app_logger.critical(f"[BackupPlugin][Failure] Fatal error during backup for {env}: {e}", exc_info=True)
+                log.error(f"Fatal error during backup for {env}: {e}")
                 raise e
     # [/DEF:execute:Function]
 # [/DEF:BackupPlugin:Class]

backend/src/plugins/debug.py

@@ -3,6 +3,7 @@
 # @PURPOSE: Implements a plugin for system diagnostics and debugging Superset API responses.
 # @LAYER: Plugins
 # @RELATION: Inherits from PluginBase. Uses SupersetClient from core.
+# @RELATION: USES -> TaskContext
 # @CONSTRAINT: Must use belief_scope for logging.
 
 # [SECTION: IMPORTS]
@@ -10,6 +11,7 @@ from typing import Dict, Any, Optional
 from ..core.plugin_base import PluginBase
 from ..core.superset_client import SupersetClient
 from ..core.logger import logger, belief_scope
+from ..core.task_manager.context import TaskContext
 # [/SECTION]
 
 # [DEF:DebugPlugin:Class]
@@ -63,6 +65,15 @@ class DebugPlugin(PluginBase):
             return "1.0.0"
     # [/DEF:version:Function]
 
+    @property
+    # [DEF:ui_route:Function]
+    # @PURPOSE: Returns the frontend route for the debug plugin.
+    # @RETURN: str - "/tools/debug"
+    def ui_route(self) -> str:
+        with belief_scope("ui_route"):
+            return "/tools/debug"
+    # [/DEF:ui_route:Function]
+
     # [DEF:get_schema:Function]
     # @PURPOSE: Returns the JSON schema for the debug plugin parameters.
     # @PRE: Plugin instance exists.
@@ -105,20 +116,29 @@ class DebugPlugin(PluginBase):
     # [/DEF:get_schema:Function]
 
     # [DEF:execute:Function]
-    # @PURPOSE: Executes the debug logic.
+    # @PURPOSE: Executes the debug logic with TaskContext support.
     # @PARAM: params (Dict[str, Any]) - Debug parameters.
+    # @PARAM: context (Optional[TaskContext]) - Task context for logging with source attribution.
     # @PRE: action must be provided in params.
     # @POST: Debug action is executed and results returned.
     # @RETURN: Dict[str, Any] - Execution results.
-    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None) -> Dict[str, Any]:
         with belief_scope("execute"):
             action = params.get("action")
             
+            # Use TaskContext logger if available, otherwise fall back to app logger
+            log = context.logger if context else logger
+            debug_log = log.with_source("debug") if context else log
+            superset_log = log.with_source("superset_api") if context else log
+            
+            debug_log.info(f"Executing debug action: {action}")
+            
             if action == "test-db-api":
-                return await self._test_db_api(params)
+                return await self._test_db_api(params, superset_log)
             elif action == "get-dataset-structure":
-                return await self._get_dataset_structure(params)
+                return await self._get_dataset_structure(params, superset_log)
             else:
+                debug_log.error(f"Unknown action: {action}")
                 raise ValueError(f"Unknown action: {action}")
     # [/DEF:execute:Function]
 
@@ -127,33 +147,37 @@ class DebugPlugin(PluginBase):
     # @PRE:     source_env and target_env params exist in params.
     # @POST:    Returns DB counts for both envs.
     # @PARAM:   params (Dict) - Plugin parameters.
+    # @PARAM:   log - Logger instance for superset_api source.
     # @RETURN:  Dict - Comparison results.
-    async def _test_db_api(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def _test_db_api(self, params: Dict[str, Any], log) -> Dict[str, Any]:
         with belief_scope("_test_db_api"):
             source_env_name = params.get("source_env")
-        target_env_name = params.get("target_env")
+            target_env_name = params.get("target_env")
         
-        if not source_env_name or not target_env_name:
+            if not source_env_name or not target_env_name:
-            raise ValueError("source_env and target_env are required for test-db-api")
+                raise ValueError("source_env and target_env are required for test-db-api")
 
-        from ..dependencies import get_config_manager
+            from ..dependencies import get_config_manager
-        config_manager = get_config_manager()
+            config_manager = get_config_manager()
         
-        results = {}
+            results = {}
-        for name in [source_env_name, target_env_name]:
+            for name in [source_env_name, target_env_name]:
-            env_config = config_manager.get_environment(name)
+                log.info(f"Testing database API for environment: {name}")
-            if not env_config:
+                env_config = config_manager.get_environment(name)
-                raise ValueError(f"Environment '{name}' not found.")
+                if not env_config:
+                    log.error(f"Environment '{name}' not found.")
+                    raise ValueError(f"Environment '{name}' not found.")
             
-            client = SupersetClient(env_config)
+                client = SupersetClient(env_config)
-            client.authenticate()
+                client.authenticate()
-            count, dbs = client.get_databases()
+                count, dbs = client.get_databases()
-            results[name] = {
+                log.debug(f"Found {count} databases in {name}")
-                "count": count,
+                results[name] = {
-                "databases": dbs
+                    "count": count,
-            }
+                    "databases": dbs
+                }
             
-        return results
+            return results
     # [/DEF:_test_db_api:Function]
 
     # [DEF:_get_dataset_structure:Function]
@@ -161,26 +185,31 @@ class DebugPlugin(PluginBase):
     # @PRE:     env and dataset_id params exist in params.
     # @POST:    Returns dataset JSON structure.
     # @PARAM:   params (Dict) - Plugin parameters.
+    # @PARAM:   log - Logger instance for superset_api source.
     # @RETURN:  Dict - Dataset structure.
-    async def _get_dataset_structure(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def _get_dataset_structure(self, params: Dict[str, Any], log) -> Dict[str, Any]:
         with belief_scope("_get_dataset_structure"):
             env_name = params.get("env")
-        dataset_id = params.get("dataset_id")
+            dataset_id = params.get("dataset_id")
         
-        if not env_name or dataset_id is None:
+            if not env_name or dataset_id is None:
-            raise ValueError("env and dataset_id are required for get-dataset-structure")
+                raise ValueError("env and dataset_id are required for get-dataset-structure")
 
-        from ..dependencies import get_config_manager
+            log.info(f"Fetching structure for dataset {dataset_id} in {env_name}")
-        config_manager = get_config_manager()
-        env_config = config_manager.get_environment(env_name)
-        if not env_config:
-            raise ValueError(f"Environment '{env_name}' not found.")
             
-        client = SupersetClient(env_config)
+            from ..dependencies import get_config_manager
-        client.authenticate()
+            config_manager = get_config_manager()
+            env_config = config_manager.get_environment(env_name)
+            if not env_config:
+                log.error(f"Environment '{env_name}' not found.")
+                raise ValueError(f"Environment '{env_name}' not found.")
             
-        dataset_response = client.get_dataset(dataset_id)
+            client = SupersetClient(env_config)
-        return dataset_response.get('result') or {}
+            client.authenticate()
+        
+            dataset_response = client.get_dataset(dataset_id)
+            log.debug(f"Retrieved dataset structure for {dataset_id}")
+            return dataset_response.get('result') or {}
     # [/DEF:_get_dataset_structure:Function]
 
 # [/DEF:DebugPlugin:Class]

backend/src/plugins/git/llm_extension.py

@@ -0,0 +1,66 @@
+# [DEF:backend/src/plugins/git/llm_extension:Module]
+# @TIER: STANDARD
+# @SEMANTICS: git, llm, commit
+# @PURPOSE: LLM-based extensions for the Git plugin, specifically for commit message generation.
+# @LAYER: Domain
+# @RELATION: DEPENDS_ON -> backend.src.plugins.llm_analysis.service.LLMClient
+
+from typing import List
+from tenacity import retry, stop_after_attempt, wait_exponential
+from ..llm_analysis.service import LLMClient
+from ...core.logger import belief_scope, logger
+
+# [DEF:GitLLMExtension:Class]
+# @PURPOSE: Provides LLM capabilities to the Git plugin.
+class GitLLMExtension:
+    def __init__(self, client: LLMClient):
+        self.client = client
+
+    # [DEF:suggest_commit_message:Function]
+    # @PURPOSE: Generates a suggested commit message based on a diff and history.
+    # @PARAM: diff (str) - The git diff of staged changes.
+    # @PARAM: history (List[str]) - Recent commit messages for context.
+    # @RETURN: str - The suggested commit message.
+    @retry(
+        stop=stop_after_attempt(2),
+        wait=wait_exponential(multiplier=1, min=2, max=10),
+        reraise=True
+    )
+    async def suggest_commit_message(self, diff: str, history: List[str]) -> str:
+        with belief_scope("suggest_commit_message"):
+            history_text = "\n".join(history)
+            prompt = f"""
+            Generate a concise and professional git commit message based on the following diff and recent history.
+            Use Conventional Commits format (e.g., feat: ..., fix: ..., docs: ...).
+            
+            Recent History:
+            {history_text}
+            
+            Diff:
+            {diff}
+            
+            Commit Message:
+            """
+            
+            logger.debug(f"[suggest_commit_message] Calling LLM with model: {self.client.default_model}")
+            response = await self.client.client.chat.completions.create(
+                model=self.client.default_model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.7
+            )
+            
+            logger.debug(f"[suggest_commit_message] LLM Response: {response}")
+            
+            if not response or not hasattr(response, 'choices') or not response.choices:
+                error_info = getattr(response, 'error', 'No choices in response')
+                logger.error(f"[suggest_commit_message] Invalid LLM response. Error info: {error_info}")
+                
+                # If it's a timeout/provider error, we might want to throw to trigger retry if decorated
+                # but for now we return a safe fallback to avoid UI crash
+                return "Update dashboard configurations (LLM generation failed)"
+
+            return response.choices[0].message.content.strip()
+    # [/DEF:suggest_commit_message:Function]
+# [/DEF:GitLLMExtension:Class]
+
+# [/DEF:backend/src/plugins/git/llm_extension:Module]

backend/src/plugins/git_plugin.py

@@ -0,0 +1,399 @@
+# [DEF:backend.src.plugins.git_plugin:Module]
+#
+# @SEMANTICS: git, plugin, dashboard, version_control, sync, deploy
+# @PURPOSE:   Предоставляет плагин для версионирования и развертывания дашбордов Superset.
+# @LAYER:     Plugin
+# @RELATION:  INHERITS_FROM -> src.core.plugin_base.PluginBase
+# @RELATION:  USES -> src.services.git_service.GitService
+# @RELATION:  USES -> src.core.superset_client.SupersetClient
+# @RELATION:  USES -> src.core.config_manager.ConfigManager
+# @RELATION:  USES -> TaskContext
+#
+# @INVARIANT: Все операции с Git должны выполняться через GitService.
+# @CONSTRAINT: Плагин работает только с распакованными YAML-экспортами Superset.
+
+# [SECTION: IMPORTS]
+import os
+import io
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Dict, Any, Optional
+from src.core.plugin_base import PluginBase
+from src.services.git_service import GitService
+from src.core.logger import logger as app_logger, belief_scope
+from src.core.config_manager import ConfigManager
+from src.core.superset_client import SupersetClient
+from src.core.task_manager.context import TaskContext
+# [/SECTION]
+
+# [DEF:GitPlugin:Class]
+# @PURPOSE: Реализация плагина Git Integration для управления версиями дашбордов.
+class GitPlugin(PluginBase):
+    
+    # [DEF:__init__:Function]
+    # @PURPOSE: Инициализирует плагин и его зависимости.
+    # @PRE: config.json exists or shared config_manager is available.
+    # @POST: Инициализированы git_service и config_manager.
+    def __init__(self):
+        with belief_scope("GitPlugin.__init__"):
+            app_logger.info("Initializing GitPlugin.")
+            self.git_service = GitService()
+            
+            # Robust config path resolution:
+            # 1. Try absolute path from src/dependencies.py style if possible
+            # 2. Try relative paths based on common execution patterns
+            if os.path.exists("../config.json"):
+                config_path = "../config.json"
+            elif os.path.exists("config.json"):
+                config_path = "config.json"
+            else:
+                # Fallback to the one initialized in dependencies if we can import it
+                try:
+                    from src.dependencies import config_manager
+                    self.config_manager = config_manager
+                    app_logger.info("GitPlugin initialized using shared config_manager.")
+                    return
+                except Exception:
+                    config_path = "config.json"
+
+            self.config_manager = ConfigManager(config_path)
+            app_logger.info(f"GitPlugin initialized with {config_path}")
+    # [/DEF:__init__:Function]
+
+    @property
+    # [DEF:id:Function]
+    # @PURPOSE: Returns the plugin identifier.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Returns 'git-integration'.
+    def id(self) -> str:
+        with belief_scope("GitPlugin.id"):
+            return "git-integration"
+    # [/DEF:id:Function]
+
+    @property
+    # [DEF:name:Function]
+    # @PURPOSE: Returns the plugin name.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Returns the human-readable name.
+    def name(self) -> str:
+        with belief_scope("GitPlugin.name"):
+            return "Git Integration"
+    # [/DEF:name:Function]
+
+    @property
+    # [DEF:description:Function]
+    # @PURPOSE: Returns the plugin description.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Returns the plugin's purpose description.
+    def description(self) -> str:
+        with belief_scope("GitPlugin.description"):
+            return "Version control for Superset dashboards"
+    # [/DEF:description:Function]
+
+    @property
+    # [DEF:version:Function]
+    # @PURPOSE: Returns the plugin version.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Returns the version string.
+    def version(self) -> str:
+        with belief_scope("GitPlugin.version"):
+            return "0.1.0"
+    # [/DEF:version:Function]
+
+    @property
+    # [DEF:ui_route:Function]
+    # @PURPOSE: Returns the frontend route for the git plugin.
+    # @RETURN: str - "/git"
+    def ui_route(self) -> str:
+        with belief_scope("GitPlugin.ui_route"):
+            return "/git"
+    # [/DEF:ui_route:Function]
+
+    # [DEF:get_schema:Function]
+    # @PURPOSE: Возвращает JSON-схему параметров для выполнения задач плагина.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Returns a JSON schema dictionary.
+    # @RETURN: Dict[str, Any] - Схема параметров.
+    def get_schema(self) -> Dict[str, Any]:
+        with belief_scope("GitPlugin.get_schema"):
+            return {
+                "type": "object",
+                "properties": {
+                    "operation": {"type": "string", "enum": ["sync", "deploy", "history"]},
+                    "dashboard_id": {"type": "integer"},
+                    "environment_id": {"type": "string"},
+                    "source_env_id": {"type": "string"}
+                },
+                "required": ["operation", "dashboard_id"]
+            }
+    # [/DEF:get_schema:Function]
+
+    # [DEF:initialize:Function]
+    # @PURPOSE: Выполняет начальную настройку плагина.
+    # @PRE: GitPlugin is initialized.
+    # @POST: Плагин готов к выполнению задач.
+    async def initialize(self):
+        with belief_scope("GitPlugin.initialize"):
+            app_logger.info("[GitPlugin.initialize][Action] Initializing Git Integration Plugin logic.")
+
+    # [DEF:execute:Function]
+    # @PURPOSE: Основной метод выполнения задач плагина с поддержкой TaskContext.
+    # @PRE: task_data содержит 'operation' и 'dashboard_id'.
+    # @POST: Возвращает результат выполнения операции.
+    # @PARAM: task_data (Dict[str, Any]) - Данные задачи.
+    # @PARAM: context (Optional[TaskContext]) - Task context for logging with source attribution.
+    # @RETURN: Dict[str, Any] - Статус и сообщение.
+    # @RELATION: CALLS -> self._handle_sync
+    # @RELATION: CALLS -> self._handle_deploy
+    async def execute(self, task_data: Dict[str, Any], context: Optional[TaskContext] = None) -> Dict[str, Any]:
+        with belief_scope("GitPlugin.execute"):
+            operation = task_data.get("operation")
+            dashboard_id = task_data.get("dashboard_id")
+            
+            # Use TaskContext logger if available, otherwise fall back to app_logger
+            log = context.logger if context else app_logger
+            
+            # Create sub-loggers for different components
+            git_log = log.with_source("git") if context else log
+            superset_log = log.with_source("superset_api") if context else log
+            
+            log.info(f"Executing operation: {operation} for dashboard {dashboard_id}")
+            
+            if operation == "sync":
+                source_env_id = task_data.get("source_env_id")
+                result = await self._handle_sync(dashboard_id, source_env_id, log, git_log, superset_log)
+            elif operation == "deploy":
+                env_id = task_data.get("environment_id")
+                result = await self._handle_deploy(dashboard_id, env_id, log, git_log, superset_log)
+            elif operation == "history":
+                result = {"status": "success", "message": "History available via API"}
+            else:
+                log.error(f"Unknown operation: {operation}")
+                raise ValueError(f"Unknown operation: {operation}")
+            
+            log.info(f"Operation {operation} completed.")
+            return result
+    # [/DEF:execute:Function]
+
+    # [DEF:_handle_sync:Function]
+    # @PURPOSE: Экспортирует дашборд из Superset и распаковывает в Git-репозиторий.
+    # @PRE: Репозиторий для дашборда должен существовать.
+    # @POST: Файлы в репозитории обновлены до текущего состояния в Superset.
+    # @PARAM: dashboard_id (int) - ID дашборда.
+    # @PARAM: source_env_id (Optional[str]) - ID исходного окружения.
+    # @RETURN: Dict[str, str] - Результат синхронизации.
+    # @SIDE_EFFECT: Изменяет файлы в локальной рабочей директории репозитория.
+    # @RELATION: CALLS -> src.services.git_service.GitService.get_repo
+    # @RELATION: CALLS -> src.core.superset_client.SupersetClient.export_dashboard
+    async def _handle_sync(self, dashboard_id: int, source_env_id: Optional[str] = None, log=None, git_log=None, superset_log=None) -> Dict[str, str]:
+        with belief_scope("GitPlugin._handle_sync"):
+            try:
+                # 1. Получение репозитория
+                repo = self.git_service.get_repo(dashboard_id)
+                repo_path = Path(repo.working_dir)
+                git_log.info(f"Target repo path: {repo_path}")
+
+                # 2. Настройка клиента Superset
+                env = self._get_env(source_env_id)
+                client = SupersetClient(env)
+                client.authenticate()
+
+                # 3. Экспорт дашборда
+                superset_log.info(f"Exporting dashboard {dashboard_id} from {env.name}")
+                zip_bytes, _ = client.export_dashboard(dashboard_id)
+                
+                # 4. Распаковка с выравниванием структуры (flattening)
+                git_log.info(f"Unpacking export to {repo_path}")
+                
+                # Список папок/файлов, которые мы ожидаем от Superset
+                managed_dirs = ["dashboards", "charts", "datasets", "databases"]
+                managed_files = ["metadata.yaml"]
+                
+                # Очистка старых данных перед распаковкой, чтобы не оставалось "призраков"
+                for d in managed_dirs:
+                    d_path = repo_path / d
+                    if d_path.exists() and d_path.is_dir():
+                        shutil.rmtree(d_path)
+                for f in managed_files:
+                    f_path = repo_path / f
+                    if f_path.exists():
+                        f_path.unlink()
+
+                with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
+                    # Superset экспортирует всё в подпапку dashboard_export_timestamp/
+                    # Нам нужно найти это имя папки
+                    namelist = zf.namelist()
+                    if not namelist:
+                        raise ValueError("Export ZIP is empty")
+                    
+                    root_folder = namelist[0].split('/')[0]
+                    git_log.info(f"Detected root folder in ZIP: {root_folder}")
+                    
+                    for member in zf.infolist():
+                        if member.filename.startswith(root_folder + "/") and len(member.filename) > len(root_folder) + 1:
+                            # Убираем префикс папки
+                            relative_path = member.filename[len(root_folder)+1:]
+                            target_path = repo_path / relative_path
+                            
+                            if member.is_dir():
+                                target_path.mkdir(parents=True, exist_ok=True)
+                            else:
+                                target_path.parent.mkdir(parents=True, exist_ok=True)
+                                with zf.open(member) as source, open(target_path, "wb") as target:
+                                    shutil.copyfileobj(source, target)
+                
+                # 5. Автоматический staging изменений (не коммит, чтобы юзер мог проверить diff)
+                try:
+                    repo.git.add(A=True)
+                    app_logger.info("[_handle_sync][Action] Changes staged in git")
+                except Exception as ge:
+                    app_logger.warning(f"[_handle_sync][Action] Failed to stage changes: {ge}")
+
+                app_logger.info(f"[_handle_sync][Coherence:OK] Dashboard {dashboard_id} synced successfully.")
+                return {"status": "success", "message": "Dashboard synced and flattened in local repository"}
+
+            except Exception as e:
+                app_logger.error(f"[_handle_sync][Coherence:Failed] Sync failed: {e}")
+                raise
+    # [/DEF:_handle_sync:Function]
+
+    # [DEF:_handle_deploy:Function]
+    # @PURPOSE: Упаковывает репозиторий в ZIP и импортирует в целевое окружение Superset.
+    # @PRE: environment_id должен соответствовать настроенному окружению.
+    # @POST: Дашборд импортирован в целевой Superset.
+    # @PARAM: dashboard_id (int) - ID дашборда.
+    # @PARAM: env_id (str) - ID целевого окружения.
+    # @PARAM: log - Main logger instance.
+    # @PARAM: git_log - Git-specific logger instance.
+    # @PARAM: superset_log - Superset API-specific logger instance.
+    # @RETURN: Dict[str, Any] - Результат деплоя.
+    # @SIDE_EFFECT: Создает и удаляет временный ZIP-файл.
+    # @RELATION: CALLS -> src.core.superset_client.SupersetClient.import_dashboard
+    async def _handle_deploy(self, dashboard_id: int, env_id: str, log=None, git_log=None, superset_log=None) -> Dict[str, Any]:
+        with belief_scope("GitPlugin._handle_deploy"):
+            try:
+                if not env_id:
+                    raise ValueError("Target environment ID required for deployment")
+
+                # 1. Получение репозитория
+                repo = self.git_service.get_repo(dashboard_id)
+                repo_path = Path(repo.working_dir)
+
+                # 2. Упаковка в ZIP
+                git_log.info(f"Packing repository {repo_path} for deployment.")
+                zip_buffer = io.BytesIO()
+                
+                # Superset expects a root directory in the ZIP (e.g., dashboard_export_20240101T000000/)
+                root_dir_name = f"dashboard_export_{dashboard_id}"
+                
+                with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zf:
+                    for root, dirs, files in os.walk(repo_path):
+                        if ".git" in dirs:
+                            dirs.remove(".git")
+                        for file in files:
+                            if file == ".git" or file.endswith(".zip"):
+                                continue
+                            file_path = Path(root) / file
+                            # Prepend the root directory name to the archive path
+                            arcname = Path(root_dir_name) / file_path.relative_to(repo_path)
+                            zf.write(file_path, arcname)
+                
+                zip_buffer.seek(0)
+                
+                # 3. Настройка клиента Superset
+                env = self.config_manager.get_environment(env_id)
+                if not env:
+                    raise ValueError(f"Environment {env_id} not found")
+                
+                client = SupersetClient(env)
+                client.authenticate()
+
+                # 4. Импорт
+                temp_zip_path = repo_path / f"deploy_{dashboard_id}.zip"
+                git_log.info(f"Saving temporary zip to {temp_zip_path}")
+                with open(temp_zip_path, "wb") as f:
+                    f.write(zip_buffer.getvalue())
+                
+                try:
+                    app_logger.info(f"[_handle_deploy][Action] Importing dashboard to {env.name}")
+                    result = client.import_dashboard(temp_zip_path)
+                    app_logger.info(f"[_handle_deploy][Coherence:OK] Deployment successful for dashboard {dashboard_id}.")
+                    return {"status": "success", "message": f"Dashboard deployed to {env.name}", "details": result}
+                finally:
+                    if temp_zip_path.exists():
+                        os.remove(temp_zip_path)
+
+            except Exception as e:
+                app_logger.error(f"[_handle_deploy][Coherence:Failed] Deployment failed: {e}")
+                raise
+    # [/DEF:_handle_deploy:Function]
+
+    # [DEF:_get_env:Function]
+    # @PURPOSE: Вспомогательный метод для получения конфигурации окружения.
+    # @PARAM: env_id (Optional[str]) - ID окружения.
+    # @PRE: env_id is a string or None.
+    # @POST: Returns an Environment object from config or DB.
+    # @RETURN: Environment - Объект конфигурации окружения.
+    def _get_env(self, env_id: Optional[str] = None):
+        with belief_scope("GitPlugin._get_env"):
+            app_logger.info(f"[_get_env][Entry] Fetching environment for ID: {env_id}")
+            
+            # Priority 1: ConfigManager (config.json)
+            if env_id:
+                env = self.config_manager.get_environment(env_id)
+                if env:
+                    app_logger.info(f"[_get_env][Exit] Found environment by ID in ConfigManager: {env.name}")
+                    return env
+            
+            # Priority 2: Database (DeploymentEnvironment)
+            from src.core.database import SessionLocal
+            from src.models.git import DeploymentEnvironment
+            
+            db = SessionLocal()
+            try:
+                if env_id:
+                    db_env = db.query(DeploymentEnvironment).filter(DeploymentEnvironment.id == env_id).first()
+                else:
+                    # If no ID, try to find active or any environment in DB
+                    db_env = db.query(DeploymentEnvironment).filter(DeploymentEnvironment.is_active).first()
+                    if not db_env:
+                        db_env = db.query(DeploymentEnvironment).first()
+
+                if db_env:
+                    app_logger.info(f"[_get_env][Exit] Found environment in DB: {db_env.name}")
+                    from src.core.config_models import Environment
+                    # Use token as password for SupersetClient
+                    return Environment(
+                        id=db_env.id,
+                        name=db_env.name,
+                        url=db_env.superset_url,
+                        username="admin",
+                        password=db_env.superset_token,
+                        verify_ssl=True
+                    )
+            finally:
+                db.close()
+            
+            # Priority 3: ConfigManager Default (if no env_id provided)
+            envs = self.config_manager.get_environments()
+            if envs:
+                if env_id:
+                    # If env_id was provided but not found in DB or specifically by ID in config,
+                    # but we have other envs, maybe it's one of them?
+                    env = next((e for e in envs if e.id == env_id), None)
+                    if env:
+                        app_logger.info(f"[_get_env][Exit] Found environment {env_id} in ConfigManager list")
+                        return env
+                
+                if not env_id:
+                    app_logger.info(f"[_get_env][Exit] Using first environment from ConfigManager: {envs[0].name}")
+                    return envs[0]
+                
+            app_logger.error(f"[_get_env][Coherence:Failed] No environments configured (searched config.json and DB). env_id={env_id}")
+            raise ValueError("No environments configured. Please add a Superset Environment in Settings.")
+    # [/DEF:_get_env:Function]
+
+    # [/DEF:initialize:Function]
+# [/DEF:GitPlugin:Class]
+# [/DEF:backend.src.plugins.git_plugin:Module]

backend/src/plugins/llm_analysis/__init__.py

@@ -0,0 +1,14 @@
+# [DEF:backend/src/plugins/llm_analysis/__init__.py:Module]
+# @TIER: TRIVIAL
+# @PURPOSE: Initialize the LLM Analysis plugin package.
+# @LAYER: Domain
+
+"""
+LLM Analysis Plugin for automated dashboard validation and dataset documentation.
+"""
+
+from .plugin import DashboardValidationPlugin, DocumentationPlugin
+
+__all__ = ['DashboardValidationPlugin', 'DocumentationPlugin']
+
+# [/DEF:backend/src/plugins/llm_analysis/__init__.py:Module]