mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-15 23:31:04 +00:00
chore: commit docs/Architecture.md
This commit is contained in:
sumeyaaaa
parent
e243a67cba
commit
6a603e2b78
1 changed files with 32 additions and 165 deletions
|
|
@ -1,180 +1,47 @@
|
|||
## **1. Project Overview**
|
||||
# Project Architecture
|
||||
|
||||
**Goal:**
|
||||
Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified.
|
||||
## Overview
|
||||
|
||||
**Core Features:**
|
||||
This is a TypeScript/Node.js project with an API layer, services, and type definitions.
|
||||
|
||||
- **Two-stage Reasoning Loop** (State Machine):
|
||||
## Directory Structure
|
||||
|
||||
- **Stage 1:** Capture client intent, map to AI code action.
|
||||
- **Stage 2:** Validate AI-generated code, detect misalignment, log corrections.
|
||||
### API Layer (`src/api/`)
|
||||
|
||||
- **Hook System Integration**:
|
||||
- REST API endpoints and route handlers
|
||||
- Request/response validation using Zod schemas
|
||||
- Authentication endpoints (login, register, etc.)
|
||||
- Error handling middleware
|
||||
|
||||
- Identify injection points in **Roo Code** for tracking.
|
||||
- Pre-commit, post-commit, and runtime hooks for tracing execution.
|
||||
### Services (`src/services/`)
|
||||
|
||||
- **`.orchestration/` directory**:
|
||||
- Business logic layer
|
||||
- Database operations
|
||||
- External API integrations
|
||||
- User management services
|
||||
|
||||
- Stores intent metadata, execution logs, and reasoning states.
|
||||
### Types (`src/types/`)
|
||||
|
||||
- **Intent-Code Mapping**:
|
||||
- TypeScript type definitions
|
||||
- Shared interfaces and types
|
||||
- User models and DTOs
|
||||
|
||||
- Links user intent → AI agent decisions → generated code → execution results.
|
||||
### Configuration (`src/config/`)
|
||||
|
||||
- **Auditability**:
|
||||
- Environment variables
|
||||
- Application configuration
|
||||
- Constants (JWT secrets, expiration times, etc.)
|
||||
|
||||
- Every code change is traceable to its originating intent.
|
||||
## Key Technologies
|
||||
|
||||
---
|
||||
- Express.js for API routes
|
||||
- Zod for schema validation
|
||||
- JWT for authentication
|
||||
- TypeScript for type safety
|
||||
|
||||
## **2. Architecture Layers**
|
||||
## Intent Areas
|
||||
|
||||
### **A. Input Layer (Intent Capture)**
|
||||
|
||||
- **Source:** User commands in the IDE, chat prompts, or code requests.
|
||||
- **Components:**
|
||||
|
||||
- Intent Parser (NLP model / regex-based)
|
||||
- Preprocessing Engine (normalize ambiguous input)
|
||||
|
||||
- **Output:** Structured intent objects (`JSON/YAML`).
|
||||
|
||||
### **B. Hook System Layer**
|
||||
|
||||
- **Integration Points:** Roo Code Extension
|
||||
|
||||
- **Pre-commit hook:** Captures intent vs proposed AI code.
|
||||
- **Post-commit hook:** Logs executed code and execution result.
|
||||
- **Custom Reasoning hooks:** Intercepts AI agent output for validation.
|
||||
|
||||
- **Responsibilities:**
|
||||
|
||||
- Validate AI output before commit.
|
||||
- Trigger state updates in Reasoning Loop.
|
||||
- Maintain orchestration logs.
|
||||
|
||||
### **C. Orchestration & Reasoning Layer**
|
||||
|
||||
- **State Machine (Two-Stage Loop)**:
|
||||
|
||||
- **Stage 1: Intent → Proposed Code**
|
||||
|
||||
- AI agent generates code based on captured intent.
|
||||
- Hook system verifies structure and alignment.
|
||||
|
||||
- **Stage 2: Code Validation**
|
||||
|
||||
- Execute test cases or lint checks.
|
||||
- Detect mismatches and suggest corrections.
|
||||
|
||||
- **Data Storage:** `.orchestration/` directory
|
||||
|
||||
- Stores:
|
||||
|
||||
- Intent metadata
|
||||
- AI decisions and reasoning traces
|
||||
- Validation results
|
||||
- Hook system logs
|
||||
|
||||
### **D. Storage & Traceability Layer**
|
||||
|
||||
- **File System:** `.orchestration/` for local tracking
|
||||
- **Optional DB:** Lightweight database (SQLite/PostgreSQL) for:
|
||||
|
||||
- Intent history
|
||||
- AI agent output logs
|
||||
- Validation state
|
||||
|
||||
- **Purpose:** Allows historical analysis and auditability.
|
||||
|
||||
### **E. Output & Feedback Layer**
|
||||
|
||||
- **Developer Feedback:**
|
||||
|
||||
- Misalignment alerts
|
||||
- Suggested corrections
|
||||
- Intent-Code mapping visualizations
|
||||
|
||||
- **Metrics & Analysis:**
|
||||
|
||||
- Traceability coverage
|
||||
- Reasoning loop success rate
|
||||
- Hook system performance
|
||||
|
||||
---
|
||||
|
||||
## **3. Development Plan / Workflow**
|
||||
|
||||
1. **Phase 0: Prep**
|
||||
|
||||
- Review `ARCHITECTURE-NOTES.md` for Roo Code injection points.
|
||||
- Map the cognitive and trust debt decisions → reasoning logic.
|
||||
- Setup Git repo with **Git Speck Kit**.
|
||||
|
||||
2. **Phase 1: Hook System Implementation**
|
||||
|
||||
- Identify Roo Code extension points for:
|
||||
|
||||
- pre-commit
|
||||
- post-commit
|
||||
- runtime reasoning interception
|
||||
|
||||
- Build hook scripts.
|
||||
- Unit test hooks independently.
|
||||
|
||||
3. **Phase 2: Reasoning Loop**
|
||||
|
||||
- Implement two-stage state machine.
|
||||
- Connect hooks to Reasoning Loop states.
|
||||
- Implement intent validation logic.
|
||||
|
||||
4. **Phase 3: Orchestration Directory**
|
||||
|
||||
- `.orchestration/` for:
|
||||
|
||||
- intent.json
|
||||
- reasoning_state.json
|
||||
- validation_results.json
|
||||
|
||||
- Implement read/write APIs for traceability.
|
||||
|
||||
5. **Phase 4: Logging & Traceability**
|
||||
|
||||
- Implement audit logs for every hook event.
|
||||
- Integrate with Git Speck Kit for code snapshots.
|
||||
- Enable metrics collection for AI alignment tracking.
|
||||
|
||||
6. **Phase 5: Testing & Validation**
|
||||
|
||||
- Create sample AI-generated code scenarios.
|
||||
- Test traceability pipeline end-to-end.
|
||||
- Measure coverage of intent-code alignment.
|
||||
|
||||
7. **Phase 6: Documentation**
|
||||
|
||||
- Maintain `ARCHITECTURE_NOTES.md` and `README.md`.
|
||||
- Document hook usage, state machine, and orchestration structure.
|
||||
|
||||
---
|
||||
|
||||
## **4. Tech Stack / Tools**
|
||||
|
||||
- **Git & Git Speck Kit:** Source control, snapshots, hooks.
|
||||
- **Python / Node.js:** For hooks and orchestration logic.
|
||||
- **JSON/YAML:** Intent and traceability storage.
|
||||
- **Roo Code Extension:** Injection points for hook system.
|
||||
- **Lightweight DB (Optional):** SQLite or PostgreSQL for logs.
|
||||
- **NLP / Parsing:** Optional intent parsing models.
|
||||
- **Testing Frameworks:** pytest / Jest for automated validation.
|
||||
|
||||
---
|
||||
|
||||
## **5. Key Architectural Decisions (From Cognitive & Trust Debt)**
|
||||
|
||||
- Track only **AI-generated code relevant to intent** instead of all outputs.
|
||||
- Enforce **two-stage validation loop** to prevent drift between intent and code.
|
||||
- Maintain **self-contained orchestration directory** to simplify tracing and rollback.
|
||||
- Use **hooks as checkpoints** rather than full code reviews to scale traceability.
|
||||
- **Metrics-driven design:** Log reasoning steps to improve future AI alignment.
|
||||
1. **API Development** - All API endpoints and handlers in `src/api/**`
|
||||
2. **Service Layer** - Business logic in `src/services/**`
|
||||
3. **Type Definitions** - Type system in `src/types/**`
|
||||
4. **Configuration** - Config management in `src/config/**`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue