# othmaneabder2303/smartroute architecture

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

- Interactive diagram: https://gitdiagram.com/othmaneabder2303/smartroute
- Repository: https://github.com/othmaneabder2303/smartroute

## Overview

##### Project Type and Purpose
- SmartRoute is a full-stack, real-time intelligent route optimization platform built as an Nx monorepo.
- It consists of:
- A frontend (Angular 17) for map-based user interaction
- A backend (Spring Boot + PostgreSQL) for business logic, authentication, data persistence
- An AI module (Flask + Python) for route optimization and traffic/time prediction
- It integrates machine learning (XGBoost, Random Forest), graph algorithms (Dijkstra, A*), external APIs (OpenWeather, OpenStreetMap via OSMnx), and OAuth2 (Google, GitHub) to deliver traffic-aware routes in Marrakech.

##### File Structure Analysis
- Top-level monorepo governed by Nx (nx.json, tsconfig.base.json), with global configs (.editorconfig, .gitignore, .prettierrc).
- apps/data-generating: Python script (run_sql.py) for data ingestion or DB seeding.
- apps/ml-api: Flask service with model artifacts (xgboost_model.pkl), caching, Dockerfile, requirements.txt.
- apps/opt-backend: Spring Boot service (Maven wrapper, pom.xml) under src/main/java for controllers, services, repositories, security, OAuth2, JWT utils.
- apps/opt-frontend: Angular application (package.json, tsconfig.json) under src/ for components, services, environment, styling, routing, tests.
- A cache folder at root holds persisted HTTP responses (used by ml-api).
- CI pipeline in .github/workflows/ci.yml automates build/test.

##### README Insights
- Confirms three-layer architecture: Frontend, Backend, AI Module.
- Details key technologies and use cases: real-time route optimization, ML based traffic/time prediction, secure JWT/OAuth2, map rendering with Leaflet.
- Mentions external data sources (OpenWeatherAPI, Hugging Face, OpenStreetMap).

a. Main Components
- User’s Web Browser
- Frontend (Angular app on localhost:4200)
- Backend API (Spring Boot at :8080)
- AI Module (Flask at :5000)
- Database (PostgreSQL)
- External Services:
– OAuth2 Providers (Google, GitHub)
– OpenWeatherAPI
– OpenStreetMap (via OSMnx)
– Hugging Face (model storage)
- Data-Generating Script (one-time DB setup)
b. Relationships & Data Flows
1. User → Frontend: HTTP(S) requests for UI and map interactions
2. Frontend ↔ Backend:
- Authentication (OAuth2 redirects → backend → external provider → callback → JWT issued)
- API calls (route requests, user profile, history) with JWT in headers
3. Backend → AI Module: REST calls to compute optimal routes and predictions
4. AI Module → External APIs:
- Fetch weather data from OpenWeatherAPI
- Query street graphs from OpenStreetMap/OSMnx
- Optionally download models from Hugging Face
5. Backend ↔ Database: CRUD via Spring Data JPA (users, events, history, places)
c. Architectural Patterns & Principles
- Layered architecture: Presentation → Business → Data
- Monorepo with Nx workspace for code sharing and unified CI
- Micro-service style separation: independent apps (frontend, backend, AI)
- Security patterns: JWT authentication, OAuth2 flow, CSRF filter
- ML service abstraction: decouple heavy computation from core API
d. Key Technologies & Frameworks
- Angular, RxJS, Leaflet, Angular Material (frontend)
- Spring Boot, Spring Security, Spring Data JPA, JWT, OAuth2 (backend)
- Flask, XGBoost, Random Forest, OSMnx, Hugging Face, caching (AI module)
- PostgreSQL, Maven, Docker, Python 3.8+, Java 17, Node.js 16+

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    Browser["User's Web Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        AngularUI["Angular UI (localhost:4200)"]:::frontend
        ProjectConfig1["package.json"]:::frontend
        ProjectConfig2["tsconfig.json"]:::frontend
        MainTS["main.ts"]:::frontend
        IndexHTML["index.html"]:::frontend
        Routes["app.routes.ts"]:::frontend
        Environments["environments"]:::frontend
        Components["components"]:::frontend
        SharedServices["shared/services"]:::frontend
        StylesAssets["styles & assets"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Layer"
        SpringAPI["Spring Boot API (localhost:8080)"]:::backend
        MavenWrapper["mvnw"]:::backend
        POM["pom.xml"]:::backend
        MVNDir[".mvn"]:::backend
        MainAppClass["SmartRouteApplication.java"]:::backend
        Controllers["controller package"]:::backend
        Services["service package"]:::backend
        Repositories["repository package"]:::backend
        SecurityConfig["SecurityConfig.java"]:::backend
        OAuth2Dir["oauth2 package"]:::backend
        JwtUtils["JwtUtils.java"]:::backend
        Filter["filter package"]:::backend
        AppProperties["application.properties"]:::backend
    end

    %% ML Layer
    subgraph "AI Module (ML Service)"
        MLService["Flask ML Service (localhost:5000)"]:::ml
        ModelArtifact["xgboost_model.pkl"]:::ml
        Requirements["requirements.txt"]:::ml
        Dockerfile["Dockerfile"]:::ml
        CacheDir["cache directory"]:::ml
    end

    %% Data Layer
    subgraph "Data Layer"
        PostgreSQL["PostgreSQL DB"]:::db
    end

    %% Utility Script
    DataGenScript["Data-Generating Script"]:::utility

    %% External Systems
    OAuth2["OAuth2 Providers"]:::external
    OpenWeather["OpenWeather API"]:::external
    OpenStreetMap["OpenStreetMap (OSMnx)"]:::external
    HuggingFace["Hugging Face Model Store"]:::external

    %% CI and Monorepo Configs
    CIPipeline["CI Pipeline"]:::external
    NxConfig["nx.json"]:::external
    TSConfigBase["tsconfig.base.json"]:::external
    RootPackage["package.json (root)"]:::external
    Prettierrc[".prettierrc"]:::external
    Editorconfig[".editorconfig"]:::external

    %% Data Flows
    Browser -->|"HTTP/HTTPS"| AngularUI
    AngularUI -->|"REST API, JWT"| SpringAPI
    AngularUI -->|OAuth2 Redirect| OAuth2
    SpringAPI -->|"OAuth2 Flow"| OAuth2
    SpringAPI -->|"CRUD via JPA"| PostgreSQL
    SpringAPI -->|"REST call"| MLService
    MLService -->|"Fetch weather"| OpenWeather
    MLService -->|"Query map data"| OpenStreetMap
    MLService -->|"Download model"| HuggingFace
    DataGenScript -->|"DB seeding"| PostgreSQL

    %% Subgraph connections
    AngularUI --- ProjectConfig1
    AngularUI --- ProjectConfig2
    AngularUI --- MainTS
    AngularUI --- IndexHTML
    AngularUI --- Routes
    AngularUI --- Environments
    AngularUI --- Components
    AngularUI --- SharedServices
    AngularUI --- StylesAssets

    SpringAPI --- MavenWrapper
    SpringAPI --- POM
    SpringAPI --- MVNDir
    SpringAPI --- MainAppClass
    SpringAPI --- Controllers
    SpringAPI --- Services
    SpringAPI --- Repositories
    SpringAPI --- SecurityConfig
    SpringAPI --- OAuth2Dir
    SpringAPI --- JwtUtils
    SpringAPI --- Filter
    SpringAPI --- AppProperties

    MLService --- ModelArtifact
    MLService --- Requirements
    MLService --- Dockerfile
    MLService --- CacheDir

    %% CI and Configs
    CIPipeline --- NxConfig
    CIPipeline --- TSConfigBase
    CIPipeline --- RootPackage
    CIPipeline --- Prettierrc
    CIPipeline --- Editorconfig

    %% Click Events
    click DataGenScript "https://github.com/othmaneabder2303/smartroute/blob/main/apps/data-generating/run_sql.py"
    click MLService "https://github.com/othmaneabder2303/smartroute/blob/main/apps/ml-api/app.py"
    click ModelArtifact "https://github.com/othmaneabder2303/smartroute/blob/main/apps/ml-api/xgboost_model.pkl"
    click Requirements "https://github.com/othmaneabder2303/smartroute/blob/main/apps/ml-api/requirements.txt"
    click Dockerfile "https://github.com/othmaneabder2303/smartroute/tree/main/apps/ml-api/dockerfile"
    click CacheDir "https://github.com/othmaneabder2303/smartroute/tree/main/apps/ml-api/cache"

    click MavenWrapper "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/mvnw"
    click POM "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/pom.xml"
    click MVNDir "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/.mvn"
    click MainAppClass "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/src/main/java/ma/kech/opt/SmartRouteApplication.java"
    click Controllers "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/src/main/java/ma/kech/opt/controller"
    click Services "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/src/main/java/ma/kech/opt/service"
    click Repositories "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/src/main/java/ma/kech/opt/repository"
    click SecurityConfig "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/src/main/java/ma/kech/opt/config/SecurityConfig.java"
    click OAuth2Dir "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/src/main/java/ma/kech/opt/oauth2"
    click JwtUtils "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/src/main/java/ma/kech/opt/utils/JwtUtils.java"
    click Filter "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-backend/src/main/java/ma/kech/opt/filter"
    click AppProperties "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-backend/src/main/resources/application.properties"

    click ProjectConfig1 "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/package.json"
    click ProjectConfig2 "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/tsconfig.json"
    click MainTS "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/src/main.ts"
    click IndexHTML "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/src/index.html"
    click Routes "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/src/app/app.routes.ts"
    click Environments "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-frontend/src/environments"
    click Components "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-frontend/src/app/components"
    click SharedServices "https://github.com/othmaneabder2303/smartroute/tree/main/apps/opt-frontend/src/app/shared/services"
    click StylesAssets "https://github.com/othmaneabder2303/smartroute/blob/main/apps/opt-frontend/src/styles.scss"

    click CacheRoot "https://github.com/othmaneabder2303/smartroute/tree/main/cache/"
    click CIPipeline "https://github.com/othmaneabder2303/smartroute/blob/main/.github/workflows/ci.yml"
    click NxConfig "https://github.com/othmaneabder2303/smartroute/blob/main/nx.json"
    click TSConfigBase "https://github.com/othmaneabder2303/smartroute/blob/main/tsconfig.base.json"
    click RootPackage "https://github.com/othmaneabder2303/smartroute/blob/main/package.json"
    click Prettierrc "https://github.com/othmaneabder2303/smartroute/blob/main/.prettierrc"
    click Editorconfig "https://github.com/othmaneabder2303/smartroute/blob/main/.editorconfig"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef ml fill:#FFF3E0,stroke:#E65100,color:#E64A19
    classDef db fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161
    classDef utility fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
