# zeromile

**Repository Path**: conanchen/zeromile

## Basic Information

- **Project Name**: zeromile
- **Description**: for distribute moto shop
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/conanchen/zeromile
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-28
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZeroMile Motorcycle Parts Shop Network

ZeroMile is a distributed motorcycle parts shop network designed for small and medium-sized motorcycle parts retailers. The system consists of two main components:

1. **Edge Servers** - Lightweight shop nodes for individual motorcycle parts shops
2. **Central Router** - Central coordination server for the entire network

Both components can be deployed on lightweight personal computers or micro servers in small/medium motorcycle parts shops.

## Client Access Patterns

There are two different ways that clients access the server data:

### Web Client Access
- The web interface is served by the same server instance and accesses data through the server's API endpoints
- Communication happens via HTTP/REST calls to localhost
- Both frontend and backend are deployed together on the same machine

### Desktop/Mobile App Access
- The Tauri app uses the Rust backend to provide commands to the frontend
- Data is accessed through Zenoh protocol via the Tauri backend
- The app can be deployed on computers or mobile devices
- The app NEVER accesses data through the server's API endpoints
- Instead, it uses Zenoh to communicate with the server after an authentication handshake

### Security
Both app and web clients must go through an authentication handshake protocol with the server before accessing private data. This ensures that only authorized clients can access sensitive information.

## Data Flow Comparison

### Local-First Design Philosophy

ZeroMile adopts a "Local-First" design philosophy similar to modern mobile applications, ensuring offline availability and responsiveness through layered architecture with Repository pattern and LiveData/Flow.

### Web Client Data Flow (Local-First Pattern)

```mermaid
sequenceDiagram
    participant WB as Web Browser
    participant UI as Svelte UI
    participant FA as FastAPI
    participant Repo as Python Repository
    participant ZF as ZeroMile Framework
    participant WS as WebSocket/SSE

    WB->>UI: User Interaction
    UI->>FA: Request Data
    FA->>Repo: Query Data
    Repo->>ZF: Query Data (Queryable API)
    ZF-->>Repo: Return Cached Data
    Repo-->>FA: Immediate Response
    FA-->>UI: Display Data (Instant)
    UI-->>WB: Display Data (Instant)

    Note over UI: Establish WebSocket/SSE Connection
    UI->>WS: Subscribe to Data Changes

    Note over Repo: Repository subscribes to LiveData via ZeroMile pub/sub

    Repo->>ZF: Subscribe LiveData (pub/sub)
    ZF-->>Repo: Data Changed Notification
    Repo->>UI: LiveData (WebSocket/SSE)
    UI-->>WB: Auto Update UI

    Note over ZF: ZeroMile Framework handles network peer synchronization asynchronously
```

**Key Characteristics:**
- **Immediate Response**: Repository queries ZeroMile Framework for cached data, ensuring instant UI responsiveness
- **Background Sync**: ZeroMile Framework handles network peer synchronization asynchronously, doesn't block UI
- **Automatic Updates**: Real-time updates delivered via WebSocket/SSE when data changes (Repository subscribes via pub/sub)
- **Offline Capable**: UI works with cached data even when offline

### Desktop/Mobile App Data Flow (Local-First Pattern)

```mermaid
sequenceDiagram
    participant TA as Tauri App
    participant UI as Svelte UI
    participant TC as Tauri Commands
    participant TR as Tauri Repository
    participant ZF as ZeroMile Framework

    TA->>UI: User Interaction
    UI->>TC: Request Data
    TC->>TR: Query Data
    TR->>ZF: Query Data (Queryable API)
    ZF-->>TR: Return Cached Data
    TR-->>TC: Immediate Response
    TC-->>UI: Display Data (Instant)
    UI-->>TA: Display Data (Instant)

    Note over UI,TC: UI observes LiveData via Tauri Commands

    Note over TR: Repository subscribes to LiveData via ZeroMile pub/sub

    TR->>ZF: Subscribe LiveData (pub/sub)
    ZF-->>TR: Data Changed Notification
    TR-->>TC: LiveData Update
    TC-->>UI: LiveData Notification
    UI-->>TA: Auto Update UI

    Note over ZF: ZeroMile Framework handles network peer synchronization asynchronously
```

**Key Characteristics:**
- **Native Performance**: Tauri App (Svelte UI + Tauri Commands + Tauri Repository) provides native desktop/mobile performance
- **ZeroMile Framework Integration**: Repository uses ZeroMile Queryable API to query data and pub/sub to subscribe for LiveData
- **Clean Abstraction**: Svelte UI only knows Tauri Commands, Tauri Repository and ZeroMile Framework are completely hidden
- **Responsive UI**: Always responsive due to local-first data access pattern

### Key Differences

1. **Local-First Design Philosophy**:
   - Both client types prioritize local database access for immediate UI responsiveness
   - Network synchronization happens asynchronously in the background
   - UI remains responsive even during network operations
   - Provides offline capability through local data caching

2. **Communication Protocol**:
   - Web clients use HTTP/REST to communicate with FastAPI for data requests
   - App clients invoke Tauri Commands for data requests
   - Repository uses ZeroMile Queryable API to query data
   - Repository uses ZeroMile pub/sub to subscribe for LiveData
   - ZeroMile Framework handles all network peer synchronization
   - Clients are unaware of ZeroMile Framework - only Repository knows about it
   - Both benefit from local caching for instant data access

3. **Repository Pattern Implementation**:
   - Repository layer provides unified data access interface for clients
   - Repository uses ZeroMile Queryable API to query data
   - Repository uses ZeroMile pub/sub to subscribe for LiveData
   - ZeroMile Framework handles local database caching and network peer synchronization
   - Web clients receive real-time updates via WebSocket/SSE (FastAPI handles this)
   - App clients receive real-time updates via Tauri Commands (Svelte UI only knows Tauri Commands)
   - **Hides ZeroMile Framework complexity** - clients never interact with ZeroMile Framework directly
   - **ZeroMile Framework is private to Repository layer only** - clients have no knowledge of it
   - **Tauri Repository is hidden from Svelte UI** - Svelte UI only knows Tauri Commands

4. **Data Model Abstraction**:
   - All network APIs return Response objects (DeviceCreateResponse, DeviceResponse, etc.)
   - Repository layer converts Response objects to local Entity objects
   - **Web Svelte UI layer only interacts with Pydantic models from FastAPI, maintaining clean architecture**
   - **Tauri App Svelte UI layer only interacts with Tauri Commands Request/Response objects**
   - Type-safe data models using Pydantic for FastAPI and dataclass/entity for local storage

5. **Deployment Model**:
   - Web clients are served by the same server instance
   - App clients are separate applications that connect to the server

6. **Access Method**:
   - Web clients make HTTP requests to FastAPI endpoints for data
   - App clients use Svelte UI which invokes Tauri Commands for data requests
   - Repository layer abstracts all data access and synchronization
   - ZeroMile API is completely hidden from clients - only Repository knows about it

7. **Native Capabilities**:
   - Web clients are limited by browser security restrictions
   - App clients can access native system resources through Tauri backend APIs

## Peer-to-Peer Server Interconnection

Servers interconnect and share data through Zenoh, with flexible deployment options:

```mermaid
graph LR
    A[Edge Server - Client] -->|Zenoh Protocol| B[Central Router]
    C[Edge Server - Peer] -->|Zenoh Protocol| B
    D[Edge Server - Router] -->|Zenoh Protocol| B
    E[Other Edge Servers] -->|Zenoh Protocol| D
    B -->|Zenoh Protocol| A
    B -->|Zenoh Protocol| C
    B -->|Zenoh Protocol| D
    D -->|Zenoh Protocol| E
    
    subgraph Network[Network]
        A
        B
        C
        D
        E
    end
```

### Flexible Zenoh Deployment Models

1. **Edge Server Modes**:
   - **Client Mode**: Default mode where edge servers run as Zenoh clients
   - **Peer Mode**: Intermediate deployment option
   - **Router Mode**: Advanced deployment for larger shops with capable hardware

2. **Central Router Enhanced Functionality**:
   - Operates as the primary Zenoh router for the entire network
   - Provides global product indexing and shop registration services
   - Supports multi-router network architecture
   - **Intelligent Mode Assignment**: Determines optimal Zenoh mode based on edge server hardware and network conditions
   - Coordinates between regional routers and edge servers

2. **Network Joining**:
   - Peers use the central router to quickly discover and join the network
   - The router facilitates fast network integration for new edge servers
   - Peers can connect to their choice of other edge servers after initial discovery

### How Peer-to-Peer Communication Works

1. **Edge Servers**:
   - Run in Zenoh client mode
   - Connect to the central router
   - Publish their product catalogs
   - Subscribe to relevant data streams

2. **Central Router**:
   - Runs in Zenoh router mode
   - Routes messages between edge servers
   - Maintains a global product index
   - Coordinates cross-location queries

3. **Data Sharing**:
   - Product catalogs are automatically shared
   - Inventory updates are propagated in real-time
   - Order requests are routed to appropriate servers
   - Communication is secure and efficient

## Project Structure

```
zeromile/
├── motoduct/               # Automotive parts scraping module
│   ├── scrapers/           # Platform-specific scrapers
│   ├── templates/          # Web interface templates
│   ├── docs/               # Documentation
│   ├── database.py         # Database interface
│   ├── main.py             # CLI entry point
│   ├── api.py              # REST API
│   ├── web.py              # Web interface
│   └── README.md           # Motoduct documentation
├── motoshop/               # Main application with central/edge servers and web interfaces
│   ├── central/            # Central router for coordinating network communication
│   │   ├── app/            # Desktop application using Tauri framework
│   │   ├── server/         # Central router server implementation
│   │   ├── web/            # Web interface for central router
│   │   └── README.md       # Central component documentation
│   ├── edge/               # Lightweight shop nodes for individual shops
│   │   ├── app/            # Desktop application using Tauri framework
│   │   ├── server/         # Edge server implementation
│   │   ├── web/            # Web interface for edge servers
│   │   └── README.md       # Edge component documentation
│   ├── docs/               # Documentation and design documents
│   └── README.md           # Main motoshop documentation
├── liugejiao/              # Quantitative trading system
│   ├── central/            # Central server for coordinating trading network
│   │   ├── server/         # Central server implementation
│   │   └── README.md       # Central component documentation
│   ├── edge/               # Edge servers for individual trading operations
│   │   ├── liugejiao_server/ # Main trading server implementation
│   │   └── README.md       # Edge component documentation
│   └── README.md           # Main liugejiao documentation
├── installer/              # Unified installer system for both projects
│   ├── unified-installer.py # Main installer script
│   ├── installer/          # Installer components (CLI/GUI)
│   └── .specify/           # Installer specifications
├── zeromile/               # Communication framework for distributed services
│   ├── communication/      # Zenoh abstraction layer
│   ├── user_management/    # User role management
│   ├── docs/               # Documentation
│   ├── example/            # Example code and tutorials
│   └── .specify/           # Framework specifications
├── tauri/                  # Desktop frontend framework
├── zenoh/                  # Data-centric middleware for real-time communication
└── zenoh-python/           # Python bindings for Zenoh integration
```

## Technology Stack

The MotoShop project uses a modern, efficient technology stack designed for distributed systems:

### Backend
- **Python**: Primary programming language for server implementations (3.8+)
- **Zenoh**: Data-centric middleware for real-time communication between components (v1.6.2)
- **FastAPI**: Web framework for building APIs and serving web interfaces (v0.120.1)
- **Uvicorn**: ASGI server implementation for Python (v0.38.0)
- **Pydantic**: Data validation and settings management using Python type hints (v2.12.3)

### Frontend
- **Svelte**: Modern JavaScript framework for building user interfaces (v5.42.3)
- **SvelteKit**: Application framework for Svelte applications (v2.48.2)
- **Vite**: Next generation frontend tooling and build system (v7.1.12)
- **TailwindCSS**: Utility-first CSS framework for styling
- **TypeScript**: Typed superset of JavaScript

### Client Types
The system supports two types of clients:
1. **Web Clients**: Browser-based interfaces that communicate with servers via FastAPI
2. **Desktop/Mobile App Clients**: Native applications built with the Tauri framework

### Tauri Framework
Tauri is used to build secure, lightweight desktop and mobile applications that can access system resources while maintaining a small footprint.
- **Tauri**: Desktop app framework using Rust and Web technologies (v2.9.1)
- **Rust**: Systems programming language for performance-critical components
- **Zenoh**: Direct integration in Tauri apps for peer-to-peer communication (v1.6.2)

## Component Descriptions

### [motoshop](file:///d:/git/zeromile/motoshop)
The main MotoShop application with central and edge server components, along with their respective web interfaces and desktop applications.

### [tauri](file:///d:/git/zeromile/tauri)
Desktop frontend framework used for building native applications.

### [zenoh](file:///d:/git/zeromile/zenoh)
Data-centric middleware for real-time communication between components.

### [motoduct](file:///d:/git/zeromile/motoduct)
Automotive parts scraping module that extracts product information from major online platforms and stores it in a local database. Can be integrated with MotoShop to enhance the product catalog with real-time market data.

### [zenoh-python](file:///d:/git/zeromile/zenoh-python)
Python bindings for Zenoh integration, allowing Python components to participate in the P2P network.

## Important Notes

1. **No root-level Node.js dependencies**: Each component manages its own frontend dependencies in its respective directory.
2. **No root-level builds**: Each component should be built from its own directory.
3. **Proper directory structure**: Always navigate to the appropriate component directory before running commands.

## Python Environment Setup

The MotoShop project uses Conda for Python environment management. There are two recommended environments:

1. **liugejiao** - The primary development environment
2. **motoshop** - An alternative environment

### Creating and Using the liugejiao Environment

To create and use the liugejiao environment (recommended):

```bash
# Create the liugejiao environment with Python 3.12
conda create -n liugejiao python=3.12

# Activate the liugejiao environment
conda activate liugejiao

# Verify the Python version
python --version
```

The liugejiao environment uses Python 3.12, which is compatible with all project dependencies.

### Creating and Using the motoshop Environment

Alternatively, you can use the motoshop environment:

```bash
# Create the motoshop environment with Python 3.12
conda create -n motoshop python=3.12

# Activate the motoshop environment
conda activate motoshop
```

## Getting Started

The recommended way to get started is to use the unified installer system:

```bash
# Navigate to the installer directory
cd installer

# Install the unified installer
pip install .

# Check hardware compatibility
zeromile-install --check-hardware

# Install components based on your role
zeromile-install --profile godowner    # For network coordinators
zeromile-install --profile storeowner  # For individual operators
```

Alternatively, you can refer to the README.md files in the [motoshop](file:///d:/git/zeromile/motoshop) and [liugejiao](file:///d:/git/zeromile/liugejiao) directories for project-specific setup instructions.