How yosgi/kiaoratrails works
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.