`README.md`

# GeoControl API

## Installation and Setup

### Prerequisites

Before starting, ensure you have the following installed on your system:

- **Node.js** (Recomended version: latest LTS)
- **npm** (Node Package Manager, included with Node.js)

### Installing Dependencies

Run the following command to install all required dependencies:

```sh
npm install

Running the Application

Starting the API Server

To start the server, run:

npm start

By default, the server runs on

http://localhost:5000

Development Mode (Hot Reloading)

For development with hot reloading, use:

npm run dev

This mode restarts the server automatically when code changes.

Debugging

For debugging with hot reloading enabled:

On Windows:
```
npm run debug-win
```
On Unix/Linux:
```
npm run debug-unix
```

Creating the Root User

To create the SQLite database file and att to it an admin user with credentials root:rootpassword, execute:

npm run create-root

Windows Execution Policy Issue

If you encounter an execution policy error like:

+ CategoryInfo : SecurityError: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess

Run the following command before executing scripts:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

API Documentation

The API follows an OpenAPI specification, with the definition stored in:

doc/swagger_v1.yaml

Once the application is running, the Swagger UI is available at:

**http://localhost:5000/api/v1/doc**

The Swagger documentation provides a complete definition and description of the system, including object schemas, detailed endpoint specifications with input and output parameters, error definitions, and a brief functional overview of each API operation. It serves as the authorative reference for understanding how the system is designed to function.

Project Structure

The project follows a modular architecture, ensuring maintainability, separation of concerns, and scalability. Each module is structured to serve a specific purpose.

`/coverage`

Contains the HTML and summary reports generated from the last test run. This folder is excluded from version control and automatically generated or updated at each test execution.

`/data`

Contains the SQLite database file. This folder is excluded from version control.

`/doc`

Contains the OpenAPI specification file (swagger) used to define the application external interface.

`/docker`

Contains everything needed to containerize the application and run it with Docker Compose.
To run the following commands, Docker Desktop is required (On Linux, you can install Docker Engine and CLI from your distribution's package manager too)
/backend
- Contains the Dockerfile used to build the backend Node.js application. When the container starts, it first runs the create-root script that waits for the database to become available and creates the default admin user if it does not already exist. After that, it launches the actual backend server.
Build the backend image manually (from the project root):
```
docker build -t geocontrol-backend -f docker/backend/Dockerfile .
```
Run the container after building the image:
```
docker run -d --name geocontrol-backend -p 5000:5000 geocontrol-backend
```
/db
- Contains the init.sql script used to initialize the MySQL database. The script creates the database, user, and password based on the environment variables defined in the docker-compose.yml file. This initialization is executed only on the first startup, if the database volume is empty.
docker-compose.yml
- Defines a three-service setup:
  - The frontend
  - The backend server
  - The MySQL database**
- The frontend image is pulled from a public DockerHub
- All configuration parameters (e.g. ports, database name, credentials) are centralized and reused across all services.
- The backend container uses an internal script to wait for the database to be ready before attempting any connection.
** Run the Docker Compose (from /docker folder):**
```
docker-compose up
```
Run the Docker Compose with automatic rebuild of the backend image:
```
docker-compose up --build
```
Stop and remove containers:
```
docker-compose down
```
Stop, remove containers and reset volumes (reset the DB):
```
docker-compose down -v
```

`/logs`

Contains all the log files generated by the application:
- error.log: contains only the errors logged by the application
- combined.log: contains all the logs generated by the application
This folder is excluded from version control

`/scripts`

Contains the set-up scripts for the application.

`/src` - Main source folder

Contains all the following subfolders with the source code.

/config
- Contains global configuration files.
/controllers
- Handle the request processing logic and call the appropriate services.
/database
- Manages database connection and initialization.
/middlewares
- Contains Express middleware for authentication, validation, and error handling.
/models
- /dao: Respresents database entities using TypeORM.
- /dto: Contains Data Transfer Objects (DTOs) generated automatically from OpenAPI.
- /errors: Contains all the custom error classes.
/Repositories
- Implements data access logic to interact with the database.
/routes
- Defines API endpoints and maps them to controllers.
/services
- Contains business logic and helper functions.
/utils.ts
- Provides utility functions used across the project.

`/test` - Test folder

Contains all unit tests and integration tests for the project. The tests are written using Jest, a popular JavaScript testing framework.
/e2e
- Contains end-to-end tests.
- Includes *an example test of a full stack execution flow of one of the users endpoints, using the actual in-memory datasource.
/integration
- Contains integration tests.
- Includes two example tests, one for the userControlled integration with mapperService and the second one for the integration of userRoutes with its middleware layer.
/postman_collection
- Contains a complete Postman test suite that can be used to manually test the API endpoints defined in Swagger. Download Postman to import the test collection (GeoControl API Full Test Suite.postman_collection.json) and run the requests against the API.
/setup
- Contains the configuration for the in-memory SQLite test datasource used during automated tests.
/unit
- Contains the unit tests
- Includes two example tests for the UserRepository class: one using full mocking, and one using the actual in-memory datasource which will be used by the final end-to-end tests.

Path Aliases

To avoid relative imports, TypeScript path aliases are defined in tsconfig.json>

		"paths": {
			"@models/*": ["models/*"],
			"@errors/*": ["models/errors/*"],
			"@dao/*": ["models/dao/*"],
			"@dto/*": ["models/dto/*"],
			"@repositories/*": ["repositories/*"],
			"@services/*": ["services/*"],
			"@routes/*": ["routes/*"],
			"@controllers/*": ["controllers/*"],
			"@middlewares/*": ["middlewares/*"],
			"@database": ["database/connection.ts"],
			"@config": ["config/config.ts"],
			"@utils": ["utils.ts"],
			"@app": ["app.ts"],
			"@test/*": ["../test/*"]
		}

This allows importing modules like:

import { UserRepository } from "@repositories/UserRepository";

instead of using relative paths like:

import { UserRepository } from "../repositories/UserRepository";

API Versioning

All API endpoints include /v1/ in their URL paths (e.g., /api/v1/users).

This approact allows for backward compatibility when introducing breaking changes in the future. If a newer version of an endpoint requires different input parameters or returns a different response structure, a new version (e.g., /api/v2/users) can be created while keeping the old version operational. This prevents service disruptions for existing clients that depend on previous API versions.


## Punto di ingresso

Il **README.md** è il riferimento da consultare per primo: descrive prerequisiti, comandi e struttura del progetto. È quindi il “manuale d’uso” che sostituisce le spiegazioni frammentarie del prof.

## Installazione delle dipendenze

1. Verificare di avere **Node ≥ LTS** e **npm**.
2. Eseguire `npm install` per scaricare tutte le dipendenze definite nel progetto - operazione da ripetere anche se pensiamo di aver già installato qualcosa, perché il pacchetto fornito contiene tutte le librerie necessarie.

## Avvio del backend

- **Modalità standard**: `npm start` avvia il server su <http://localhost:5000>.
- **Modalità sviluppo con hot-reload**: `npm run dev` ricarica il codice a ogni salvataggio, evitando riavvii manuali.
- **Debug con hot-reload**:
    - Windows → `npm run debug-win`
    - Unix → `npm run debug-unix`
        
        Il prof insiste che questi script sono già configurati: basta lanciarli, senza modifiche.
        

## Primo accesso: creazione utente amministratore

Per effettuare chiamate autenticate serve un utente. Il comando `npm run create-root` popola il database (SQLite di default) con l’utente `root : rootpassword` (**password lunga ≥ 5 caratteri**, per rispettare la validazione dell’entità `User`).

## Architettura del progetto

Il repository segue una **struttura modulare**:

- `/src` - codice applicativo suddiviso in **config**, **controllers**, **models (DAO/DTO/errors)**, **repositories**, **services**, **routes**, **middlewares** e **utils**.
- `/test` - suite Jest con unit, integration, e2e e una collezione Postman completa.
- Cartelle di servizio: `/coverage` (report test), `/data` (SQLite), `/logs` (file di log), `/docker` (containerizzazione), `/doc` (OpenAPI).
- **Path aliases** (definiti in `tsconfig.json`) eliminano i percorsi relativi, migliorando leggibilità e refactoring.

## Comandi utili (recap)

README.md