# gaesty/biketrack architecture

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

- Interactive diagram: https://gitdiagram.com/gaesty/biketrack
- Repository: https://github.com/gaesty/biketrack

## Overview

##### Project type and purpose
- BikeTrack is a full-stack, cross-platform monitoring and security system for motorcycles, combining
an embedded IoT device (LilyGO A7670E), a cloud proxy service, a Supabase backend, and a Flutter mobile/web/desktop client.
- Purpose: collect telemetry (GPS, accelerometer, battery), detect events (theft, fall), store and serve data, notify users in real time.

##### Main components
a. IoT Firmware
– Arduino code (CodeFonctionnel/*.ino, utilities.h) running on an ESP32 module with 4G, GPS, MPU9250 IMU.
– Responsibilities: sensor initialization, data collection, 4G HTTPS POST to Proxy, SMS emergency.
b. Proxy Cloud
– Node.js/Express server (Proxy/proxy.js) hosted on Google Cloud.
– Responsibilities: receive compact JSON from device, transform to Supabase schema, forward via Supabase REST API, handle errors.
c. Backend / Database
– Supabase (PostgreSQL + Auth).
– Tables: users, sensor_data.
– Supabase Auth for sign-in/up, session management.
d. Mobile & Web Client
– Flutter app (lib/, android/, ios/, web/, linux/, macos/, windows/).
– UI screens (home, history, alerts, safety, settings, login, signup).
– Services layer (password_service, password_service_impl_*.dart) uses supabase_flutter for auth and data queries.
– Features: real-time map (flutter_map + OpenStreetMap), push notifications, historical route display, settings management.
e. External services
– OpenStreetMap tile server for maps.
– Supabase realtime channels or REST API for live updates.

##### Component interactions and data flows
- IoT Device → Proxy Cloud: HTTPS POST compact JSON payload
- Proxy Cloud → Supabase: REST API call to insert transformed data into sensor_data table
- Flutter Client → Supabase:
– Auth flows (sign-up, sign-in via supabase_flutter)
– Query sensor_data for history and real-time updates
– Subscribe to real-time events or poll for new alert records
- Flutter Client → OpenStreetMap: fetch map tiles
- (Optional) Proxy Cloud or Supabase → SMS/Push notifications: trigger on threshold events

##### Architectural patterns and design principles
- Separation of concerns:
– Embedded firmware only handles hardware and network transmission
– Proxy service isolates device-specific payload formats from backend schema
– Backend handles data storage, auth, security
– Client handles presentation, user interaction, notifications
- Client-server pattern with RESTful interactions
- Event-driven notifications (real-time updates via Supabase realtime or push)
- Layered architecture: hardware layer, transport layer (proxy), data layer (database), presentation layer (Flutter)

##### Detailed capture of essential elements
- Firmware modules: GPS, IMU, battery monitor, GSM module
- Proxy’s transformation logic (compact → extended schema)
- UI screens grouping (map view, history view, alerts view) to show client module boundaries

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Hardware Layer"
        IoT["IoT Device (ESP32 + GPS + IMU)"]:::hardware
    end

    subgraph "Transport Layer"
        Proxy["Proxy Service\n(Node.js/Express)"]:::compute
    end

    subgraph "Data Layer"
        DB["Supabase\n(PostgreSQL + Auth)"]:::database
    end

    subgraph "Presentation Layer"
        subgraph "Flutter Client"
            Entry["lib/main.dart"]:::client
            Models["lib/models/moto_status.dart"]:::client

            subgraph "Services Layer"
                PS["lib/services/password_service.dart"]:::client
                PSI["lib/services/password_service_impl.dart"]:::client
                PSM["lib/services/password_service_impl_mobile.dart"]:::client
                PSW["lib/services/password_service_impl_web.dart"]:::client
            end

            subgraph "UI Screens"
                Home["lib/ui/screens/home_screen.dart"]:::client
                History["lib/ui/screens/history_screen.dart"]:::client
                Alerts["lib/ui/screens/alerts_screen.dart"]:::client
                AlertDetail["lib/ui/screens/alert_detail_screen.dart"]:::client
                Safety["lib/ui/screens/safety_screen.dart"]:::client
                Settings["lib/ui/screens/settings_screen.dart"]:::client
                Login["lib/ui/screens/login_screen.dart"]:::client
                Signup["lib/ui/screens/signup_screen.dart"]:::client
                Confirm["lib/ui/screens/confirmation_screen.dart"]:::client
            end

            Widget["lib/ui/widgets/moto_card.dart"]:::client

            subgraph "Platform Folders"
                Android["android/"]:::client
                iOS["ios/"]:::client
                Web["web/"]:::client
                Linux["linux/"]:::client
                MacOS["macos/"]:::client
                Windows["windows/"]:::client
            end
        end
    end

    External["OpenStreetMap Tiles"]:::external

    IoT -->|"HTTPS POST JSON"| Proxy
    Proxy -->|"REST INSERT"| DB
    Entry -->|"Auth, Query, Realtime"| DB
    Entry -->|"Tile Requests"| External

    click IoT "https://github.com/gaesty/biketrack/blob/main/CodeFonctionnel/CodeFonctionnel.ino"
    click IoT "https://github.com/gaesty/biketrack/blob/main/CodeFonctionnel/utilities.h"
    click IoT "https://github.com/gaesty/biketrack/blob/main/CodeFonctionnel/arduino_secrets.h"
    click Proxy "https://github.com/gaesty/biketrack/blob/main/Proxy/proxy.js"
    click Proxy "https://github.com/gaesty/biketrack/blob/main/Proxy/README.md"
    click Entry "https://github.com/gaesty/biketrack/blob/main/lib/main.dart"
    click Models "https://github.com/gaesty/biketrack/blob/main/lib/models/moto_status.dart"
    click PS "https://github.com/gaesty/biketrack/blob/main/lib/services/password_service.dart"
    click PSI "https://github.com/gaesty/biketrack/blob/main/lib/services/password_service_impl.dart"
    click PSM "https://github.com/gaesty/biketrack/blob/main/lib/services/password_service_impl_mobile.dart"
    click PSW "https://github.com/gaesty/biketrack/blob/main/lib/services/password_service_impl_web.dart"
    click Home "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/home_screen.dart"
    click History "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/history_screen.dart"
    click Alerts "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/alerts_screen.dart"
    click AlertDetail "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/alert_detail_screen.dart"
    click Safety "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/safety_screen.dart"
    click Settings "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/settings_screen.dart"
    click Login "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/login_screen.dart"
    click Signup "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/signup_screen.dart"
    click Confirm "https://github.com/gaesty/biketrack/blob/main/lib/ui/screens/confirmation_screen.dart"
    click Widget "https://github.com/gaesty/biketrack/blob/main/lib/ui/widgets/moto_card.dart"
    click Android "https://github.com/gaesty/biketrack/tree/main/android/"
    click iOS "https://github.com/gaesty/biketrack/tree/main/ios/"
    click Web "https://github.com/gaesty/biketrack/tree/main/web/"
    click Linux "https://github.com/gaesty/biketrack/tree/main/linux/"
    click MacOS "https://github.com/gaesty/biketrack/tree/main/macos/"
    click Windows "https://github.com/gaesty/biketrack/tree/main/windows/"

    classDef hardware fill:#A2D9CE,stroke:#117A65,color:#000
    classDef compute fill:#85C1E9,stroke:#21618C,color:#000
    classDef database fill:#F5B041,stroke:#B9770E,color:#000
    classDef client fill:#D7BDE2,stroke:#7D3C98,color:#000
    classDef external fill:#D5DBDB,stroke:#7B7D7D,color:#000
```
