RoamReceipt: Developer Project Summary 1. Project Overview RoamReceipt is a Progressive Web App (PWA) designed for trip planning and expense tracking. It allows users to register, plan trips with specific destinations, record stops (like restaurants or fuel stations), log expenses for each stop, and review their trip history. The application is enhanced with AI-powered suggestions for nearby places using the Google Gemini API. Core Features: User Authentication: Mobile number and OTP-based sign-up/login (currently uses a static OTP for testing). Trip Management: Create, manage, and end trips. Trips can have an optional name and a destination. Stop & Expense Tracking: Add multiple stops to a trip, categorized by type (Restaurant, Fuel, etc.), and log expenses for each. AI-Powered Suggestions: Utilizes the Gemini API to search for nearby places and provide travel suggestions. Trip History: All completed trips are saved locally, allowing users to review their past journeys and total expenses. PWA-Ready: The app is installable on both iOS and Android and has basic offline capabilities via a service worker. 2. Tech Stack & Architecture The application is built as a single-page application with a modern, serverless-style frontend architecture. Framework: React 19 (loaded via CDN). Language: TypeScript. Styling: Tailwind CSS (loaded via CDN). State Management: Local component state managed exclusively with React Hooks (useState, useEffect, useMemo, etc.). There is no global state manager like Redux or Context API. Data Persistence: All user data, sessions, and trip histories are stored in the browser's localStorage. A dedicated service abstracts all read/write operations. API Integration: The Google Gemini API (@google/genai) is used for all AI features. The Google Maps Static API is used for the background image. Environment: The app is designed to run in an environment where no build step is required. All dependencies are loaded directly in index.html via a script with type="importmap". It assumes process.env.API_KEY is securely injected into the runtime environment. 3. Codebase Structure & Key Files index.html: The main entry point. Loads dependencies, sets up PWA meta tags, and contains the root DOM element. index.tsx: Renders the React App component and registers the service worker. App.tsx: The core of the application. This monolithic component acts as a controller, managing: The current view (Authentication, Planner, History). The authentication state (currentUser). The active trip object. All modals for adding stops, expenses, and tolls. components/Icons.tsx: A library of SVG icons used throughout the UI. hooks/useGeolocation.ts: A custom hook that abstracts the browser's Geolocation API to fetch the user's current location. services/: storageService.ts: Crucial file. The single source of truth for all localStorage interactions. Manages CRUD operations for users and trips. geminiService.ts: Handles all API calls to the Gemini API for searching places and fetching suggestions. types.ts: Contains all TypeScript interfaces and enums (Trip, Stop, User, etc.) for strong typing across the app. manifest.json & sw.js: These files provide the PWA functionality, making the app installable and enabling a basic offline cache. 4. Development & Testing Notes API Key: The application relies on process.env.API_KEY being available in the environment for both Gemini and Google Maps. The developer does not need to configure this. Authentication: The OTP is hardcoded to 9999 in App.tsx within the AuthScreen component for easy testing. This is not a production-ready security feature. Data Flow: The data flow is strictly top-down. The App component holds the primary state, which is passed down to child components via props. State updates are lifted up using callback functions. UI/UX: The UI is designed to be mobile-first with a "glassmorphism" effect, where content panels float over a static map background of the user's current location.