Update: backend README.md

Author: GiZano

backend-data-elaborator/README.md

@@ -1,50 +1,122 @@
-# backend-data-elaborator 🧠
+# Backend Data Elaborator 🧠
 
-This is the core API for the EDEAS system. It manages the database, validates incoming IoT data via cryptography, and serves the frontend application.
+Welcome to the **Backend Data Elaborator** module of the **Electro-Domestic Earthquake Alarm System**.
+This service is the "brain" of the operation: it receives real-time telemetry from the IoT devices, processes the data using seismic detection algorithms, and triggers alerts when necessary.
 
-## 🛠 Tech Stack
-* **Language:** Python 3.11
-* **Framework:** FastAPI
-* **Database:** PostgreSQL 15 + PostGIS (Spatial Extensions)
-* **ORM:** SQLAlchemy + GeoAlchemy2
-* **Security:** Python-ECDSA (NIST256p)
+## 📂 Project Structure
+
+The project is organized to keep the source code, configurations, and environment definitions clean and separated.
+
+```text
+backend-data-elaborator/
+├── api/
+│   ├── src/                # Main application source code (FastAPI/Flask)
+│   ├── tests/              # Unit and Integration tests
+│   ├── init-scripts/       # Database or service initialization scripts
+│   ├── Dockerfile          # Docker image definition
+│   ├── docker-compose.yml  # Local development orchestration
+│   ├── requirements.txt    # Python dependencies
+│   └── .env                # Environment variables (do not commit secrets!)
+└── README.md               # This file
+```
+
+## 🚀 Tech Stack
+
+* **Language:** Python 3.x
+* **Framework:** FastAPI / Flask (adjust based on your actual implementation)
 * **Containerization:** Docker & Docker Compose
+* **CI/CD:** GitHub Actions (Automated build & push to GHCR)
+
+---
+
+## 🛠️ Getting Started
+
+You can run this service either using Docker (Recommended 🐳) or manually with a Python virtual environment.
+
+### Prerequisites
+
+* **Docker** and **Docker Compose** installed.
+* **Python 3.10+** (only for manual execution).
+
+### Option 1: Run with Docker (The "Chill" Way)
+
+This is the preferred method as it ensures the environment is identical to production.
+
+1.  Navigate to the `api` directory:
+    ```bash
+    cd api
+    ```
+
+2.  Create your environment file (if missing):
+    ```bash
+    cp .env.example .env
+    # Edit .env with your specific configuration
+    ```
 
-## ⚙️ Configuration
+3.  Build and start the container:
+    ```bash
+    docker-compose up --build
+    ```
+
+The service should now be running (usually on `http://localhost:8000` or similar, check your compose config).
+
+### Option 2: Manual Execution
+
+If you need to debug locally without Docker:
 
-1.  Create a `.env` file in this directory based on the following template:
+1.  Navigate to the `api` directory:
+    ```bash
+    cd api
+    ```
+
+2.  Create and activate a virtual environment:
+    ```bash
+    python -m venv .venv
+    # Windows
+    .\.venv\Scripts\activate
+    # Linux/Mac
+    source .venv/bin/activate
+    ```
 
-    ```ini
-    # Database Credentials
-    POSTGRES_USER=developer
-    POSTGRES_PASSWORD=password
-    POSTGRES_DB=monitoraggio_db
+3.  Install dependencies:
+    ```bash
+    pip install -r requirements.txt
+    ```
 
-    # Connection String (Ensure host is 'postgres' for Docker networking)
-    DATABASE_URL=postgresql://developer:password@postgres:5432/monitoraggio_db
+4.  Run the application (example for generic app):
+    ```bash
+    # Command depends on your framework, e.g.:
+    uvicorn src.main:app --reload
+    # OR
+    python src/main.py
     ```
 
-2.  Ensure the `init-scripts/` folder contains the SQL script to enable PostGIS.
+---
 
-## 🐳 Running the Server
+## 🧪 Testing
 
-Run the application using Docker Compose:
+We believe in code quality. Here is how to run the test suite.
 
+**Using Docker:**
 ```bash
-# Build and Start
-docker-compose up -d --build
+docker-compose run backend pytest
+```
 
-# View Logs
-docker-compose logs -f
+**Manual:**
+```bash
+pytest tests/
 ```
 
-### Endpoints
-* **Swagger Documentation:** [http://localhost:8000/docs](http://localhost:8000/docs)
-* **pgAdmin (DB Interface):** [http://localhost:8080](http://localhost:8080) (User: `admin@example.com`, Pass: `admin`)
+## 🐳 Deployment
 
-## ⚠️ Troubleshooting
-* **"Type geometry does not exist":**
-    If the database was created before PostGIS was enabled, run:
-    ```bash
-    docker-compose exec postgres psql -U developer -d monitoraggio_db -c "CREATE EXTENSION IF NOT EXISTS postgis;"
-    ```
+This repository uses **GitHub Actions** for CI/CD.
+Every push to the `main` branch (involving this folder) triggers a workflow that:
+1.  Builds the Docker image using the context `./backend-data-elaborator/api`.
+2.  Pushes the image to **GitHub Container Registry (GHCR)**.
+
+## 🤝 Contribution
+
+1.  Create a feature branch from `main`.
+2.  Ensure your code follows the project's style guide.
+3.  Write tests for new features.
+4.  Open a Pull Request.