🧠 DevMind — Autonomous AI Software Engineer & Code Intelligence Platform

Context-Grounded Multi-Agent Code Audits, AST Code Modifications, Verification, Failure Repair & Safe Git Recovery

Overview • Capabilities • Architecture • Safety & Recovery • Setup • Testing • Documentation Index

---

📖 DevMind Overview

DevMind is an enterprise-grade, context-grounded Autonomous AI Software Engineer & Code Intelligence Platform. It is engineered to analyze, refactor, modify, verify, and repair software repositories within isolated, deterministic safety boundaries.

Unlike conversational code assistants that produce raw text snippets, DevMind operates as a full-lifecycle software engineering agent. It translates natural language goal specifications into topological execution DAGs, performs AST-driven transactional code modifications, runs verification test suites, diagnoses failure tracebacks across a 7-tier evidence taxonomy, executes bounded autonomous repairs, and manages workspace safety with Git isolation and transactional rollback points.

---

🎯 Problem Statement & Solution

The Problem

• Context Loss: Generic LLMs struggle with large codebases, missing file-level dependencies, configuration settings, and call-graph boundaries.
• Unsafe Code Mutations: Blind patch applications often introduce syntax errors, break adjacent modules, or leak sensitive keys (.env, credentials).
• Hallucinated Solutions: Unverified LLM outputs claim code fixes without executing unit test suites or checking build outputs.
• Lack of Isolation: Direct modifications to a developer's working directory can corrupt unstaged work or cause Git merge conflicts.

The DevMind Solution

1. Multi-Agent & RAG Grounding: Combines FAISS vector embeddings, call-graph topology, and multi-agent consensus (Planner, Reviewer, Security, Critic).
2. Deterministic Safety Boundaries: Enforces strict path validation (WorkspaceSafetyService), snapshot ownership tracking, and transactional rollback mechanisms.
3. AST & Transactional Diff Modifications: Applies code modifications inside isolated dry-run buffers before staging.
4. Evidence-Driven Autonomous Repair: Executes unit tests, captures stdout/stderr, diagnoses root causes across 7 evidence tiers, and performs bounded repair loops (max 3 attempts).
5. Verified Change Review & Commit Gate: Requires explicit verification proof and user authorization before committing changes to Git.

---

🚀 Core Capabilities

Capability	Module / Engine	Description
Repository Intelligence	ScannerService / KnowledgeGraph	AST & static scanning, dependency graph parsing, call-graph extraction, and FAISS RAG vector indexing.
Task Understanding	TaskUnderstandingEngine (9.1)	Intent classification, task scoping, file boundary resolution, and prompt requirement normalization.
Topological Planning	PlanningEngine (8.4)	Dependency DAG generation, topological step sorting, cycle detection, and execution readiness scoring.
Code Modification	CodeModificationEngine (9.2)	AST-driven patch generation, unified diff formatting, transactional dry-run checks, and backup management.
Verification Console	VerificationEngine (9.3)	Automated test execution (pytest, npm test), build checking, log evidence collection, and regression detection.
Autonomous Failure Repair	FailureDiagnosisService (9.4)	7-tier failure evidence hierarchy diagnosis, hypothesis generation, and bounded self-repair iteration loops.
Master Workflow	AutonomousWorkflowOrchestrator (9.5)	12-stage state machine (TASK_UNDERSTANDING $\rightarrow$ COMPLETED), SSE streaming, pause/resume approval gates.
Workspace Safety & Isolation	WorkspaceSafetyService (10.1)	Isolated workspace directories, path traversal prevention, file locks, and snapshot state tracking.
Change Review & Commit	ChangeReviewService (10.2)	Verified commit eligibility gating, diff inspections, conventional commit generation, and ownership tags.
Git Recovery Engine	GitRecoveryEngine (10.3)	Safe commit reverts, snapshot rollbacks, conflict prevention against user work, and recovery state tracking.
AI Quality Evaluation	aiEvaluation.ts (11.4)	Deterministic evaluation of task clarity, plan validity, diff syntax, test evidence, and diagnostic confidence.
Accessibility & Stabilization	Phase 11.5 Polish	Full Dark/Light theme polish, focus management, ARIA dialog roles, reduced motion, zero lint warnings.

---

🏛️ System Architecture

DevMind uses a decoupled architecture separating a high-performance Python FastAPI Backend from a Vite + React 18 TypeScript Frontend.

┌───────────────────────────────────────────────────────────────────────────────────┐
│                                   REACT FRONTEND                                  │
│  ┌──────────────────────┐   ┌────────────────────────┐   ┌─────────────────────┐  │
│  │   App Shell & Nav    │   │  Contexts & Providers  │   │  Workspace Views    │  │
│  │  (Phase 11.2 Shell)  │──>│ (Analysis & Workflow)  │──>│ (IDE, DAG, Console) │  │
│  └──────────────────────┘   └────────────────────────┘   └─────────────────────┘  │
└─────────────────────────────────────────┬─────────────────────────────────────────┘
                                          │ Axios API / SSE Live Stream
                                          ▼
┌───────────────────────────────────────────────────────────────────────────────────┐
│                                  FASTAPI BACKEND                                  │
│  ┌──────────────────────┐   ┌────────────────────────┐   ┌─────────────────────┐  │
│  │    REST Routers      │   │   Domain Orchestrators │   │  Workspace Safety   │  │
│  │  (/api/v1/workflows) │──>│  (Master 12-Stage Engine)│──>│  (Isolation & Git)  │  │
│  └──────────────────────┘   └────────────────────────┘   └─────────────────────┘  │
│                                         │                                         │
│        ┌────────────────────────────────┼────────────────────────────────┐        │
│        ▼                                ▼                                ▼        │
│  ┌───────────┐                  ┌───────────────┐                  ┌───────────┐  │
│  │ AI/RAG    │                  │ Mod & Verify  │                  │ Storage   │  │
│  │ (FAISS)   │                  │ (AST/Pytest)  │                  │ (Postgres)│  │
│  └───────────┘                  └───────────────┘                  └───────────┘  │
└───────────────────────────────────────────────────────────────────────────────────┘

---

🛡️ Workspace Safety & Git Recovery

DevMind enforces zero-trust safety constraints around workspace operations:

• Protected Path Boundary: Restricts modification of system paths (.git, .env, credentials, lockfiles).
• Path Traversal Prevention: Resolves canonical absolute paths, rejecting directory traversal attempts (../).
• Execution Locks: Uses mutex locks (asyncio.Lock) per workspace to prevent concurrent mutating operations.
• Safe Revert Eligibility: Verifies commit ownership before git revert, checking that no untracked user changes will be corrupted.

---

⚙️ Technology Stack

Layer	Component	Technologies
Backend Framework	Asynchronous API	Python 3.10+, FastAPI 0.100+, Uvicorn ASGI
Database & Storage	ORM & Relational DB	PostgreSQL, SQLAlchemy, Alembic Migrations
Vector Engine	Code Indexing & Search	FAISS (Facebook AI Similarity Search), SentenceTransformers
Testing & Quality	Backend Test Suite	Pytest (109 Unit & Integration Tests Passed)
Frontend Core	Application Build	React 18, TypeScript, Vite 8, React Router v6
Design System	UI Tokens & Styling	Vanilla CSS Custom Variables, TailwindCSS
State & Streaming	Live Updates	React Context API, Server-Sent Events (SSE), rAF Buffering

---

💻 Setup & Installation

Prerequisites

• Python 3.10+
• Node.js 18+ & npm
• Git

Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv .venv

# Activate environment (Windows)
.venv\Scripts\activate
# Activate environment (Linux/macOS)
# source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Run database migrations
alembic upgrade head

# Run backend unit test suite (109 tests)
..\.venv\Scripts\pytest

# Start FastAPI dev server (default port 8000)
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Frontend Setup

# In project root directory
npm install

# Run TypeScript type check
npm run typecheck

# Run linter (0 warnings, 0 errors)
npm run lint

# Start Vite dev server
npm run dev

# Build production bundle
npm run build

---

📊 Development Phase History

• Phase 1 – 7: Core Infrastructure, Repository Scanner, AI Reasoning Failover, Interactive Dashboard, FAISS Semantic RAG, Multi-Agent Collaboration, and Execution Memory.
• Phase 8 (8.4 – 8.9): Intelligent Planning, Adaptive Execution, Multi-Agent Collaboration, Memory & Learning, Autonomous Reasoning, Policy Decision Engine.
• Phase 9 (9.1 – 9.5): Task Understanding (9.1), AST Code Modification (9.2), Test Verification (9.3), Failure Diagnosis & Repair (9.4), Master 12-Stage Orchestrator (9.5).
• Phase 10 (10.1 – 10.5): Workspace Safety (10.1), Verified Change Review (10.2), Safe Git Recovery (10.3), Security Validation (10.4), Regression & Stabilization (10.5).
• Phase 11 (11.1 – 11.5): Design System (11.1), Navigation Shell (11.2), Contextual Workspaces (11.3), Performance & AI Quality (11.4), Technical Documentation & UML (11.4.1), Final Dark/Light Polish, Accessibility & v1.0 Stabilization (11.5).

---

📚 Complete Technical Documentation

Comprehensive documentation is available in the docs/ directory:

• 📄 Documentation Entry Point
• 📄 Project Overview
• 📄 Complete Master Project Report
• 🏛️ System Architecture
• 🖥️ Frontend Architecture
• ⚙️ Backend Architecture
• 🧠 AI & Engineering Intelligence Architecture
• 🔄 Data Flow Architecture
• 🛡️ Security Architecture
• 📊 Phase Development History
• 📐 Mermaid UML Diagrams
• 🗺️ Future Roadmap

---

⚠️ Known Limitations

1. Local Git Worktree Scoping: Remote Git operations require configured SSH keys or OAuth tokens; unauthenticated private repositories are restricted.
2. Targeted Syntaxes: AST diff generation is optimized for Python, TypeScript, JavaScript, and JSON; raw text patch fallback is used for unparsed file types.
3. Execution Limits: Autonomous repair loops are bounded to a maximum of 3 attempts per workflow run to prevent infinite loop resource consumption.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.