# abdulrazakzakieh/person-finder architecture

> Architecture diagram of the GitHub repository abdulrazakzakieh/person-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdulrazakzakieh/person-finder
- Repository: https://github.com/abdulrazakzakieh/person-finder

## Overview

##### Project Type & Purpose
- This is a full-stack mobile-client/server application.
- The Flutter-based mobile app (Android, iOS, Web, desktop) serves as the client UI.
- A Python/Flask backend hosts two ML models (YOLOv8-Face for detection, FaceNet for verification) and exposes REST endpoints.

##### File Structure
- person_finder/… – Flutter project with platform folders (android/, ios/, linux/, macos/, web/, windows/) and lib/ where main.dart, Dart APIs (TargetPageAPI.dart, PersonImageUpload.dart) live.
- Server/ – Python Flask application: app.py defines two endpoints (`/upload-person-image`, `/search`), requirements.txt, and the YOLOv8 face-detection weights (yolov8n-face.pt).

##### Extract Key Architectural Insights from README
- Client uploads “target” image → server computes & stores FaceNet embedding.
- Models run on the cloud or local server; mobile communicates over HTTP (optionally through ngrok for tunneling).

##### Main Components & Their Relationships
a. Components:
- Mobile Client (Flutter UI & Networking)
- REST API Gateway (Flask app)
- Face Detection Module (YOLOv8-Face in PyTorch)
- Face Verification Module (FaceNet embedding in PyTorch)
- Embedding Store (in-memory or persistent store)
- Network (HTTPS / ngrok tunnel)
b. Interactions/Data Flow:
1. User selects “target” image → Client HTTP POST → `/upload-person-image` →
REST API computes FaceNet embedding → stores embedding.
2. User selects “search” image → Client HTTP POST → `/search` →
REST API loads YOLOv8 to detect face bboxes → for each bbox crops face → runs FaceNet → compares embeddings to stored target → picks best match above threshold → returns bbox JSON.
c. Architectural Patterns & Principles:
- Client-Server (RESTful) separation
- Modular ML pipeline (detection → verification)
- Stateless API (except stored embedding)
- Single-responsibility services: detection and verification are distinct modules
d. Key Technologies & Libraries:
- Flutter 3.13.0 (Dart)
- HTTP client (Dart’s http or dio)
- Flask (Python)
- PyTorch (YOLOv8, FaceNet)
- ngrok (for local testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Mobile Client"
        root["person_finder/"]:::client
        main["main.dart"]:::client
        api["TargetPageAPI.dart"]:::client
        upload["PersonImageUpload.dart"]:::client
        pubspec["pubspec.yaml"]:::client
    end

    subgraph "Network & Tunnel"
        ngrok["ngrok Tunnel"]:::server
    end

    subgraph "Server"
        apiGW["Flask API Gateway (app.py)"]:::server
        deps["requirements.txt"]:::server
        weights["yolov8n-face.pt"]:::server
        readme["README.md"]:::server
        detector(["YOLOv8 Face Detector"]):::ml
        embedder(["FaceNet Embedder"]):::ml
        store[(Embedding Store)]:::datastore
    end

    root --> main
    main --> api
    main --> upload

    upload -->|"POST /upload-person-image (target)"| ngrok
    upload -->|"POST /search (image)"| ngrok

    ngrok -->|"tunnel request"| apiGW

    apiGW -->|"invoke FaceNet"| embedder
    embedder -->|"store embedding"| store
    store -->|"ack response"| apiGW

    apiGW -->|"invoke YOLOv8"| detector
    detector -->|"crop faces"| embedder
    embedder -->|"compare embeddings"| store
    store -->|"return best match"| apiGW

    apiGW -->|"JSON bbox response"| ngrok
    ngrok -->|"deliver bbox JSON"| upload

    click root "https://github.com/abdulrazakzakieh/person-finder/tree/main/Mobile Application/person_finder/"
    click main "https://github.com/abdulrazakzakieh/person-finder/blob/main/Mobile Application/person_finder/lib/main.dart"
    click api "https://github.com/abdulrazakzakieh/person-finder/blob/main/Mobile Application/person_finder/lib/TargetPageAPI.dart"
    click upload "https://github.com/abdulrazakzakieh/person-finder/blob/main/Mobile Application/person_finder/lib/PersonImageUpload.dart"
    click pubspec "https://github.com/abdulrazakzakieh/person-finder/blob/main/Mobile Application/person_finder/pubspec.yaml"
    click apiGW "https://github.com/abdulrazakzakieh/person-finder/blob/main/Server/app.py"
    click deps "https://github.com/abdulrazakzakieh/person-finder/blob/main/Server/requirements.txt"
    click weights "https://github.com/abdulrazakzakieh/person-finder/blob/main/Server/yolov8n-face.pt"
    click readme "https://github.com/abdulrazakzakieh/person-finder/blob/main/Server/README.md"
    click store "https://github.com/abdulrazakzakieh/person-finder/blob/main/Server/app.py"

    classDef client fill:#add8e6,stroke:#000
    classDef server fill:#90ee90,stroke:#000
    classDef ml fill:#ffa500,stroke:#000,stroke-width:2px
    classDef datastore fill:#ffe4b5,stroke:#000,stroke-dasharray: 5 5
```
