From 75c2aff4d743e6feee5abe4d34da5825739096d3 Mon Sep 17 00:00:00 2001
From: Livio Meuli <livio.meuli@ksb-sg.ch>
Date: Thu, 26 Mar 2026 22:43:53 +0100
Subject: [PATCH] Update README with detailed project structure and component
 responsibilities

---
 README.md | 81 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 63 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 0b2b9c0..97f4062 100644
--- a/README.md
+++ b/README.md
@@ -8,33 +8,78 @@ AI-Supported Lightweight Code Editor built with Streamlit (AISE501 Spring 2026)
 AISE_AIAgent/
 ├── frontend/                      # Streamlit UI Components
 │   ├── __init__.py
-│   ├── app.py                    # Main Streamlit application
-│   ├── sidebar.py                # File navigation sidebar
-│   ├── editor.py                 # Code editor pane
-│   └── chat.py                   # Chat interface
+│   ├── app.py                    # Main Streamlit application entry point
+│   ├── sidebar.py                # File navigation sidebar component
+│   ├── editor.py                 # Code editor pane component
+│   └── chat.py                   # Chat interface component
 │
 ├── backend/                       # Backend Logic Modules
 │   ├── __init__.py
-│   └── managers/                 # Business logic managers
+│   ├── managers/                 # Business logic for UI operations
+│   │   ├── __init__.py
+│   │   ├── file_manager.py       # File I/O operations for UI (read, write, list files)
+│   │   ├── chat_manager.py       # AI chat management and history
+│   │   ├── system_prompter.py    # System prompts and context injection
+│   │   ├── search_manager.py     # Internet search functionality
+│   │   ├── execution_engine.py   # Code execution and sandboxing
+│   │   └── debug_logger.py       # Logging, error handling, debug messages
+│   │
+│   ├── agents/                   # AI Agent System
+│   │   ├── __init__.py
+│   │   ├── coding_agent.py       # Main agent loop (plan-act-observe cycle)
+│   │   └── tools.py              # Tools available to agent (7 functions + dispatcher)
+│   │
+│   └── utils/                    # Helper Utilities
 │       ├── __init__.py
-│       ├── file_manager.py       # File I/O operations
-│       ├── chat_manager.py       # AI chat management
-│       ├── system_prompter.py    # System prompts & context
-│       ├── search_manager.py     # Internet search
-│       ├── execution_engine.py   # Code execution
-│       └── debug_logger.py       # Logging & debugging
+│       └── server_utils.py       # LLM client init, chat functions, formatters
 │
-├── tests/                         # Unit tests
+├── tests/                         # Unit Tests
 │   ├── __init__.py
-│   ├── test_file_manager.py
-│   ├── test_chat_manager.py
-│   └── test_execution_engine.py
+│   ├── test_file_manager.py      # Tests for file operations
+│   ├── test_chat_manager.py      # Tests for chat functionality
+│   ├── test_execution_engine.py  # Tests for code execution
+│   └── test_main.py              # Integration tests
 │
-├── .gitignore                     # Git exclusions
-├── requirements.txt               # Python dependencies
-└── README.md                      # This file
+├── workspace/                     # Agent Sandbox Directory
+│   └── .gitkeep                  # Placeholder for agent to work safely in isolation
+│
+├── .gitignore                     # Git exclusions (venv, .env, __pycache__, etc.)
+├── .env                          # Local environment variables (NOT committed)
+├── .env.example                  # Template for environment variables (IS committed)
+├── requirements.txt              # Python dependencies
+├── README.md                      # This file
+└── project_exercise.pdf          # Project specification
 ```
 
+## Component Responsibilities
+
+### Frontend (`frontend/`)
+- **app.py**: Main Streamlit application, layout orchestration
+- **sidebar.py**: File browser and project navigation
+- **editor.py**: Code editing interface with syntax highlighting
+- **chat.py**: AI assistant chat interface
+
+### Backend Managers (`backend/managers/`)
+Used directly by Frontend for UI operations:
+- **file_manager.py**: CRUD operations on project files
+- **chat_manager.py**: Chat history, message management
+- **system_prompter.py**: System prompt generation and file context
+- **execution_engine.py**: Safe code execution with output capture
+- **debug_logger.py**: Error tracking and log formatting
+- **search_manager.py**: Web search integration
+
+### Backend Agents (`backend/agents/`)
+Independent AI agent system for complex tasks:
+- **coding_agent.py**: Agent loop (Plan → Act → Observe → Repeat)
+- **tools.py**: 7 tools agent can use (read/write/run/search/validate/grep/done)
+
+### Backend Utils (`backend/utils/`)
+- **server_utils.py**: LLM client initialization, chat helpers, message formatters
+
+### Workspace (`workspace/`)
+- Sandbox directory where agent executes and stores files
+- Prevents agent from accessing files outside this directory
+
 ## Features
 
 - **File Display & Management**: Browse and edit code files