specification.json

{
  "projectName": "TrailOpt - Intelligent Trip Planning & Optimization",
  "description": "A full-stack hiking trip optimizer that computes calorie expenditure, evaluates weather risk, generates packing lists, and performs gear weight minimization via DP. Built with Next.js, React, TypeScript, Tailwind, and MongoDB/PostgreSQL. Includes Google Login via NextAuth.",

  "auth": {
    "provider": "NextAuth (Auth.js)",
    "providers": [
      {
        "name": "Google",
        "type": "oauth",
        "envVarsRequired": [
          "GOOGLE_CLIENT_ID",
          "GOOGLE_CLIENT_SECRET",
          "NEXTAUTH_SECRET",
          "NEXTAUTH_URL"
        ]
      }
    ],
    "sessionStrategy": "jwt",
    "callbacks": {
      "jwt": "Attach user.id, email, name, and image",
      "session": "Expose user.id, email, name, and image to client"
    },
    "pages": {
      "signIn": "/auth/signin"
    },
    "protectedRoutes": [
      "/dashboard",
      "/trips/*",
      "/gear/*",
      "/optimize/*"
    ],
    "sessionProtectionBehavior": "Redirect unauthenticated users to /auth/signin"
  },

  "staticTrails": [
    {
      "name": "Yosemite Valley Loop",
      "location": "California, USA",
      "distanceKm": 18,
      "elevationGainM": 150,
      "typicalTemperatureRange": "5°C to 25°C",
      "difficulty": "Moderate",
      "recommendedTripLengthDays": 1,
      "notes": "Scenic valley loop with waterfalls and granite cliffs."
    },
    {
      "name": "Inca Trail",
      "location": "Peru",
      "distanceKm": 42,
      "elevationGainM": 1350,
      "typicalTemperatureRange": "2°C to 20°C",
      "difficulty": "Hard",
      "recommendedTripLengthDays": 4,
      "notes": "High-altitude trekking finishing at Machu Picchu."
    },
    {
      "name": "Appalachian Trail (Smokies Section)",
      "location": "Tennessee/North Carolina, USA",
      "distanceKm": 114,
      "elevationGainM": 4300,
      "typicalTemperatureRange": "-5°C to 20°C",
      "difficulty": "Hard",
      "recommendedTripLengthDays": 7,
      "notes": "Forest ridges with reliable shelters."
    },
    {
      "name": "Pacific Crest Trail (Section J)",
      "location": "Washington, USA",
      "distanceKm": 113,
      "elevationGainM": 3800,
      "typicalTemperatureRange": "0°C to 22°C",
      "difficulty": "Hard",
      "recommendedTripLengthDays": 6,
      "notes": "Alpine terrain with glacier views."
    },
    {
      "name": "John Muir Trail",
      "location": "California, USA",
      "distanceKm": 340,
      "elevationGainM": 15000,
      "typicalTemperatureRange": "-3°C to 23°C",
      "difficulty": "Very Hard",
      "recommendedTripLengthDays": 20,
      "notes": "Iconic Sierra Nevada thru-hike."
    },
    {
      "name": "Banff Skyline Trail",
      "location": "Alberta, Canada",
      "distanceKm": 44,
      "elevationGainM": 1520,
      "typicalTemperatureRange": "0°C to 18°C",
      "difficulty": "Moderate-Hard",
      "recommendedTripLengthDays": 3,
      "notes": "High-alpine ridge walking with 360° views."
    },
    {
      "name": "Tour du Mont Blanc",
      "location": "France/Italy/Switzerland",
      "distanceKm": 170,
      "elevationGainM": 10000,
      "typicalTemperatureRange": "4°C to 20°C",
      "difficulty": "Hard",
      "recommendedTripLengthDays": 10,
      "notes": "Famous Europe long-distance loop."
    },
    {
      "name": "Everest Base Camp Trek",
      "location": "Nepal",
      "distanceKm": 130,
      "elevationGainM": 3000,
      "typicalTemperatureRange": "-15°C to 12°C",
      "difficulty": "Very Hard",
      "recommendedTripLengthDays": 12,
      "notes": "Extreme elevation trek in Himalayas."
    },
    {
      "name": "Milford Track",
      "location": "New Zealand",
      "distanceKm": 53,
      "elevationGainM": 1500,
      "typicalTemperatureRange": "5°C to 18°C",
      "difficulty": "Moderate",
      "recommendedTripLengthDays": 4,
      "notes": "Lush forest and waterfalls."
    },
    {
      "name": "Kilimanjaro (Machame Route)",
      "location": "Tanzania",
      "distanceKm": 62,
      "elevationGainM": 4100,
      "typicalTemperatureRange": "-10°C to 20°C",
      "difficulty": "Very Hard",
      "recommendedTripLengthDays": 7,
      "notes": "Extreme elevation gain across multiple climate zones."
    }
  ],

  "techStack": {
    "frontend": ["Next.js", "React", "TypeScript", "Tailwind CSS", "Recharts or Chart.js"],
    "backend": ["Next.js API Routes", "Node.js", "TypeScript"],
    "database": ["MongoDB or PostgreSQL"],
    "optional": {
      "orm": "Prisma (if PostgreSQL)",
      "auth": "NextAuth Google OAuth"
    }
  },

  "systemArchitecture": {
    "frontend": [
      "Trip creation wizard",
      "Gear inventory manager",
      "Optimization dashboard",
      "Charts and visualizations",
      "Auth-protected dashboard",
      "Google sign-in UI"
    ],
    "backend": [
      "Trip analytics engine",
      "Weather risk engine",
      "Dynamic packing list generator",
      "Knapsack-based optimizer",
      "Database CRUD",
      "Auth session callbacks"
    ],
    "databaseModels": {
      "User": {
        "fields": [
          "id", "name", "email", "image", "createdAt"
        ]
      },
      "GearItem": {
        "fields": [
          "id", "userId", "name", "category", "baseWeight",
          "warmthRating", "priority", "isEssential", "createdAt"
        ]
      },
      "Trip": {
        "fields": [
          "id", "userId", "trailName", "distanceKm", "elevationGainM",
          "startDate", "location", "desiredPackWeightLimit",
          "temperatureRange", "weatherRiskScore", "optimizedGearListId",
          "createdAt"
        ]
      },
      "GearList": {
        "fields": [
          "id", "tripId", "items[]", "totalWeight", "generatedBy", "createdAt"
        ]
      }
    }
  },

  "coreFeatures": {
    "tripAnalytics": {
      "inputs": [
        "distanceKm", "elevationGainM", "expectedHours",
        "temperatureRange", "trailDifficulty"
      ],
      "logic": {
        "calorieEstimation": "Modified Naismith + MET-based adjustments",
        "fatigueScore": "Weighted combination of elevation, distance, temp"
      },
      "outputs": [
        "calorieEstimate",
        "fatigueScore",
        "charts"
      ]
    },

    "weatherRiskEngine": {
      "dataSourceOptions": ["Mock data", "OpenWeather API"],
      "riskModel": {
        "coldExposure": "Temperature thresholds",
        "heatExposure": "High temp penalty",
        "stormProbability": "Precipitation-based",
        "windRisk": "Wind speed scoring"
      },
      "finalRiskScore": "Low / Medium / High"
    },

    "autoGeneratedPackingList": {
      "inputs": [
        "distance", "elevation", "temperature",
        "tripLength", "weatherRiskScore"
      ],
      "rules": [
        "Essentials always included",
        "Add insulation if cold",
        "Add water/food based on distance",
        "Add shelter for multi-day trips"
      ],
      "output": "Gear items[] with computed weights"
    },

    "weightOptimizationDP": {
      "approach": "0/1 Knapsack DP",
      "inputs": ["gearItems", "weightLimit"],
      "constraints": [
        "Essentials must be included",
        "Stay within weight limit"
      ],
      "goal": "Max usefulness while minimizing weight",
      "dpState": "dp[i][w] = best usefulness",
      "output": [
        "optimizedGearList",
        "optimizedWeight",
        "itemsChosen[]"
      ]
    },

    "visualizations": {
      "charts": [
        "Weight breakdown",
        "Calorie burn curve",
        "Weather timeline",
        "Before/After optimization comparison"
      ]
    }
  },

  "uiPages": {
    "auth": [
      "/auth/signin (Google login button)"
    ],
    "home": [
      "Marketing hero",
      "Start a Trip button",
      "Sign in with Google"
    ],
    "dashboard": [
      "Requires login",
      "Recent trips grid",
      "Gear inventory summary"
    ],
    "tripBuilderWizard": [
      "Step 1: Trail Select",
      "Step 2: Trail Stats Auto-Fill",
      "Step 3: Weather Info",
      "Step 4: Gear Preferences"
    ],
    "gearInventoryManager": [
      "CRUD",
      "Category filters",
      "Weight auto-sum",
      "Image upload"
    ],
    "optimizationDashboard": [
      "Calorie Estimate",
      "Weather Risk Score",
      "Suggested Gear",
      "Run Optimization button",
      "Weight comparison charts"
    ],
    "tripDetailPage": [
      "Timeline",
      "Charts",
      "Optimized Gear List",
      "Export"
    ]
  },

  "backendAPIs": {
    "authRoutes": {
      "nextAuth": "/api/auth/[...nextauth]",
      "session": "Built-in via next-auth/react"
    },
    "tripAnalyticsAPI": {
      "route": "/api/analytics",
      "method": "POST",
      "requestBody": [
        "distanceKm", "elevationGainM", "packWeight", "tempRange"
      ],
      "response": ["calorieEstimate", "fatigueScore"]
    },
    "weatherRiskAPI": {
      "route": "/api/weather-risk",
      "method": "GET",
      "queryParams": ["lat", "lon"],
      "response": ["riskScore", "recommendations"]
    },
    "gearOptimizationAPI": {
      "route": "/api/optimize-gear",
      "method": "POST",
      "requestBody": ["gearItems[]", "weightLimit"],
      "response": ["optimizedGearList", "totalWeight"]
    }
  }
}