Update documentation

README.md

@@ -77,7 +77,6 @@
 avaaz.ai/
 ├── .dockerignore                    # Specifies files and directories to exclude from Docker builds, such as .git, node_modules, and build artifacts, to optimize image sizes.
 ├── .gitignore                       # Lists files and patterns to ignore in Git, including .env, __pycache__, node_modules, and logs, preventing sensitive or temporary files from being committed.
-├── .gitattributes                   # Controls Git’s handling of files across platforms (e.g. normalizing line endings with * text=auto), and can force certain files to be treated as binary or configure diff/merge drivers.
 │
 ├── .env.example                     # Template for environment variables, showing required keys like DATABASE_URL, GEMINI_API_KEY, LIVEKIT_API_KEY without actual values.
 ├── docker-compose.dev.yml           # Docker Compose file for development environment: defines services for local frontend, backend, postgres, livekit with volume mounts for hot-reloading.

app/README.md

@@ -1,5 +1,47 @@
-# Configuration
+# 1. Run Applicaiton
 
-## 1. Configure the VPS
+1. Remove all cached Python packages stored by pip, remove local Python cache files, clear the cache used by uv, and forcibly clear the cache for Node.js.
 
-## 2. Configure the Development Laptop
+    ```bash
+    uv tool install cleanpy
+    pip cache purge && cleanpy . && uv cache clean && npm cache clean --force
+    ```
+
+2. Resolve dependencies from *pyproject.toml* and upgrade all packages. Synchronize the virtual environment with the dependencies specified in the *uv.lock* including packages needed for **development**.
+
+    ```bash
+    cd backend
+    uv lock --upgrade
+    uv sync --dev
+    ```
+
+3. Lint and check code for errors, style issues, and potential bugs, and try to fix them. Discover and run tests in *tests/*.
+
+    ```bash
+    uv run ruff check --fix && uv run pytest
+    ```
+
+4. Start a local **development** API server, visible at port 8000, and automatically reloads the server when code changes are made.
+
+    ```bash
+    uv run uvicorn src.main:app --reload --port 8000
+    ```
+
+5. Open a new terminal. Scan dependencies for security vulnerabilities and attempt to automatically fix them by force-updating to the latest secure versions.
+
+    ```bash
+    cd frontend
+    npm audit fix --force
+    ```
+
+6. Install dependencies from *package.json*, then update those dependencies to the latest allowed versions based on version ranges. Next, check the source code for stylistic and syntax errors according to configured rules. Finally, compile or bundle the application for deployment or production use.
+
+    ```bash
+    npm install && npm update && npm run lint && npm run build
+    ```
+
+7. Execute start script in *package.json*, launch Node.js application in **development** mode.
+
+    ```bash
+    npm run dev
+    ```

docs/architecture.md

@@ -115,7 +115,7 @@ flowchart LR
 
 #### Infra Stack
 
-Docker Compose from the `avaaz-infra` Git repository is cloned to `/srv/infra/docker-compose.yml` on the VPS.
+Docker Compose from `./infra/docker-compose.yml` is cloned to `/srv/infra/docker-compose.yml` on the VPS.
 
 | Container      | Description                                                                         |
 | -------------- | ----------------------------------------------------------------------------------- |
@@ -125,7 +125,7 @@ Docker Compose from the `avaaz-infra` Git repository is cloned to `/srv/infra/do
 
 #### App Stack
 
-Docker Compose from the `avaaz-app` Git repository is cloned to `/srv/app/docker-compose.yml` on the VPS.
+Docker Compose from `./app/docker-compose.yml` is cloned to `/srv/app/docker-compose.yml` on the VPS.
 
 | Container  | Description                                                                               |
 | ---------- | ----------------------------------------------------------------------------------------- |
@@ -134,7 +134,7 @@ Docker Compose from the `avaaz-app` Git repository is cloned to `/srv/app/docker
 | `postgres` | **PostgreSQL + pgvector** – Persistent relational database with vector search.            |
 | `livekit`  | **LiveKit Server** – WebRTC signaling plus UDP media for real-time audio and data.       |
 
-The `backend` uses several Python packages such as UV, Ruff, FastAPI, FastAPI Users, FastAPI-pagination, FastStream, Pydantic, PydanticAI, Pydantic-settings, LiveKit Agent, Google Gemini Live API, OpenAI Realtime API, SQLAlchemy, Alembic, docling, Gunicorn, Uvicorn[standard], Pyright, Pytest, Hypothesis, and Httpx to deliver the services.
+The `backend` uses several Python packages such as UV, Ruff, FastAPI, FastAPI Users, FastAPI-pagination, FastStream, FastMCP, Pydantic, PydanticAI, Pydantic-settings, LiveKit Agent, Google Gemini Live API, OpenAI Realtime API, SQLAlchemy, Alembic, docling, Gunicorn, Uvicorn[standard], Pyright, Pytest, Hypothesis, and Httpx to deliver the services.
 
 ### 1.2 Network
 

docs/docker.md

@@ -9,6 +9,7 @@ The following command will delete ALL Docker data, including stopped containers,
 
     ```bash
     cd /srv/infra
+    sudo docker stop $(sudo docker ps -a -q) && sudo docker rm $(sudo docker ps -a -q)
     sudo docker compose down -v --rmi all --remove-orphans
     ```
 

docs/git.md

@@ -8,7 +8,7 @@
 
 ## Pull Request
 
-1. Ensure your main branch is protected, so that direct push is disabled.
+1. Ensure your main branch is protected on Gitea configuration, so that direct push is disabled.
 
 2. Update the local main branch.
 
@@ -69,10 +69,10 @@
     git push origin --delete feature/new-branch
     ```
 
-13. Create a new branch for upcoming work, for example `feature/dev`.
+13. Create a new branch for upcoming work, for example `feature/new-branch-2`.
 
     ```bash
-    git checkout -b feature/dev
+    git checkout -b feature/new-branch-2
     ```
 
 ## Troubleshooting

infra/README.md

@@ -87,11 +87,7 @@
 4. Install dependencies for Docker’s official repo
 
     ```bash
-    sudo apt install -y \
-        ca-certificates \
-        curl \
-        gnupg \
-        lsb-release
+    sudo apt install -y ca-certificates curl gnupg lsb-release
     ```
 
 5. Add Docker’s official APT repo.
@@ -99,15 +95,11 @@
     ```bash
     sudo install -m 0755 -d /etc/apt/keyrings
 
-    curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-        sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
 
-    echo \
-        "deb [arch=$(dpkg --print-architecture) \
-        signed-by=/etc/apt/keyrings/docker.gpg] \
-        https://download.docker.com/linux/ubuntu \
-        $(lsb_release -cs) stable" \
-        sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+    sudo chmod a+r /etc/apt/keyrings/docker.gpg
+
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
     sudo apt update
     ```
@@ -115,12 +107,7 @@
 6. Install Docker Engine + compose plugin.
 
     ```bash
-    sudo apt install -y \
-        docker-ce \
-        docker-ce-cli \
-        containerd.io \
-        docker-buildx-plugin \
-        docker-compose-plugin
+    sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
     ```
 
 7. Verify the installation.