From 6a603e2b78caa476b9277277351453ba0e52a536 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:53:16 +0300 Subject: [PATCH] chore: commit docs/Architecture.md --- docs/Architecture.md | 197 +++++++------------------------------------ 1 file changed, 32 insertions(+), 165 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index 4ebec88ec7..022e0d3c26 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -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/**`