🛡️ SmartGuard

Open-Source IoT Sigurnosni Sistem

Vaša kuća. Vaša kontrola. Vaši podaci.

---

📖 O projektu

SmartGuard je self-hosted IoT sigurnosno rješenje za pametne domove koje kombinuje:

• 📷 ESP32-CAM edge uređaje za lokalno snimanje i baferovanje videa
• ⚙️ .NET Backend (REST + SignalR) za real-time komunikaciju i poslovnu logiku
• 📱 Flutter mobilnu/desktop aplikaciju za upravljanje i praćenje

Osnovna filozofija projekta počiva na tri stuba:

🔒 Privatnost	💾 Minimalni Storage	⚡ Real-Time
Podaci ostaju kod korisnika — bez cloud-a trećih strana	Event-driven snimanje + ring buffer	Live stream + instant push notifikacije

---

🔗 Brzi linkovi

Komponenta	Opis	Link
🖥️ Backend	.NET mikroservisi, REST API, SignalR	Backend/README.md
📡 ESP32-CAM	Firmware i Wi-Fi provisioning	ESP32/README.md
📱 Mobilna	Flutter Android aplikacija	Mobile/README.md
🖱️ Desktop	Flutter admin panel	Desktop/README.md

---

❗ Problem koji rješavamo

Klasična "pametna" kućna sigurnost često donosi ozbiljne nedostatke:

• 💸 Mjesečne pretplate za cloud storage
• 🕵️ Nejasne politike obrade lica i snimaka
• 🔐 Vendor lock-in — ako servis prestane s radom, nestaje i sigurnost
• 📼 Nepotrebno 24/7 snimanje videa koje troši prostor i propusnost

SmartGuard pristup je suprotan: lokalna kontrola + minimalni podaci + otvoreni kod.

---

✨ Ključne karakteristike

🎥 Live Stream bez latencije

ESP32 šalje JPEG frame-ove backendu, koji ih putem SignalR-a prosljeđuje klijentima u realnom vremenu.

📅 Event-driven snimanje

Snimci i arhive nastaju samo kada se desi relevantan događaj — detektovan pokret, detektovano lice (slika + embedding) ili aktiviran alarm — umjesto stalnog snimanja.

🔁 Ring buffer na SD kartici

Uređaj čuva ograničen broj "normalnih" snimaka na SD kartici, dok event snimke tretira kao prioritetne klipove.

👤 Detekcija lica i poznate osobe

Događaji detekcije lica se šalju backendu kao slika + embedding vektor (128 float vrijednosti). Backend zatim radi matching prema postojećim poznatim osobama i povezuje događaj s odgovarajućom osobom, uz mogućnost selektivnih notifikacija po osobi.

🧠 Prepoznavanje identiteta na backendu

Prepoznavanje (matching) se ne radi na ESP32 uređaju. Uređaj šalje podatke, a backend:

• sačuva događaj i objavi poruku na RabbitMQ
• VectorMatching servis izračuna cosine similarity prema KnownPerson centroid embeddingima
• API obradi rezultat, upiše score, poveže osobu i ažurira centroid embedding kroz vrijeme

🔔 Selektivne notifikacije

Push/email obavijesti samo za tipove događaja i osobe koje vi odaberete.

🔑 Sigurnost i autorizacija

JWT autentifikacija, role-based autorizacija (Admin / HomeOwner / Viewer), audit trail i soft delete.

📈 Skalabilnost

Podrška za više ESP32 uređaja uz asinhroničnu obradu putem message brokera.

---

🏗️ Pregled arhitekture

SmartGuard je dizajniran kao skup komponenti s jasnom podjelom između real-time streaminga, poslovne logike i zahtjevnih pozadinskih operacija.

[ OVDJE UMETNUTI DIJAGRAM ARHITEKTURE ] (npr. dijagram koji prikazuje ESP32 → REST API → SignalR → Flutter klijenti)

Pregled komponenti

Komponenta	Uloga
📡 ESP32-CAM (Edge)	Lokalno snimanje i ring buffer; upload frame-ova; detekcija lica + ekstrakcija embeddinga; Wi-Fi provisioning
🖥️ REST API (.NET)	Auth/AuthZ; CRUD; SignalR hubovi; ingest face eventa; objavljuje poruke workerima; obrada rezultata matchinga
🧠 VectorMatching Worker (.NET)	Matching identiteta (cosine similarity nad embeddingima) preko gRPC + objava rezultata na RabbitMQ
📬 Notification Worker (.NET)	Konzumira poruke → šalje email + push (FCM)
📦 Archiving Worker (.NET)	Preuzima MJPEG snimke s uređaja; čuva na serveru; ažurira statuse snimaka
🗄️ SQL Server	Centralna relaciona baza (domenski entiteti + referentne tabele)
🐇 RabbitMQ	Asinhroni tokovi poruka (notifikacije i arhiviranje)
📱 Flutter Mobile	Korisnička aplikacija — live prikaz, snimci, alarmi, poznate osobe, notifikacije
🖱️ Flutter Desktop	Admin panel — upravljanje sistemom, izvještaji, audit logovi

---

🔄 Tokovi podataka

📡 Live Stream

ESP32  →  REST API (upload frame-a)  →  SignalR Hub  →  Mobilni / Desktop klijent

🎬 Event snimak

ESP32 najavljuje upload  →  API objavljuje poruku  →  Archiving Worker preuzima snimak
  →  Čuva na storage-u  →  API ažurira status snimka

🔔 Notifikacije

API objavljuje poruku  →  Notification Worker šalje Email / Push
  →  SignalR in-app notifikacije

👤 Prepoznavanje lica (backend matching)

ESP32 (slika + embedding)  →  POST /FaceDetectionEvents/detect  →  RabbitMQ (IVectorMatchRequestedEvent)
  →  VectorMatching Worker (cosine similarity + threshold)  →  RabbitMQ (IVectorMatchCompletedEvent)
  →  API Consumer (poveže osobu + score + centroid update)  →  alarmi / notifikacije  →  klijenti

---

💡 Inovativnost

🧩 Karakteristika	Opis
🔀 Hibridni Edge + Server	Obrada je podijeljena između uređaja (edge) i backenda s jasnim granicama privatnosti
📉 Minimalni podaci po defaultu	Snimaju se samo relevantni događaji; ring buffer služi kao sigurnosna mreža
🔓 Open-Source i auditabilan	Svako može pregledati kompletan tok podataka i sigurnosne odluke (auth, audit, state machine)
📡 Real-Time bez cloud lock-ina	SignalR push tokovi — bez posredničkih servisa ili pretplata

---

🌍 Utjecaj na okruženje

• 🏠 Privatnost kao default — podaci ostaju u lokalnoj infrastrukturi (kuća ili firma), a ne kod trećih strana
• 💰 Budžetski pristupačno — ESP32-CAM uređaji omogućavaju jeftino skaliranje (više kamera bez povećanja pretplate)
• 🏢 Primjenjivo u praksi — kuće, mali biznisi (prodavnice/restorani), apartmanski kompleksi (više korisnika, više nivoa pristupa)

---

🛠️ Tehnička realizacija

📦 Gotova rješenja (building blocks)

Etablirani alati i frameworki korišteni kao osnova:

• Hardver: ESP32-CAM + SD kartica
• Frameworki: .NET (net10.0), Flutter, SignalR, Entity Framework Core
• Infrastruktura: SQL Server, RabbitMQ (message broker)

✍️ Autorski rad tima

Sve ispod je izradio SmartGuard tim:

• 🗃️ Modeliranje domene i baze — entiteti, relacije, soft delete, audit
• ⚙️ Backend poslovna logika — state machine za alarme/snimke, ownership provjere, API key autentifikacija za uređaje
• 📡 Real-Time tokovi — SignalR hubovi + provjera prava pristupa na stream
• 🔧 Worker servisi — queue potrošači, retry logika, slanje email/push, arhiviranje i struktura storage-a
• 📱 Flutter klijenti — UI, navigacija, auth tokovi, filteri/paginacija, master-detail ekrani, PDF izvještaji (desktop)
• 📡 ESP32 firmware tok — provisioning, slanje događaja, lokalni buffer i retry sinhronizacije

---

📁 Struktura repozitorija

SmartGuard/
├── 📂 Backend/     # .NET API + mikroservisi + domenski model
├── 📂 ESP32/       # Firmware za ESP32-CAM + provisioning
├── 📂 Mobile/      # Flutter Android aplikacija
├── 📂 Desktop/     # Flutter desktop admin aplikacija
└── 📂 Docs/        # Dokumentacija za prijavu i takmičenje

Detaljni opisi i upute za pokretanje svake komponente nalaze se u README.md fajlovima iz sekcije Brzi linkovi iznad.

---

🚀 Pokretanje sistema (end-to-end)

✅ Preduvjeti

Za kompletan demo potrebno je:

Zahtjev	Napomena
🗄️ SQL Server	Centralna baza podataka
🐇 RabbitMQ	Queue za worker servise
🔴 Redis (opcionalno)	Cache, ovisno o konfiguraciji API-ja
🔷 .NET SDK net10.0	Za lokalno pokretanje servisa
🐦 Flutter SDK	Za pokretanje klijenata

---

🐳 Opcija A: Docker (Preporučeno)

Docker Compose konfiguracija se nalazi na:

Backend/SecureGuard/docker-compose.yml

Pokretanjem Compose-a pokreću se:

Servis	Opis
smartguard.api	REST API + SignalR
smartguard.archive.microservice	Archiving worker
smartguard.notifications.microservice	Notification worker
sqlserver	SQL Server 2022
rabbitmq	RabbitMQ + management UI
redis	Redis cache

⚠️ Potreban je .env fajl sa sljedećim varijablama: SQLSERVER_SA_PASSWORD, RABBITMQ_USER, RABBITMQ_PASSWORD, REDIS_PASSWORD

Pokretanje sistema iz root-a repozitorija:

docker compose -f Backend/SecureGuard/docker-compose.yml --env-file Backend/SecureGuard/.env up --build

Za mapiranje portova (npr. localhost:5000, localhost:5001), pogledajte Backend/README.md.

---

💻 Opcija B: Lokalno (bez Dockera)

Korak 1 — Pokretanje infrastrukture:

# Pokreni SQL Server i kreiraj bazu
# Naziv baze: SmartGuardDb
# (connection string se nalazi u backend konfiguraciji)

# Pokreni RabbitMQ (default: guest/guest)
# Pokreni Redis (opcionalno)

Korak 2 — Pokretanje .NET servisa (detalji u Backend/README.md):

• REST API
• Archiving Worker
• Notifications Worker

Korak 3 — Pokretanje Flutter klijenata:

• 📱 Mobilna → Mobile/README.md
• 🖱️ Desktop → Desktop/README.md

Korak 4 — Flash i provisioning ESP32-a → ESP32/README.md

---

📸 Screenshot-ovi

Mobilna aplikacija	Desktop Admin	Live Stream prikaz
[ UMETNUTI SCREENSHOT MOBILNE ]	[ UMETNUTI SCREENSHOT DESKTOPA ]	[ UMETNUTI SCREENSHOT LIVE PRIKAZA ]

---

👥 Tim

Ime	ID
👨‍💻 Dušan Perić	IB230222
👨‍💻 Marko Milidragović	IB230221

---