# tinbalon3/gps_map architecture

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

- Interactive diagram: https://gitdiagram.com/tinbalon3/gps_map
- Repository: https://github.com/tinbalon3/gps_map

## Overview

##### Project Type and Purpose
- This is a full-stack application focused on providing routing and location search functionality via integration with Azure Maps.
- The backend provides a set of API endpoints (e.g., /route, /search, /health) implemented in Python (using uvicorn as the ASGI server), and the frontend is a client-side Angular application (located in the gps-maps directory) that consumes these endpoints.
- The project integrates with Azure Maps for authentication and route calculations, clearly outlined in the README.

##### File Structure Insights
- The project is divided into two main components:
- The “backend” folder: Contains Python files such as main.py, azure_maps.py, config.py, and schemas.py, forming the core API service logic. Also includes an environment configuration file (.env.example) used for sensitive credentials.
- The “gps-maps” folder: Contains all Angular-specific configurations (angular.json, package.json) and source code under src/app. In particular, the azure-map component and several Angular services (azure-maps.service.ts, location.service.ts, etc.) clearly indicate that the frontend is responsible for interacting with the backend and displaying map-based content.
- There are additional configuration and dependency management files (e.g., package.json files, tsconfig files) that support build tasks and environment configuration.

##### Key Components
a. Backend API Service:
- Components: main.py (entry point), azure_maps.py (integration with Azure Maps), config.py (configuration management), and schemas.py (data validation/serialization).
- Functionality: Handling client requests, performing routing calculations, searching locations via Azure Maps, and managing health checks.
- External Dependencies: Azure Maps (for credentials, route calculations, and point-of-interest searches). Also, environment settings stored in .env.

b. Frontend Angular Application:
- Components: Angular’s main app (app.component), azure-map component (for map display), and supporting Angular services (azure-maps.service, location.service, routing.service, search.service) that call the backend endpoints.
- Functionality: Providing a user interface for users to interact with the routing and search features, making HTTP requests to the backend API.

c. External Services:
- Azure Maps: This external service is a key part of the architecture as the backend uses it to process route calculations and search queries.
- Optionally, include any underlying infrastructure or deployment concerns if applicable (e.g., hosting details for the Angular app and backend server).

##### Relationships and Interactions
- The Angular frontend sends HTTP requests (GET, POST) to the Python backend via defined endpoints.
- The backend processes these routes – for routing and searching – and, when needed, makes outbound API calls to Azure Maps.
- Responses (or errors) flow back from the backend to the frontend.
- Authentication and security steps (e.g., usage of credentials from .env, Azure Maps authentication).
- Directional relationship from the frontend to the backend and from the backend to the Azure Maps service.

##### Architectural Patterns and Design Principles
- Clearly separate concerns by having a dedicated backend API and a standalone frontend client.
- Configuration management (with environment configuration files and dependency management).
- Use of external, third-party services (Azure Maps) that are decoupled from the internal application logic.
- Error handling practices as specified in the README (HTTP error codes and JSON error responses).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend API Service Subgraph
    subgraph "Backend API Service"
        B1["main.py (API Entry)"]
        B2["azure_maps.py (Azure Maps Integration)"]
        B3["config.py (Configuration)"]
        B4["schemas.py (Data Schemas)"]
        B5[".env.example (Environment Config)"]
    end

    %% Angular Frontend Subgraph
    subgraph "Angular Frontend"
        F1["angular.json (Angular Configuration)"]
        F2["package.json (Frontend Dependencies)"]
        subgraph "Angular UI"
            F3["App Component"]
            F4["Azure Map Component (UI)"]
        end
        subgraph "Angular Services"
            F5["Azure Maps Service"]
            F6["Location Service"]
            F7["Routing Service"]
            F8["Search Service"]
        end
    end

    %% External Service
    E1["Azure Maps External Service"]

    %% Relationships within Backend
    B1 -->|"uses"| B2
    B1 -->|"uses"| B3
    B1 -->|"validates"| B4
    B1 -->|"reads"| B5

    %% Backend to External Service
    B2 -->|"callsAPIs"| E1

    %% Angular UI to Angular Services
    F4 -->|"callsService"| F5

    %% Angular Frontend to Backend
    F3 -->|"HTTPcalls"| B1
    F5 -->|"HTTPcalls"| B1
    F6 -->|"HTTPcalls"| B1
    F7 -->|"HTTPcalls"| B1
    F8 -->|"HTTPcalls"| B1

    %% Click Events for Backend Components
    click B1 "https://github.com/tinbalon3/gps_map/blob/main/backend/main.py"
    click B2 "https://github.com/tinbalon3/gps_map/blob/main/backend/azure_maps.py"
    click B3 "https://github.com/tinbalon3/gps_map/blob/main/backend/config.py"
    click B4 "https://github.com/tinbalon3/gps_map/blob/main/backend/schemas.py"
    click B5 "https://github.com/tinbalon3/gps_map/blob/main/backend/.env.example"

    %% Click Events for Frontend Components
    click F1 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/angular.json"
    click F2 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/package.json"
    click F3 "https://github.com/tinbalon3/gps_map/tree/main/gps-maps/src/app"
    click F4 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/src/app/components/azure-map/azure-map.component.ts"
    click F5 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/src/app/services/azure-maps.service.ts"
    click F6 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/src/app/services/location.service.ts"
    click F7 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/src/app/services/routing.service.ts"
    click F8 "https://github.com/tinbalon3/gps_map/blob/main/gps-maps/src/app/services/search.service.ts"

    %% Styles
    class B1,B2,B3,B4,B5 backend
    class F1,F2,F3,F4,F5,F6,F7,F8 frontend
    class E1 external

    %% Class Definitions with Colors
    classDef backend fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef external fill:#ccffcc,stroke:#336633,stroke-width:2px;
```
