# tushar-surti/building-detection-app architecture

> Architecture diagram of the GitHub repository tushar-surti/building-detection-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tushar-surti/building-detection-app
- Repository: https://github.com/tushar-surti/building-detection-app

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Flask for detecting buildings in satellite/aerial images.
- The front end is a lightweight HTML/CSS/JavaScript interface; the back end handles image uploads, invokes a PyTorch DeepLab V3+ segmentation model, post-processes the output, and returns results.

##### File Structure Analysis
- Root files:
- app.py – Flask routes (controllers) and HTTP API endpoints (`/`, `/upload`, `/about`, `/health`).
- model.py – Model-loading and inference logic.
- Dockerfile, render.yaml – Containerization and deployment configurations.
- requirements.txt – Python dependencies.
- Directories:
- models/ – Pretrained model weights and metadata.
- templates/ – Jinja2 HTML templates (views).
- static/ – Client assets (JavaScript, CSS) and runtime file storage:
– uploads/ for incoming user images
– results/ for generated masks and overlays

##### README Insights
- Technology Stack: Flask, PyTorch/TorchVision, OpenCV, Pillow, NumPy, vanilla JS.
- Workflow steps: preprocessing → model inference (DeepLab V3+ with ASPP) → postprocessing (threshold & overlay) → visualization & statistics.
- API spec provided, sample response schema, and performance metrics.

##### Main Components
a. User Browser (UI Layer)
- Upload form, drag & drop, result display pages (index.html, about.html)
b. Flask Backend
- HTTP server (app.py)
- API endpoints
- Controller logic for routing, invoking model.py
c. Model Inference Pipeline
- Preprocessing module (resize, normalize)
- DeepLab V3+ model (PyTorch)
- Postprocessing module (threshold, mask generation, overlay)
- Statistics computation
d. File Storage
- Static/uploads for input
- Static/results for output
- models/ folder for weights
e. Optional Infrastructure
- Docker container (Dockerfile, .dockerignore)
- Deployment config (render.yaml)

##### Relationships and Data Flows
- Browser → HTTP POST /upload → Flask app → preprocess → model inference → postprocess → save results → HTTP JSON response → browser renders results.
- The health check endpoint monitors backend status.
- Template rendering for GET `/` and `/about` serve static HTML.
- Docker container encapsulates the entire back end + model environment.

##### Architectural Patterns & Design Principles
- MVC-inspired:
- Model: model.py + pretrained weights
- View: templates/ + static assets
- Controller: app.py routes
- Separation of concerns: UI, API, ML logic, and storage are distinct.
- Stateless HTTP handling; persistent storage on disk for images.
- Containerization for reproducibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["User Browser"]:::ui
        Index["index.html"]:::ui
        About["about.html"]:::ui
        Assets["static/ (CSS, JS)"]:::ui
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Flask["Flask API Server\n(app.py)\nEndpoints: /, /upload, /about, /health"]:::backend
        UploadEP["/upload Endpoint"]:::backend
        HealthEP["/health Endpoint"]:::backend
    end

    %% Inference Engine
    subgraph "Inference Engine"
        direction TB
        Preprocess["Preprocessing Module\n(resize, normalize)"]:::ml
        DeepLab["DeepLab V3+ Model\n(PyTorch)"]:::ml
        Postprocess["Postprocessing Module\n(threshold, overlay)"]:::ml
        Stats["Statistics Computation"]:::ml
        ModelScript["model.py"]:::ml
        Weights["models/"]:::ml
    end

    %% Storage Layer
    subgraph "File Storage"
        direction TB
        Uploads["static/uploads/"]:::storage
        Results["static/results/"]:::storage
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        DockerIgnore[".dockerignore"]:::infra
        RenderYaml["render.yaml"]:::infra
        Requirements["requirements.txt"]:::infra
    end

    %% Data Flows
    Browser -->|"GET /"| Flask
    Flask -->|"render index.html"| Index
    Browser -->|"GET /about"| Flask
    Flask -->|"render about.html"| About
    Browser -->|"loads CSS/JS"| Assets

    Browser -->|"multipart/form-data POST /upload"| UploadEP
    UploadEP -->|"save file"| Uploads
    UploadEP -->|"invoke model.py"| ModelScript
    ModelScript -->|"load weights"| Weights
    ModelScript -->|"call preprocessing()"| Preprocess
    Preprocess -->|"tensor image"| DeepLab
    DeepLab -->|"raw mask"| Postprocess
    Postprocess -->|"mask & overlay"| Results
    Postprocess -->|"compute stats"| Stats
    Results -->|"file paths"| UploadEP
    Stats -->|"stats data"| UploadEP
    UploadEP -->|"JSON response"| Browser

    Browser -->|"GET /health"| HealthEP
    HealthEP -->|"status JSON"| Browser

    %% Containerization Relationship
    DockerfileNode -.-> Flask
    DockerfileNode -.-> ModelScript
    DockerfileNode -.-> Weights
    DockerfileNode -.-> Uploads
    DockerfileNode -.-> Results
    DockerfileNode -.-> Requirements
    RenderYaml -.-> Flask

    %% Click Events
    click Index "https://github.com/tushar-surti/building-detection-app/blob/main/templates/index.html"
    click About "https://github.com/tushar-surti/building-detection-app/blob/main/templates/about.html"
    click Assets "https://github.com/tushar-surti/building-detection-app/tree/main/static/"
    click Flask "https://github.com/tushar-surti/building-detection-app/blob/main/app.py"
    click ModelScript "https://github.com/tushar-surti/building-detection-app/blob/main/model.py"
    click Weights "https://github.com/tushar-surti/building-detection-app/tree/main/models/"
    click Uploads "https://github.com/tushar-surti/building-detection-app/tree/main/static/uploads/"
    click Results "https://github.com/tushar-surti/building-detection-app/tree/main/static/results/"
    click DockerfileNode "https://github.com/tushar-surti/building-detection-app/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/tushar-surti/building-detection-app/blob/main/.dockerignore"
    click RenderYaml "https://github.com/tushar-surti/building-detection-app/blob/main/render.yaml"
    click Requirements "https://github.com/tushar-surti/building-detection-app/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#D6F5D6,stroke:#28A745,color:#28A745;
    classDef ml fill:#FFE5B4,stroke:#E18F00,color:#E18F00;
    classDef storage fill:#E2E2E2,stroke:#6C757D,color:#6C757D;
    classDef infra fill:#F4D9FF,stroke:#6F42C1,color:#6F42C1;
```
