# yosgi/kiaoratrails architecture

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

- Interactive diagram: https://gitdiagram.com/yosgi/kiaoratrails
- Repository: https://github.com/yosgi/kiaoratrails

## Overview

##### Main Components
- Mobile Frontend: Built with Next.js (React 19), Tailwind CSS, and shadcn/ui. This part of the system handles the responsive, mobile-first user interface, interactive map views (with Google Maps API integration), digital twin visualization, user profiles, and reporting systems.
- Backend API: A NestJS-based backend (in the “backend” directory) providing RESTful endpoints. It manages business logic, authentication (using Privy), integration with AWS S3 for image/media storage, and geospatial services.
- Smart Contracts & Blockchain: The “contracts” directory houses Ethereum-based smart contracts for fund management, token rewards (TRL tokens), multisig wallet operations, and verification of trail maintenance tasks.
- External Integrations:
- Authentication via Privy (both in the frontend and backend).
- Geospatial/location services via Google Maps API.
- AWS S3 for storage.
- Blockchain wallet integration managed through Privy.

##### Relationships and Data Flow
- The Mobile Frontend communicates with the Backend API to exchange data, fetch user profiles, submit trail reports, and retrieve map/geospatial data.
- The Backend API acts as the intermediary between the frontend and the blockchain, handling authentication (via Privy), interacting with external storage (AWS S3), and processing data required for smart contract interactions.
- Smart Contracts provide transparency and decentralized logic for critical functions like token distribution and voting. Data flows from the backend to the blockchain and vice versa, especially for immutable recording of maintenance tasks and token transactions.
- External services (Privy, Google Maps, AWS S3) are accessed by both frontend and backend components.

##### Architectural Patterns and Design Principles
- Layered/MVC Approach: The system separates the presentation (mobile frontend), business logic (backend API), and data persistence/blockchain operations (smart contracts).
- Clear API Boundary: RESTful endpoints in the backend are responsible for bridging Web2 interactions with the blockchain.
- Modular Design: The project’s file tree shows independent modules (like posts, users, and repositories in the backend, and dedicated digital twin components in the mobile app) which should be distinctly represented.
- Emphasis on decoupled external integrations for authentication and mapping, ensuring each component is responsible for its domain.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Frontend Layer
    subgraph "Mobile Frontend Layer"
        MF1["Mobile Frontend (Next.js/React, Tailwind)"]:::frontend
        MF2["App Files"]:::frontendDetail
        MF3["UI Components"]:::frontendDetail
        MF4["Providers"]:::frontendDetail
        MF5["Public ABI Files"]:::frontendDetail
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        BA1["Backend API (NestJS)"]:::backend
        BA2["Posts Module"]:::backendDetail
        BA3["Users Module"]:::backendDetail
        BA4["Repositories Module"]:::backendDetail
        BA5["Controllers"]:::backendDetail
    end

    %% Smart Contracts Layer
    subgraph "Smart Contracts Layer"
        SC1["Smart Contracts (Ethereum)"]:::blockchain
        SC2["Contracts Directory"]:::blockchainDetail
        SC3["Compiled Artifacts"]:::blockchainDetail
        SC4["Contract Tests"]:::blockchainDetail
    end

    %% External Services
    subgraph "External Services"
        EX1["Privy (Auth&Wallet)"]:::external
        EX2["Google Maps API"]:::external
        EX3["AWS S3 (Storage)"]:::external
    end

    %% Data Flow Connections
    MF1 -->|"API_request"| BA1
    BA1 -->|"SmartContractCalls"| SC1
    MF1 ---|"AuthWallet"| EX1
    BA1 ---|"AuthWallet"| EX1
    MF1 ---|"MapData"| EX2
    BA1 ---|"Geospatial"| EX2
    BA1 ---|"MediaStorage"| EX3

    %% Internal Frontend Module Connections
    MF1 --> MF2
    MF1 --> MF3
    MF1 --> MF4
    MF1 --> MF5

    %% Internal Backend Module Connections
    BA1 --> BA2
    BA1 --> BA3
    BA1 --> BA4
    BA1 --> BA5

    %% Click Events for Mobile Frontend Components
    click MF1 "https://github.com/yosgi/kiaoratrails/tree/main/mobile-app"
    click MF2 "https://github.com/yosgi/kiaoratrails/tree/main/mobile-app/app"
    click MF3 "https://github.com/yosgi/kiaoratrails/tree/main/mobile-app/components"
    click MF4 "https://github.com/yosgi/kiaoratrails/tree/main/mobile-app/providers"
    click MF5 "https://github.com/yosgi/kiaoratrails/tree/main/mobile-app/public"

    %% Click Events for Backend API Components
    click BA1 "https://github.com/yosgi/kiaoratrails/tree/main/backend"
    click BA2 "https://github.com/yosgi/kiaoratrails/tree/main/backend/src/posts"
    click BA3 "https://github.com/yosgi/kiaoratrails/tree/main/backend/src/users"
    click BA4 "https://github.com/yosgi/kiaoratrails/tree/main/backend/src/repositories"
    click BA5 "https://github.com/yosgi/kiaoratrails/tree/main/backend/src/controllers"

    %% Click Events for Smart Contracts Components
    click SC1 "https://github.com/yosgi/kiaoratrails/tree/main/contracts"
    click SC2 "https://github.com/yosgi/kiaoratrails/tree/main/contracts/contracts"
    click SC3 "https://github.com/yosgi/kiaoratrails/tree/main/contracts/bin"
    click SC4 "https://github.com/yosgi/kiaoratrails/tree/main/contracts/test"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:2px;
    classDef frontendDetail fill:#ff9,stroke:#333,stroke-width:1px;
    classDef backend fill:#9f9,stroke:#333,stroke-width:2px;
    classDef backendDetail fill:#cff,stroke:#333,stroke-width:1px;
    classDef blockchain fill:#f99,stroke:#333,stroke-width:2px;
    classDef blockchainDetail fill:#fc9,stroke:#333,stroke-width:1px;
    classDef external fill:#9cf,stroke:#333,stroke-width:2px;
```
