🌍 Travel Memory Map (Travel Memory OS)

A feature-rich, interactive web platform built with Angular 21 and Node.js/Express that allows travelers to log, visualize, and share their journey memories. The application features a dynamic map interface, detailed travel statistics, social feed community, AI-powered nostalgic story generation, and automatic EXIF metadata extraction from photo uploads.

---

🚀 Key Features

📍 Interactive Leaflet Map Dashboard

• Dynamic Markers: Custom category markers styled with unique emojis and color schemes (e.g., 🏖️ Beach, 🛕 Temple, ⛰️ Mountain, 🏰 Fort, 🚗 Road Trip).
• Heat Map Mode: Switch to a density heat map view to visualize travel concentration areas.
• Smart Filtering: Live filters to search locations by keywords, favorites, specific categories, or the year visited.
• Geocoding & Search: Auto-complete location queries using the OpenStreetMap Nominatim API.

🤖 Smart AI & Weather Integrations

• Nostalgic Storyteller: Integrates the Google Gemini 2.5 Flash API to generate warm, first-person travel memories (under 240 characters) based on your notes, category, and weather conditions.
• Multi-Language Support: Automatically translate or generate stories in English, Hindi, Spanish, French, Japanese, German, Portuguese, or Arabic.
• Real-time Weather lookup: Queries the OpenWeatherMap API to fetch and store local temperature, humidity, wind speed, and weather conditions for visits.
• EXIF Geotagging: Automatically extracts embedded GPS coordinates and camera/lens profiles (make, model, settings) from uploaded images using exifr.

👥 Social Community Feed

• Travel Feed: View public travel logs and journals from other travelers in a global feed.
• Social Mechanics: Follow/unfollow other users, react (like) to visits, and comment on travel posts.
• Shareable Profiles: Set user profiles to public or private and share custom profile URLs (/user/:username) complete with user stats and interactive map journals.

📊 Analytics & Timeline Journal

• Travel Stats: Dashboard indicating total places, trips, media counts, total kilometers traveled, and geographical statistics (countries and states visited).
• Gear Analysis: Breakdown of camera equipment used based on photo EXIF data.
• Timeline View: A chronological timeline history (journal) of all visits, queryable by year.
• Media Gallery: Integrated photo gallery with image/video views and an interactive lightbox.
• Wishlist (Bucket List): Log planned future destinations with estimated target years.

🛡️ Admin Portal

• User Management: View users, promote users to admin status, and terminate accounts.
• System Stats: Overview of global platform usage, database records, and media volumes.

---

🛠️ Technology Stack

Frontend

• Framework: Angular 21 (Signals-based state management, standalone components, lazy loading)
• Styling: Tailwind CSS v4, PostCSS, Custom responsive layouts
• Mapping: Leaflet map library & Leaflet Heatmap
• Testing: Vitest, jsdom
• Formatting: Prettier

Backend

• Runtime: Node.js & TypeScript v6 (ts-node-dev)
• Framework: Express v5
• Database: MongoDB & Mongoose ORM
• Media Hosting: Multer & Cloudinary API
• APIs & Services: Google Gemini API, OpenWeatherMap API, OSM Nominatim
• Validation: Zod (strict schemas)
• Security: JWT authentication, bcrypt, Helmet (security headers), CORS

---

⚙️ Environment Configuration

Backend Config

Create a .env file in the /backend folder:

PORT=5000
MONGODB_URI=your-mongodb-connection-string
JWT_SECRET=your-jwt-signing-secret

# Cloudinary (Media Hosting)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Smart API Integrations
GEMINI_API_KEY=your-google-gemini-api-key
OPENWEATHER_API_KEY=your-openweathermap-api-key

Frontend Config

Configure endpoints in src/environments/environment.ts:

export const environment = {
  apiUrl: 'http://localhost:5000/api/v1', // Local API url
  // apiUrl: 'https://travel-memory-map-api.vercel.app/api/v1' // Production URL
};

---

📂 Project Structure

travel-memory-map/
├── backend/                   # Node.js + Express + TypeScript API server
│   ├── src/
│   │   ├── config/            # DB and Environment config
│   │   ├── middleware/        # JWT auth, validation, error handler
│   │   ├── modules/           # Module controllers, models, and routes
│   │   │   ├── auth/          # Authentication & Registration
│   │   │   ├── places/        # Geocoded locations
│   │   │   ├── visits/        # Individual logs/visits of places
│   │   │   ├── trips/         # Route sequences linking visits
│   │   │   ├── media/         # Image uploads & EXIF parsing
│   │   │   ├── features/      # Stats, Timeline, Weather, Bucket List, Gemini AI
│   │   │   ├── users/         # Profile management & Social flows
│   │   │   └── admin/         # Site admin controls
│   │   ├── services/          # External API handlers (Gemini API)
│   │   └── server.ts          # Server listener entry
│   └── tsconfig.json
│
├── src/                       # Angular Frontend Application
│   ├── app/
│   │   ├── components/        # Frontend standalone components
│   │   │   ├── landing/       # Landing page (responsive hero & dark mode)
│   │   │   ├── auth/          # Login & Signup flows
│   │   │   ├── dashboard/     # Interactive map, filters, timeline, settings
│   │   │   ├── profile-view/  # Public portfolio view & social actions
│   │   │   └── admin/         # Administrative console
│   │   ├── services/          # ApiService (backend client) & ThemeService
│   │   ├── app.routes.ts      # Lazy loaded routing
│   │   └── main.ts            # App bootstrapping
│   └── environments/          # Dev and production configs
├── package.json               # Frontend dependencies & CLI scripts
└── tsconfig.json

---

🏃 Getting Started

1. Prerequisite Checklist

• Node.js (v18 or higher recommended)
• MongoDB database instance (Local or Atlas)
• Cloudinary, Gemini, and OpenWeatherMap credentials

2. Setup the Backend

Navigate to the backend folder, install dependencies, and start the development server:

cd backend
npm install
npm run dev

The server will run on http://localhost:5000.

3. Setup the Frontend

From the root directory, install dependencies and start the Angular development server:

npm install
npm start

Open your browser and navigate to http://localhost:4200/.

4. Build and Compile

To compile the Angular production bundle:

npm run build

To compile the TypeScript backend source to Javascript:

cd backend
npm run build

---

🧪 Running Tests

To execute unit tests on the frontend using Vitest:

npm test

---

🔌 API Endpoints

All backend endpoints are prefixed with /api/v1.

🔑 Authentication (/auth)

• POST /auth/register - Create a new user account.
• POST /auth/login - Authenticate a user and return a JWT token.
• POST /auth/forgot-password - Request a password reset email.
• POST /auth/reset-password - Reset password using a secure token.

🗺️ Places (/places)

• POST /places - Add a new geographical location coordinate. (Auth required)
• GET /places - List all recorded places. (Auth required)
• GET /places/:slug - View a specific place by its URL slug. (Auth required)

📝 Visits (/visits)

• GET /visits - List all user visits. (Auth required)
• GET /visits/place/:placeId - Retrieve visits for a specific location. (Auth required)

🚗 Journeys/Trips (/trips)

• POST /trips/generate - Automatically generate trip details connecting visits. (Auth required)
• GET /trips - List all trips. (Auth required)
• GET /trips/:id - View detailed route metadata of a trip. (Auth required)

🖼️ Media (/media)

• POST /media/upload - Upload media (image/video) and run auto-EXIF parser. (Auth required)
• GET /media - Retrieve user's media library. (Auth required)
• GET /media/:id - View details for a single media asset. (Auth required)
• DELETE /media/:id - Delete media from database and Cloudinary storage. (Auth required)

🤖 Smart Features (/features)

• GET /features/stats - Fetch overall travel analytics. (Auth required)
• GET /features/timeline - Retrieve chronological log history. (Auth required)
• PATCH /features/places/:id - Update place parameters. (Auth required)
• PATCH /features/visits/:id - Update a visit record (notes, rating). (Auth required)
• POST /features/visits/:id/regenerate-story - Request Gemini AI to recreate memory description. (Auth required)
• GET /features/visits/:id/weather - Fetch weather info from OpenWeatherMap API. (Auth required)
• GET /features/bucket - Fetch wishlist items. (Auth required)
• POST /features/bucket - Add wishlist target. (Auth required)
• PATCH /features/bucket/:id - Edit wishlist details. (Auth required)
• DELETE /features/bucket/:id - Remove wishlist target. (Auth required)

👥 User Profiles & Feed (/users & /feed)

• GET /users/profile - Fetch current user's profile detail. (Auth required)
• PATCH /users/profile - Update bio, name, or visibility settings. (Auth required)
• POST /users/change-password - Update account password. (Auth required)
• DELETE /users/profile - Permanently terminate user account. (Auth required)
• GET /users/public/:username - Fetch public user profile and stats dashboard.
• POST /users/:username/follow - Follow/unfollow target user. (Auth required)
• GET /feed - Retrieve global activities feed.
• POST /feed - Share a visit log to the global feed. (Auth required)
• POST /feed/:id/like - React to a shared feed post. (Auth required)
• POST /feed/:id/comments - Append a comment to a post. (Auth required)

🛡️ Admin Suite (/admin) (Admin access required)

• GET /admin/stats - Platform global usage analytics.
• GET /admin/users - Fetch user directory.
• PATCH /admin/users/:id/role - Toggle user administrative role.
• DELETE /admin/users/:id - Terminate a user account.

---

🤝 Contributing

Contributions to Travel Memory Map are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'feat: add amazing feature'.
4. Push to the branch: git push origin feature/amazing-feature.
5. Open a Pull Request.

---

📄 License

Distributed under the ISC License. See the backend package.json for details.