🏗️ Esempio: System Architecture Design

Estratto dall'analisi tecnica del progetto Errantia

Progetto: Errantia - Piattaforma per oggetti erranti con NFC
Documento: Analisi Tecnica (ANALISI_TECNICA.md)
Versione: 1.0
Data: 31 Dicembre 2024
Gestito con: MdExplorer + Git

1. Stack Tecnologico

Panoramica delle tecnologie selezionate per ogni componente del sistema, con le motivazioni architetturali alla base di ogni scelta.

Componente Tecnologia Motivazione
Frontend Angular 17 (Standalone) SPA moderna, SSR ready, componenti standalone
Backend Node.js + Express Ecosistema npm, performance I/O async, TypeScript ready
Database PostgreSQL 16 + PostGIS Supporto geospaziale nativo, JSONB, performance
Auth JWT + bcrypt Stateless, scalabile, standard industriale
Maps Leaflet.js Open source, leggero, personalizzabile
NFC Web NFC API + URL fallback Compatibilità universale tramite URL

2. Architettura di Deploy

Diagramma a tre livelli che mostra la separazione tra frontend, backend e database con i rispettivi moduli interni.

┌─────────────────────────────────────────────────┐ │ BROWSER │ │ Angular 17 SPA (PWA) │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Auth │ │ Artisan │ │ Public Landing │ │ │ │ Module │ │Dashboard │ │ (NFC Wizard) │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────┘ │ REST API (HTTPS) ▼ ┌─────────────────────────────────────────────────┐ │ NODE.JS + EXPRESS │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Auth │ │ Objects │ │ Sightings │ │ │ │ Routes │ │ Routes │ │ Routes │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ JWT │ │ Upload │ │ Geocoding │ │ │ │Middleware│ │Middleware │ │ Service │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────┘ │ SQL + PostGIS ▼ ┌─────────────────────────────────────────────────┐ │ POSTGRESQL 16 + PostGIS │ │ ┌──────┐ ┌────────┐ ┌───────┐ ┌────────────┐ │ │ │users │ │artisan │ │objects│ │ sightings │ │ │ │ │ │profiles│ │ │ │(+ geometry)│ │ │ └──────┘ └────────┘ └───────┘ └────────────┘ │ └─────────────────────────────────────────────────┘

3. Schema Database

Le tabelle core del sistema, progettate per supportare il flusso degli oggetti erranti dalla creazione alla tracciatura degli avvistamenti.

Tabella Colonne Principali Note
users id (UUID), email, password_hash, role, status, created_at Utenti del sistema (artisan, traveler, admin)
artisan_profiles id, user_id (FK), business_name, description, vat_number Profilo artigiano collegato a user
objects id, artisan_id (FK), unique_code, name, message, type, status Oggetti erranti creati dagli artigiani
sightings id, object_id (FK), location (GEOMETRY), location_name, created_at Avvistamenti con coordinate PostGIS
followers id, user_id (FK), object_id (FK), created_at Relazione di following tra utenti e oggetti

4. API Endpoints Summary

Riepilogo degli endpoint REST principali del sistema, con indicazione del metodo HTTP, dell'autenticazione richiesta e della funzione svolta.

Metodo Endpoint Auth Descrizione
POST /api/v1/auth/register No Registrazione artigiano
POST /api/v1/auth/login No Login e ottenimento JWT
GET /api/v1/auth/me Sì Profilo utente corrente
GET /api/v1/artisans/objects Sì Lista oggetti dell'artigiano
POST /api/v1/artisans/objects Sì Crea nuovo oggetto errante
GET /api/v1/objects/:code No Info pubblica oggetto (landing NFC)
POST /api/v1/objects/:code/sightings No Registra avvistamento
GET /api/v1/objects/:code/sightings No Lista avvistamenti oggetto

5. Diagramma Architettura (PlantUML)

Diagramma dei componenti del sistema scritto in PlantUML, direttamente integrato nel documento Markdown e renderizzato da MdExplorer.

PlantUML - Component Diagram 
@startuml
skinparam componentStyle rectangle

package "Frontend - Angular 17" {
  [Auth Module] as FE_AUTH
  [Artisan Dashboard] as FE_DASH
  [Object Management] as FE_OBJ
  [Public Landing] as FE_LAND
  [Sighting Wizard] as FE_SIGHT
  [Map Component] as FE_MAP
}

package "Backend - Node.js + Express" {
  [Auth Controller] as BE_AUTH
  [Objects Controller] as BE_OBJ
  [Sightings Controller] as BE_SIGHT
  [JWT Middleware] as BE_JWT
  [Geocoding Service] as BE_GEO
}

package "Database - PostgreSQL" {
  [Users & Profiles] as DB_USER
  [Objects] as DB_OBJ
  [Sightings + PostGIS] as DB_SIGHT
}

FE_AUTH --> BE_AUTH : POST /auth/login
FE_DASH --> BE_OBJ : GET /artisans/objects
FE_OBJ --> BE_OBJ : POST /artisans/objects
FE_LAND --> BE_OBJ : GET /objects/:code
FE_SIGHT --> BE_SIGHT : POST /objects/:code/sightings
FE_MAP --> BE_SIGHT : GET /objects/:code/sightings

BE_AUTH --> DB_USER
BE_OBJ --> DB_OBJ
BE_SIGHT --> DB_SIGHT
BE_SIGHT --> BE_GEO
@enduml

6. Benefici dello Spec Driven Development

Questo documento di architettura tecnica rappresenta il cuore progettuale del sistema, versionato e mantenuto insieme al codice sorgente:

← Torna al Case Study