[add] documentation for API, directory structure

docs/backend/api.md

@@ -1 +1,151 @@
 # API
+
+The API calls to PictoPy are done via HTTP requests since we are hosting our backend on a Flask server. Follow this [Link](https://www.postman.com/cryosat-explorer-62744145/workspace/pictopy/overview)
+to get example request and response.
+## Table of Contents
+1. [Albums](#albums)
+2. [Image](#image)
+3. [Face Recognition and Tagging](#face-recognition-and-tagging)
+
+## Albums
+
+We briefly discuss the endpoints related to albums, all of these fall under the `/albums` route
+
+### Create Album
+- **Endpoint**: `POST /albums/create-album`
+- **Description**: Creates a new album with the given name and optional description.
+- **Request Format**:
+  ```json
+  {
+    "name": "string",
+    "description": "string" (optional)
+  }
+  ```
+- **Response**: Message confirming album creation.
+
+### Delete Album
+- **Endpoint**: `DELETE /albums/delete-album`
+- **Description**: Deletes an existing album by name.
+- **Request Format**:
+  ```json
+  {
+    "name": "string"
+  }
+  ```
+- **Response**: Message confirming album deletion.
+
+### Add Multiple Images to Album
+- **Endpoint**: `POST /albums/add-multiple-to-album`
+- **Description**: Adds multiple images to an existing album.
+- **Request Format**:
+  ```json
+  {
+    "album_name": "string",
+    "paths": ["string", "string", ...]
+  }
+  ```
+- **Response**: Message confirming images were added to the album.
+
+### Remove Image from Album
+- **Endpoint**: `DELETE /albums/remove-from-album`
+- **Description**: Removes a single image from an album.
+- **Request Format**:
+  ```json
+  {
+    "album_name": "string",
+    "path": "string"
+  }
+  ```
+- **Response**: Message confirming image removal from the album.
+
+### View Album Photos
+- **Endpoint**: `GET /albums/view-album`
+- **Description**: Retrieves all photos in a specified album.
+- **Query Parameters**: `album_name` (string)
+- **Response**: JSON object containing album name and list of photos.
+
+### Edit Album Description
+- **Endpoint**: `PUT /albums/edit-album-description`
+- **Description**: Updates the description of an existing album.
+- **Request Format**:
+  ```json
+  {
+    "name": "string",
+    "description": "string"
+  }
+  ```
+- **Response**: Message confirming album description update.
+
+### View All Albums
+- **Endpoint**: `GET /albums/view-all`
+- **Description**: Retrieves a list of all albums.
+- **Response**: JSON object containing a list of all albums.
+
+## Image
+We briefly discuss the endpoints related to images, all of these fall under the `/images` route
+### Get All Images
+- **Endpoint**: `GET /images/all-images`
+- **Description**: Retrieves a list of all image files in the system.
+- **Response**: JSON object containing a list of image file paths.
+
+### Add Multiple Images
+- **Endpoint**: `POST /images/images`
+- **Description**: Adds multiple images to the system and processes them in the background.
+- **Request Format**:
+  ```json
+  {
+    "paths": ["string", "string", ...]
+  }
+  ```
+- **Response**: Message indicating that images are being processed.
+
+### Delete Image
+- **Endpoint**: `DELETE /images/delete-image`
+- **Description**: Deletes a single image from the system.
+- **Request Format**:
+  ```json
+  {
+    "path": "string"
+  }
+  ```
+- **Response**: Message confirming image deletion.
+
+### Get All Image Objects
+- **Endpoint**: `GET /images/all-image-objects`
+- **Description**: Retrieves all images and their associated object classes.
+- **Response**: JSON object mapping image paths to their object classes.
+
+### Get Class IDs
+- **Endpoint**: `GET /images/class-ids`
+- **Description**: Retrieves the object classes for a specific image.
+- **Query Parameters**: `path` (string) - full path to the image
+- **Response**: JSON object containing the classes detected in the image.
+
+### Add Folder
+- **Endpoint**: `POST /images/add-folder`
+- **Description**: Adds all images from a specified folder to the system and processes them in the background.
+- **Request Format**:
+  ```json
+  {
+    "folder_path": "string"
+  }
+  ```
+- **Response**: Message indicating the number of images being processed from the folder.
+
+## Face Recognition and Tagging
+We briefly discuss the endpoints related to face tagging and recognition, all of these fall under the `/tag` route
+### Face Matching
+- **Endpoint**: `GET /tag/match`
+- **Description**: Finds similar faces across all images in the database.
+- **Response**: JSON object containing pairs of similar images and their similarity scores.
+
+### Face Clusters
+- **Endpoint**: `GET /tag/clusters`
+- **Description**: Retrieves clusters of similar faces across all images.
+- **Response**: JSON object containing clusters of images with similar faces.
+
+### Related Images
+- **Endpoint**: `GET /tag/related-images`
+- **Description**: Finds images with faces related to the face in the given image.
+- **Query Parameters**: `path` (string) - full path to the image
+- **Response**: JSON object containing a list of related image paths.

docs/backend/directory-structure.md

@@ -0,0 +1,104 @@
+# Directory Structure
+
+The entry point for the backend is in `main.py`, which initializes the databases and handles the startup and shutdown for the FastAPI server.
+
+The code for the application mainly lies in the `app/` directory the heirarchy of which looks like this:
+
+```bash
+.
+├── main.py
+└── app/
+    ├── config/
+    ├── database/
+    ├── facecluster/
+    ├── facenet/
+    ├── models/
+    ├── routes/
+    ├── utils/
+    └── yolov8/
+
+```
+
+We will discuss what each of these directories do and the relevant files they contain
+
+## config
+
+Related to variables used accross the application.
+
+| Name   | Description |
+|-------------|-------------|
+| `settings.py`     | Contains configuration files for the application, mainly paths and parameters which are used across the application |
+
+
+## database
+
+This directory contains files related to database operations, including table creation, query handeling and some helper functions on the tables.
+These files are the places where most of the SQL queries are written. By default, on startup this directory is where the databases (`.db` files) is
+created.
+
+| Name           | Description |
+|----------------|-------------|
+| `albums.py`     | Handles operations related to photo albums, including creating, deleting, and managing albums and their contents. |
+| `faces.py`     | Manages face-related data, including storing and retrieving face embeddings for facial recognition. |
+| `images.py`      | Deals with image-related operations, such as storing image metadata, managing image IDs, and handling image classifications. |
+| `yolo_mapping.py`| Creates and manages mappings for YOLO object detection classes. |
+
+
+## facecluster
+This directory contains files related to face clustering functionality, which is used to group similar faces together across different images.
+
+| Name                 | Description |
+|----------------------|-------------|
+| `init_face_cluster.py` | Initializes and manages the face clustering system |
+| `facecluster.py`       | Implements the FaceCluster class, which handles the core face clustering logic |
+
+
+## facenet
+This directory contains files related to facial recognition functionality using FaceNet, a deep learning model for face embedding.
+
+| Name | Description |
+|------|-------------|
+| `facenet.py` | Implements face detection and embedding generation using FaceNet and YOLOv8 |
+| `preprocess.py` | Contains utility functions for image preprocessing and embedding manipulation |
+
+
+## models
+This directory contains pre-trained machine learning models used in the application.
+
+| Name | Description |
+|------|-------------|
+| `facenet.onnx` | Pre-trained FaceNet model for generating face embeddings |
+| `yolov8n-face.onnx` | YOLOv8 model trained specifically for face detection |
+| `yolov8n.onnx` | YOLOv8 model for general object detection |
+
+## routes
+This directory contains API route definitions for different functionalities of the application.
+
+| Name | Description |
+|------|-------------|
+| `albums.py` | Handles API routes for album-related operations (create, delete, add/remove photos, view albums) |
+| `facetagging.py` | Manages routes for face matching, clustering, and finding related images |
+| `images.py` | Deals with image-related operations (adding, deleting, retrieving images and their metadata) |
+
+
+
+## utils
+This directory contains utility functions and helper modules used across the application.
+
+| Name | Description |
+|------|-------------|
+| `classification.py` | Provides functions for image classification using YOLOv8 |
+| `metadata.py` | Extracts and processes metadata from image files |
+| `path_id_mapping.py` | Handles mappings between image paths and their database IDs |
+| `wrappers.py` | Contains decorator functions for validating album and image existence |
+
+
+
+## yolov8
+This directory contains implementations and utilities for the YOLOv8 object detection model.
+The code is taken from [This Repositry](https://github.com/ibaiGorordo/ONNX-YOLOv8-Object-Detection)
+
+| Name | Description |
+|------|-------------|
+| `utils.py` | Provides utility functions for YOLOv8, including NMS, IoU computation, and drawing detections |
+| `YOLOv8.py` | Implements the YOLOv8 class for object detection, including model initialization, inference, and post-processing |

docs/index.md

@@ -33,6 +33,11 @@ offering smart tagging capabilities for photos based on objects, faces, or scene
                     Database
                 </a>
             </li>
+            <li>
+                <a href="./backend/directory-structure">
+                    Directory Structure
+                </a>
+            </li>
             <li>
                 <a href="./backend/api">
                     API

mkdocs.yml

@@ -55,6 +55,7 @@ nav:
       - Architecture: overview/architecture.md
   - Backend:
       - Setup: backend/setup.md
+      - Directory Structure: backend/directory-structure.md
       - Database: backend/database.md
       - API: backend/api.md
       - Image Processing: backend/image-processing.md