AhmedFatthy1040 · AhmedFatthy1040 · Jun 8, 2025
diff --git a/docs/DFD_Level_0_Context.md b/docs/DFD_Level_0_Context.md
@@ -0,0 +1,75 @@
+# SAT-Annotator - Level 0 Context Diagram
+
+This is the highest level view of the SAT-Annotator system, showing the system as a single process with external entities.
+
+## Context Diagram (Level 0)
+
+```mermaid
+graph TB
+    %% External Entities
+    User[👤 User/Annotator<br/>Researcher/GIS Specialist]
+    FileSystem[📁 File System<br/>Local Storage]
+    SAMModel[🤖 SAM AI Model<br/>Segment Anything]
+
+    %% Main System
+    System[🛰️ SAT-Annotator System<br/>Satellite Image Annotation Tool]
+
+    %% Data Flows    User -->|1.1 Upload Satellite Images<br/>JPG/PNG/TIFF/GeoTIFF| System
+    User -->|1.2 Point Prompts<br/>Click Coordinates| System
+    User -->|1.3 Manual Annotations<br/>Polygon Drawing| System
+    User -->|1.4 Export Requests<br/>JSON Format| System
+
+    System -->|2.1 Processed Images<br/>Metadata & Thumbnails| User
+    System -->|2.2 AI Segmentation Results<br/>Polygon Boundaries| User
+    System -->|2.3 Annotation Files<br/>JSON/Shapefile| User
+    System -->|2.4 Session Status<br/>Upload Progress| User
+      System -->|3.1 Store Image Files<br/>Original & Processed| FileSystem
+    System -->|3.2 Store Annotation Data<br/>JSON Files| FileSystem
+    FileSystem -->|3.3 Retrieve Images<br/>For Processing| System
+    FileSystem -->|3.4 Retrieve Annotations<br/>For Export| System
+
+    System -->|4.1 Image Data<br/>Pixel Arrays| SAMModel
+    System -->|4.2 Point Prompts<br/>X,Y Coordinates| SAMModel
+    SAMModel -->|4.3 Segmentation Masks<br/>Binary Masks| System
+    SAMModel -->|4.4 Confidence Scores<br/>Quality Metrics| System
+
+    %% Styling
+    classDef userStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    classDef systemStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:3px
+    classDef externalStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
+
+    class User userStyle
+    class System systemStyle
+    class FileSystem,SAMModel externalStyle
+```
+
+## Data Flow Description
+
+### External Entities:
+- **User/Annotator**: Researchers, GIS specialists, or remote sensing analysts who upload and annotate satellite images
+- **File System**: Local or network storage for image files and annotation data
+- **SAM AI Model**: Segment Anything Model providing AI-powered segmentation capabilities
+
+### Data Flows:
+1. **Input Flows (User → System)**:
+   - Upload satellite images in various formats
+   - Provide point prompts for AI segmentation
+   - Create manual annotations
+   - Request data exports
+
+2. **Output Flows (System → User)**:
+   - Display processed images with metadata
+   - Show AI-generated segmentation results
+   - Provide downloadable annotation files
+   - Display real-time session status
+
+3. **Storage Flows (System ↔ File System)**:
+   - Store and retrieve image files
+   - Persist annotation data
+
+4. **AI Processing Flows (System ↔ SAM Model)**:
+   - Send image data and prompts to AI model
+   - Receive segmentation masks and confidence scores
+
+## Purpose
+This context diagram provides a high-level overview of the SAT-Annotator system's boundaries and its interactions with external entities, showing the main data flows without internal system details.
diff --git a/docs/DFD_Level_1_Overview.md b/docs/DFD_Level_1_Overview.md
@@ -0,0 +1,143 @@
+# SAT-Annotator - Level 1 Data Flow Diagram
+
+This diagram breaks down the SAT-Annotator system into its major functional processes.
+
+## Level 1 DFD
+
+```mermaid
+graph TB
+    %% External Entities
+    User[👤 User/Annotator]
+    FileSystem[📁 File System]
+    SAMModel[🤖 SAM AI Model]
+      %% Processes
+    P1["1.0 🔐 Session Management"]
+    P2["2.0 📤 Image Upload & Processing"]
+    P3["3.0 🤖 AI Segmentation"]
+    P4["4.0 ✏️ Manual Annotation"]
+    P5["5.0 📊 Data Export"]
+    P6["6.0 🌐 Web Interface"]
+
+    %% Data Stores
+    DS1[("D1 Session Store")]
+    DS2[("D2 Image Cache")]
+
+    %% User Interactions
+    User -->|Login/Session Request| P1
+    User -->|Upload Images| P2
+    User -->|Point Prompts| P3
+    User -->|Manual Polygons| P4
+    User -->|Export Request| P5
+    User -->|Web Requests| P6
+
+    P1 -->|Session Data| User
+    P2 -->|Upload Status| User
+    P3 -->|Segmentation Results| User
+    P4 -->|Annotation Confirmation| User
+    P5 -->|Download Files| User
+    P6 -->|Web Interface| User
+
+    %% Process Interactions
+    P1 -->|Session ID| DS1
+    DS1 -->|Session Data| P1
+
+    P2 -->|Image Metadata| DS1
+    P2 -->|Image Files| FileSystem
+    FileSystem -->|Stored Images| P2
+
+    P3 -->|Image Path| DS1
+    DS1 -->|Image Info| P3
+    P3 -->|Embeddings| DS2
+    DS2 -->|Cached Data| P3
+    P3 -->|Image Data| SAMModel
+    SAMModel -->|Segmentation Masks| P3
+    P3 -->|Annotations| DS1
+
+    P4 -->|Manual Annotations| DS1
+    DS1 -->|Existing Annotations| P4
+
+    P5 -->|Annotation Data| DS1
+    DS1 -->|Export Data| P5
+    P5 -->|Annotation Files| FileSystem
+
+    P6 -->|Static Files| FileSystem
+    P6 -->|API Calls| P2
+    P6 -->|API Calls| P3
+    P6 -->|API Calls| P4
+    P6 -->|API Calls| P5
+
+    %% Styling
+    classDef userStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    classDef processStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
+    classDef datastoreStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
+    classDef externalStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
+
+    class User userStyle
+    class P1,P2,P3,P4,P5,P6 processStyle
+    class DS1,DS2 datastoreStyle
+    class FileSystem,SAMModel externalStyle
+```
+
+## Process Descriptions
+
+### 1.0 Session Management
+- **Purpose**: Handle user session lifecycle, generate session IDs, manage session cookies
+- **Inputs**: User login/session requests
+- **Outputs**: Session data, session cookies
+- **Storage**: Session metadata in D1 (Session Store)
+
+### 2.0 Image Upload & Processing
+- **Purpose**: Receive, validate, process, and store satellite images
+- **Inputs**: Image files from users
+- **Outputs**: Upload confirmation, image metadata
+- **Processing**: File validation, metadata extraction, thumbnail generation
+- **Storage**: Image files in File System, metadata in D1
+
+### 3.0 AI Segmentation
+- **Purpose**: Perform automated segmentation using SAM model
+- **Inputs**: Point prompts from users, image data
+- **Outputs**: Segmentation polygons, confidence scores
+- **Processing**: Image embedding, prompt processing, mask generation
+- **Storage**: Embeddings in D2 (Image Cache), results in D1
+
+### 4.0 Manual Annotation
+- **Purpose**: Handle user-drawn annotations and polygon editing
+- **Inputs**: Manual polygon data from users
+- **Outputs**: Annotation confirmation, updated annotations
+- **Storage**: Annotation data in D1
+
+### 5.0 Data Export
+- **Purpose**: Generate and provide downloadable annotation files
+- **Inputs**: Export requests, annotation data
+- **Outputs**: JSON files, shapefiles
+- **Processing**: Format conversion, file generation
+- **Storage**: Export files in File System
+
+### 6.0 Web Interface
+- **Purpose**: Serve frontend interface and handle HTTP requests
+- **Inputs**: Web requests, API calls
+- **Outputs**: HTML pages, JSON responses
+- **Processing**: Static file serving, API routing
+
+## Data Stores
+
+### D1 - Session Store (In-Memory)
+- **Contents**: 
+  - Session metadata (session_id, timestamps)
+  - Image metadata (filename, resolution, upload time)
+  - Annotation data (polygons, labels, auto/manual flags)
+- **Access**: All processes except AI model
+
+### D2 - Image Cache (In-Memory)
+- **Contents**:
+  - SAM model embeddings
+  - Processed image data
+  - Segmentation masks
+- **Access**: Primarily by AI Segmentation process
+
+## Key Data Flows
+
+1. **Image Processing Pipeline**: User → P2 → FileSystem → P3 → SAMModel → P3 → User
+2. **Session Flow**: User → P1 → D1 → (All Processes) → User
+3. **Annotation Flow**: User → P3/P4 → D1 → P5 → FileSystem → User
+4. **Web Interface Flow**: User → P6 → (API Processes) → P6 → User
diff --git a/docs/DFD_Level_2_AI_Segmentation.md b/docs/DFD_Level_2_AI_Segmentation.md
@@ -0,0 +1,170 @@
+# SAT-Annotator - Level 2 Data Flow Diagram
+
+This diagram provides detailed breakdown of the AI Segmentation process (Process 3.0), which is the most complex part of the system.
+
+## Level 2 DFD - AI Segmentation Process (3.0)
+
+```mermaid
+graph TB    %% External to this process
+    User["👤 User"]
+    DS1[("D1 Session Store")]
+    DS2[("D2 Image Cache")]
+    SAMModel["🤖 SAM AI Model"]
+
+    %% Sub-processes of 3.0 AI Segmentation
+    P31["3.1 🔍 Image Loading & Validation"]
+    P32["3.2 🧠 Image Embedding Generation"]
+    P33["3.3 📍 Point Prompt Processing"]
+    P34["3.4 🎯 Mask Prediction & Generation"]
+    P35["3.5 🔗 Polygon Conversion & Optimization"]
+    P36["3.6 💾 Result Storage & Caching"]
+      %% Input flows
+    User -->|"Point Coordinates (x,y)"| P33
+    DS1 -->|"Image Metadata & File Path"| P31
+
+    %% Process flow
+    P31 -->|"Validated Image Array Data"| P32
+    P32 -->|"Image Embeddings"| P34
+    P33 -->|"Processed Points Labels"| P34
+    P34 -->|"Raw Masks Confidence Scores"| P35
+    P35 -->|"Polygon Coordinates Simplified Shapes"| P36
+
+    %% Cache interactions
+    P32 -->|"Store Embeddings"| DS2
+    DS2 -->|"Cached Embeddings (if available)"| P32
+    P36 -->|"Cache Results"| DS2
+
+    %% External model interaction
+    P32 -->|"Image Data"| SAMModel
+    SAMModel -->|"Feature Embeddings"| P32
+    P34 -->|"Embeddings + Prompts"| SAMModel
+    SAMModel -->|"Segmentation Masks"| P34
+
+    %% Storage and output
+    P36 -->|"Annotation Metadata"| DS1
+    P36 -->|"Segmentation Results Polygon Data"| User
+
+    %% Error flows
+    P31 -->|"Validation Errors"| User
+    P32 -->|"Model Load Errors"| User
+    P34 -->|"Segmentation Errors"| User
+
+    %% Styling
+    classDef userStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
+    classDef processStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
+    classDef datastoreStyle fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
+    classDef externalStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    classDef errorStyle fill:#ffebee,stroke:#c62828,stroke-width:2px,stroke-dasharray: 5 5
+
+    class User userStyle
+    class P31,P32,P33,P34,P35,P36 processStyle
+    class DS1,DS2 datastoreStyle
+    class SAMModel externalStyle
+```
+
+## Sub-Process Descriptions
+
+### 3.1 Image Loading & Validation
+- **Purpose**: Load and validate images for AI processing
+- **Inputs**: 
+  - Image metadata and file path from Session Store (D1)
+- **Processing**:
+  - Validate image file exists and is readable
+  - Load image data into memory
+  - Convert to required format (RGB arrays)
+  - Validate image dimensions and format
+- **Outputs**: 
+  - Validated image array data → Process 3.2
+  - Validation errors → User (if any)
+
+### 3.2 Image Embedding Generation
+- **Purpose**: Generate or retrieve cached image embeddings for SAM model
+- **Inputs**: 
+  - Validated image data from Process 3.1
+  - Cached embeddings from Image Cache (D2) if available
+- **Processing**:
+  - Check cache for existing embeddings
+  - If not cached, send image to SAM model for embedding
+  - Store new embeddings in cache
+- **Outputs**: 
+  - Image embeddings → Process 3.4
+  - Model load errors → User (if any)
+- **External**: SAM Model for embedding generation
+
+### 3.3 Point Prompt Processing
+- **Purpose**: Process and validate user-provided point prompts
+- **Inputs**: 
+  - Point coordinates (x, y) from User
+- **Processing**:
+  - Validate coordinates are within image bounds
+  - Convert web coordinates to image coordinates
+  - Assign point labels (foreground/background)
+  - Format prompts for SAM model
+- **Outputs**: 
+  - Processed points and labels → Process 3.4
+
+### 3.4 Mask Prediction & Generation
+- **Purpose**: Generate segmentation masks using SAM model
+- **Inputs**: 
+  - Image embeddings from Process 3.2
+  - Processed points and labels from Process 3.3
+- **Processing**:
+  - Combine embeddings with point prompts
+  - Send to SAM model for mask prediction
+  - Receive multiple mask candidates with confidence scores
+  - Select best mask based on confidence
+- **Outputs**: 
+  - Raw segmentation masks and confidence scores → Process 3.5
+  - Segmentation errors → User (if any)
+- **External**: SAM Model for mask prediction
+
+### 3.5 Polygon Conversion & Optimization
+- **Purpose**: Convert binary masks to polygon coordinates
+- **Inputs**: 
+  - Raw segmentation masks and confidence scores from Process 3.4
+- **Processing**:
+  - Find contours in binary mask
+  - Convert contours to polygon coordinates
+  - Simplify polygons (reduce vertex count)
+  - Filter out small artifacts
+  - Convert coordinates back to web format
+- **Outputs**: 
+  - Polygon coordinates and simplified shapes → Process 3.6
+
+### 3.6 Result Storage & Caching
+- **Purpose**: Store results and manage caching
+- **Inputs**: 
+  - Polygon coordinates from Process 3.5
+- **Processing**:
+  - Generate annotation metadata
+  - Cache results for potential reuse
+  - Prepare response format
+- **Outputs**: 
+  - Annotation metadata → Session Store (D1)
+  - Cached results → Image Cache (D2)
+  - Final segmentation results → User
+
+## Data Flow Details
+
+### Critical Paths:
+1. **First-time segmentation**: 3.1 → 3.2 → SAM → 3.4 → SAM → 3.5 → 3.6
+2. **Cached segmentation**: 3.1 → 3.2 (cache hit) → 3.4 → SAM → 3.5 → 3.6
+3. **Error handling**: Each process → User (for respective error types)
+
+### Performance Optimizations:
+- **Embedding Cache**: Process 3.2 caches expensive image embeddings
+- **Result Cache**: Process 3.6 caches final results
+- **Async Processing**: Multiple point prompts can be processed in parallel
+
+### Error Handling:
+- Image validation errors (corrupt files, unsupported formats)
+- Model loading errors (missing SAM checkpoint, CUDA issues)
+- Segmentation errors (invalid prompts, model failures)
+
+## Technical Implementation Notes
+
+This Level 2 DFD corresponds to the following code components:
+- **Process 3.1-3.6**: `app/utils/sam_model.py` - SAMSegmenter class
+- **Process 3.3**: `app/routers/session_segmentation.py` - Point prompt handling
+- **Cache D2**: SAMSegmenter.cache dictionary
+- **Session Store D1**: `app/storage/session_store.py` - SessionStore class