# smart-ouassine/moroccoai-data-challenge architecture

> Architecture diagram of the GitHub repository smart-ouassine/moroccoai-data-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smart-ouassine/moroccoai-data-challenge
- Repository: https://github.com/smart-ouassine/moroccoai-data-challenge

## Overview

##### Project Type and Purpose
- This repository implements an end-to-end Automatic Number Plate Recognition (ANPR) system for Moroccan vehicles.
- It consists of two main deliverables:
- A backend REST API (FastAPI) that hosts two Detectron2-based object-detection models: one to locate license plates in images, and another to recognize (OCR) the individual characters on those plates.
- A frontend demo (Streamlit) that allows users to upload images or streams and view recognized plate strings.

##### File Structure
- Top-level artifacts:
- docker-compose.yml — orchestrates two containerized services (fastapi, streamlit)
- fastapi/ — source code, model-loading logic, endpoints, model weight directories
- streamlit/ — interactive UI code and its Dockerfile
- weights/ — model artifacts for local training or inference
- docs/ — Jupyter notebooks and presentation slides (offline training/demo materials)
- Architectural clues:
- Two distinct Dockerfiles → two services (micro-services)
- fastapi/main.py defines HTTP endpoints: /plate_detector, /plate_ocr
- streamlit/streamlit.py interacts with those endpoints over HTTP
- model artifacts (Detectron2 Faster R-CNN) kept alongside code for versioning

##### README for Additional Insights
- The README confirms the two-stage detection approach:
a. Detect and crop the license plate region.
b. Crop passed to a second model for character detection.
- Transfer learning via pretrained COCO Faster R-CNN backbones

##### Main Components & Their Interactions
a. Frontend (Streamlit UI service)
- Runs as its own Docker container
- Presents an interface for image upload or camera stream
- Makes HTTPS/HTTP calls to the FastAPI backend
b. API Gateway / Backend (FastAPI service)
- Hosts two endpoints: plate detection & OCR
- Loads the corresponding Detectron2 model weights at startup
- Receives images, runs inference, applies post-processing, returns JSON responses
c. Model Storage & Weights
- weights/ or fastapi/weights/ folders store .pth, checkpoint, metrics
- Mounted into containers via Docker volumes
d. Data Flow
1. User uploads image via Streamlit
2. Streamlit POSTs raw image to FastAPI’s /plate_detector
4. Streamlit POSTs cropped plate to /plate_ocr
5. API returns ordered character string
6. Streamlit displays final plate string
e. (Optional) Training & Experimentation Notebooks
- docs/*.ipynb used offline in Colab or local for model improvements

##### Architectural Patterns & Design Principles
- Micro-service separation: UI vs. API vs. data (weights)
- Containerization for reproducibility (Docker + docker-compose)
- Two-stage pipeline pattern (pipeline of inference stages)
- Transfer learning via Detectron2 (reusable pretrained modules)
- Stateless services: each inference request is independent

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    StreamlitService["Streamlit Service"]:::service
    FastAPIService["FastAPI Service"]:::service
    PlateDetector["Faster-RCNN Plate Detector"]:::model
    PlateOCR["Faster-RCNN Character Detector"]:::model
    PostProcess["Post-Processing Module"]:::model
    WeightsShared[(Shared Weights Volume)]:::storage
    DockerCompose["docker-compose.yml"]:::orchestrator

    subgraph "Docker Compose"
        direction TB
        StreamlitService
        FastAPIService
        WeightsShared
    end

    DockerCompose -.-> StreamlitService
    DockerCompose -.-> FastAPIService

    User -->|"image upload"| StreamlitService
    StreamlitService -->|"POST /plate_detector"| FastAPIService
    FastAPIService -->|"inference call"| PlateDetector
    PlateDetector -->|"bboxes"| FastAPIService
    FastAPIService -->|"response JSON"| StreamlitService
    StreamlitService -->|"POST /plate_ocr"| FastAPIService
    FastAPIService -->|"inference call"| PlateOCR
    PlateOCR -->|"char detections"| PostProcess
    PostProcess -->|"ordered string"| FastAPIService
    FastAPIService -->|"response JSON"| StreamlitService
    StreamlitService -->|"display plate"| User

    subgraph "Streamlit Service Files"
        direction TB
        StreamlitDir["streamlit/"]:::storage
        SS_Docker["streamlit/Dockerfile"]:::storage
        SS_Req["streamlit/requirements.txt"]:::storage
        SS_App["streamlit/streamlit.py"]:::storage
    end

    subgraph "FastAPI Service Files"
        direction TB
        FastAPIDir["fastapi/"]:::storage
        FA_Docker["fastapi/Dockerfile"]:::storage
        FA_Req["fastapi/requirements.txt"]:::storage
        FA_Main["fastapi/main.py"]:::storage
        FA_Det["fastapi/plate_detector.py"]:::storage
        FA_Ocr["fastapi/plate_ocr.py"]:::storage
    end

    subgraph "Plate Detector Weights"
        direction TB
        PD_WeightsDir["fastapi/weights/plate_detector/"]:::storage
    end

    subgraph "Plate OCR Weights"
        direction TB
        PO_WeightsDir["fastapi/weights/plate_ocr/"]:::storage
    end

    SharedWeightsDir["weights/"]:::storage
    DocsDir["docs/"]:::storage

    click StreamlitDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/streamlit/"
    click SS_Docker "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/streamlit/Dockerfile"
    click SS_Req "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/streamlit/requirements.txt"
    click SS_App "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/streamlit/streamlit.py"
    click FastAPIDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/fastapi/"
    click FA_Docker "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/fastapi/Dockerfile"
    click FA_Req "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/fastapi/requirements.txt"
    click FA_Main "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/fastapi/main.py"
    click FA_Det "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/fastapi/plate_detector.py"
    click FA_Ocr "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/fastapi/plate_ocr.py"
    click PD_WeightsDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/fastapi/weights/plate_detector/"
    click PO_WeightsDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/fastapi/weights/plate_ocr/"
    click SharedWeightsDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/weights/"
    click DockerCompose "https://github.com/smart-ouassine/moroccoai-data-challenge/blob/master/docker-compose.yml"
    click DocsDir "https://github.com/smart-ouassine/moroccoai-data-challenge/tree/master/docs/"

    classDef service fill:#bbdefb,stroke:#2196f3,stroke-width:1px
    classDef model fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px
    classDef storage fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef orchestrator stroke-dasharray:5 5,stroke:#757575
    classDef user fill:#ef9a9a,stroke:#c62828,stroke-width:1px
```
