From 0d4e0336471010f4803223b70501d783ca73cd6e Mon Sep 17 00:00:00 2001
From: Yogini Aishwaryaa P T S <yoginianithakumar@gmail.com>
Date: Wed, 11 Mar 2026 09:49:39 +0530
Subject: [PATCH] Revise README.md with comprehensive project details

Expanded README.md to include detailed project overview, system architecture, file descriptions, development setup, and troubleshooting sections.
---
 README.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d2e7761..0abaf87 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,129 @@
-# React + TypeScript + Vite
+# Delta.
+
+## 1. Overview
+
+Delta is an automated documentation system that ensures documentation remains consistent with the underlying codebase through continuous drift detection and updates. Its architecture is divided into a React/TypeScript frontend for user interaction and a Python backend responsible for analysis, processing, and documentation generation.
+
+---
+
+## 2. System Architecture
+
+### 2.1 Technology Stack
+
+#### 2.1.1 Frontend Service (`/frontend`)
+
+- **Runtime Environment:** Node.js / Bun  
+- **Core Framework:** React 18  
+- **Language:** TypeScript 5.x  
+- **Build System:** Vite 5.x  
+- **Styling:** Tailwind CSS 3.x  
+
+#### 2.1.2 Backend Service (`/backend`)
+
+- **Runtime Environment:** Python 3.10+  
+- **Web Framework:** FastAPI  
+- **Server:** Uvicorn (ASGI)  
+- **Database:** PostgreSQL  
+- **ORM:** SQLAlchemy  
+- **Migration Tool:** Alembic  
+
+---
+
+## 3. File Description
+
+### 3.1 Frontend (`/frontend`)
+
+- **src/app/**: Contains core application configuration, global providers, and routing setup.  
+- **src/assets/**: Stores static assets such as images, fonts, and global CSS files.  
+- **src/components/**: Houses all reusable UI components.
+  - **shadcn/**: Implementation of the design system components (buttons, inputs, cards).
+  - **landing/**: Components specific to the marketing landing page (Hero, About, Animations).
+- **src/pages/**: Contains page components (Landing, Login, Signup) representing full views.  
+- **src/hooks/**: Custom React hooks for sharing stateful logic (e.g., scroll handling, authentication).  
+- **src/utils/**: Utility functions, constants, and helper classes.  
+
+### 3.2 Backend (`/backend`)
+
+- **app/**: The main application source code.  
+  - **api/**: Defines API route handlers and endpoints.  
+  - **core/**: Configuration settings (`config.py`) and security utilities (`security.py`).  
+  - **db/**: Database connection management and session handling.  
+  - **models/**: SQLAlchemy database models defining the schema (User, Repository, Drift).  
+  - **schemas/**: Models used for data validation and serialization.  
+  - **services/**: Business logic layer (GitHub API integration, Webhook processing).  
+- **alembic/**: Database migration scripts and version history.  
+- **tests/**: Unit and integration tests.  
+
+---
+
+## 4. Development Environment Setup
+
+### 4.1 Prerequisites
+
+Ensure the following tools are installed and configured in your environment path:
+
+- **Node.js:** v18.0.0+ (or Bun v1.0.0+)  
+- **Python:** v3.10+  
+- **Git:** Latest stable version  
+
+### 4.2 Installation & Execution
+
+#### 4.2.1 Frontend Service
+
+**Initialize:**
+
+```bash
+cd frontend
+bun install  # Alternatives: npm install, yarn install
+```
+
+**Execute:**
+
+```bash
+bun dev
+```
+Access via: http://localhost:5173
+
+#### 4.2.2 Backend Service
+
+refer [link](https://github.com/Delta-Docs/delta.backend)
+
+---
+
+## 5. Troubleshooting
+
+### 5.1 Frontend Issues
+
+**Issue:** "Module not found" or import errors.<br/>
+**Cause:** Missing dependencies or incorrect paths.<br/>
+**Fix:** Run bun install again. Verify tsconfig.json path aliases (e.g., @/components).<br/>
+<br/>
+**Issue:** Port 5173 in use.<br/>
+**Cause:** Another instance of the dev server is running.<br/>
+**Fix:** Check other terminals. Vite usually auto-switches to the next available port (e.g., 5174).<br/>
+<br/>
+
+### 5.2 Backend Issues
+
+**Issue:** ModuleNotFoundError: No module named fastapi <br/>
+**Cause:** Dependencies are not installed in the current environment.<br/>
+**Fix:** Ensure your virtual environment is active (.venv) and run `pip install -r requirements.txt`. <br/>
+<br/>
+**Issue:** uvicorn is not recognized <br/>
+**Cause:** System path issue or venv not active.<br/>
+**Fix:** Activate the venv. Alternatively, run `python -m uvicorn app.main:app --reload`.<br/>
+<br/>
+**Issue:** Database connection refused.<br/>
+**Cause:** PostgreSQL service is down or credentials in .env are wrong.<br/>
+**Fix:** Ensure Postgres is running. Check DATABASE_URL in .env.<br/>
+
+**Issue:** "alembic: command not found"<br/>
+**Cause:** Alembic not installed or not in path.<br/>
+**Fix:** Ensure venv is active. Run `pip install alembic`. Use `python -m alembic upgrade head`.<br/>
+
+## React + TypeScript + Vite
+
+## React + TypeScript + Vite
 
 This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.