PROJECT OVERVIEW:
You are tasked with developing a comprehensive, fully functional Next.js MVP application called 'Solar Lot Manager'. This SaaS platform aims to revolutionize how public and private parking lot owners assess, plan, and manage the installation of solar panels. The core problem it solves is the complexity and uncertainty involved in transitioning parking infrastructure into renewable energy assets. The value proposition is to provide a streamlined, data-driven solution that maximizes solar potential, simplifies the installation process, and enhances financial returns for parking lot owners.
TECH STACK:
- Framework: Next.js (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- ORM: Drizzle ORM (PostgreSQL compatible)
- Database: PostgreSQL (using Vercel Postgres or a similar provider)
- UI Components: shadcn/ui
- Authentication: NextAuth.js (with Google, GitHub, and Email/Password providers)
- Forms: React Hook Form & Zod for validation
- State Management: React Context API / Zustand (for global state)
- Charting: Chart.js or Recharts
- Other: React Query (for data fetching/caching), React Email/Resend (for email notifications)
DATABASE SCHEMA:
1. **`users`**
- `id` (UUID, primary key)
- `name` (VARCHAR)
- `email` (VARCHAR, unique)
- `emailVerified` (TIMESTAMP)
- `image` (VARCHAR, optional)
- `createdAt` (TIMESTAMP)
- `updatedAt` (TIMESTAMP)
2. **`accounts`** (for NextAuth.js)
- `id` (BIGSERIAL, primary key)
- `userId` (UUID, foreign key to `users.id`)
- `type` (VARCHAR)
- `provider` (VARCHAR)
- `providerAccountId` (VARCHAR)
- `refresh_token` (TEXT, optional)
- `access_token` (TEXT, optional)
- `expires_at` (BIGINT, optional)
- `token_type` (VARCHAR, optional)
- `scope` (VARCHAR, optional)
- `id_token` (TEXT, optional)
- `session_state` (VARCHAR, optional)
3. **`sessions`** (for NextAuth.js)
- `id` (BIGSERIAL, primary key)
- `sessionToken` (VARCHAR, unique)
- `userId` (UUID, foreign key to `users.id`)
- `expires` (TIMESTAMP)
4. **`verificationTokens`** (for NextAuth.js)
- `identifier` (VARCHAR)
- `token` (VARCHAR, unique)
- `expires` (TIMESTAMP)
5. **`parkingLots`**
- `id` (UUID, primary key)
- `userId` (UUID, foreign key to `users.id`)
- `name` (VARCHAR)
- `address` (VARCHAR)
- `latitude` (DECIMAL)
- `longitude` (DECIMAL)
- `areaSqMeters` (DECIMAL)
- `avgShadingPercentage` (INTEGER, 0-100)
- `currentUsageType` (VARCHAR, e.g., 'Public', 'Private Commercial', 'Residential')
- `createdAt` (TIMESTAMP)
- `updatedAt` (TIMESTAMP)
6. **`solarAnalyses`**
- `id` (UUID, primary key)
- `parkingLotId` (UUID, foreign key to `parkingLots.id`)
- `potentialKwhPerYear` (DECIMAL)
- `estimatedInstallationCost` (DECIMAL)
- `paybackPeriodYears` (DECIMAL)
- `roiPercentage` (DECIMAL)
- `reportGeneratedAt` (TIMESTAMP)
- `technicalDetails` (JSONB, optional)
7. **`suppliers`**
- `id` (UUID, primary key)
- `name` (VARCHAR)
- `contactPerson` (VARCHAR)
- `email` (VARCHAR)
- `phone` (VARCHAR)
- `website` (VARCHAR, optional)
- `specialization` (VARCHAR, e.g., 'Residential Solar', 'Commercial Solar', 'EV Charging Integration')
8. **`installations`**
- `id` (UUID, primary key)
- `parkingLotId` (UUID, foreign key to `parkingLots.id`)
- `supplierId` (UUID, foreign key to `suppliers.id`)
- `status` (VARCHAR, e.g., 'Quoted', 'In Progress', 'Completed', 'Cancelled')
- `quoteAmount` (DECIMAL)
- `installationDate` (DATE, optional)
- `energyProductionKwh` (DECIMAL, optional, cumulative)
- `createdAt` (TIMESTAMP)
- `updatedAt` (TIMESTAMP)
CORE FEATURES & USER FLOW:
1. **User Authentication (NextAuth.js):**
- Flow: Users can sign up using Google, GitHub, or email/password. Email verification is required for email signups. Existing users can log in via their chosen provider. Password reset functionality for email signups.
- Edge Case: Handle multiple login attempts, invalid credentials, expired tokens.
2. **Parking Lot Management (CRUD):**
- Flow:
a. Authenticated users navigate to 'My Parking Lots'.
b. Click 'Add New Lot'.
c. Fill out the 'Add Parking Lot' form (name, address, area, avg shading, usage type). Use Google Maps API or similar for lat/lon auto-fill from address.
d. The system automatically calculates or prompts for manual input of `avgShadingPercentage`.
e. Saved lots appear in a list/table. Users can view, edit, or delete their lots.
- Edge Cases: Invalid address, missing required fields, exceeding user's lot limit (if tiered).
3. **Solar Potential Analysis:**
- Flow:
a. From the 'My Parking Lots' list, user clicks 'Analyze Solar Potential' for a specific lot.
b. The system fetches lot data (area, lat/lon, shading).
c. It uses a backend calculation (potentially calling a third-party API for precise solar irradiance or using a simplified model) to estimate `potentialKwhPerYear`.
d. It applies industry-standard cost assumptions (configurable or based on location averages) to estimate `estimatedInstallationCost`.
e. Calculates `paybackPeriodYears` and `roiPercentage` based on estimated cost and potential energy production (assuming a certain electricity price).
f. Saves the results in the `solarAnalyses` table, linked to the `parkingLotId`.
g. Displays the analysis results on a dedicated 'Analysis Report' page for the lot.
- Edge Cases: Insufficient data for calculation, API failure, extreme shading, geographical limitations.
4. **Supplier & Quote Management:**
- Flow:
a. Users navigate to 'Suppliers'. They see a list of available suppliers (pre-populated or fetched from an external directory).
b. Users can search/filter suppliers by specialization.
c. For a specific parking lot's analysis report, users can click 'Request Quotes'.
d. The system creates entries in the `installations` table with `status: 'Quoted'`, linking the `parkingLotId` and a selected `supplierId`.
e. (MVP Scope Limitation): The initial MVP might not fully automate quote retrieval but would facilitate the process. For MVP, maybe just a button to 'Contact Supplier' with pre-filled info.
f. (Future Scope): Integration with supplier APIs for actual quote data.
- Edge Cases: No suppliers available in the area, supplier unresponsiveness.
5. **Installation Tracking & Production Monitoring (Basic):**
- Flow:
a. Users can manually update the status of an installation (e.g., from 'Quoted' to 'In Progress' to 'Completed') via the 'Installations' page.
b. For 'Completed' installations, users can input `energyProductionKwh` (cumulative or monthly, MVP to decide).
c. A dashboard widget or the analysis report page shows basic production data.
- Edge Cases: Incorrect data entry, delayed updates from user.
API & DATA FETCHING:
- Use Next.js API Routes (or Server Actions for Drizzle ORM integration).
- **Auth Endpoints:** Handled by NextAuth.js.
- **`/api/parking-lots` (POST, PUT, DELETE, GET):** CRUD operations for `parkingLots`.
- Request Body (POST/PUT): `{ name, address, areaSqMeters, avgShadingPercentage, currentUsageType, latitude?, longitude? }`
- Response Body (GET list): `ParkingLot[]`
- Response Body (GET single): `ParkingLot`
- **`/api/parking-lots/[id]/analyze` (POST):** Triggers solar analysis calculation for a specific lot.
- Request Body: `{}`
- Response Body: `SolarAnalysis` (or status update if async)
- **`/api/suppliers` (GET):** Fetch list of suppliers.
- Response Body: `Supplier[]`
- **`/api/installations` (POST, PUT):** Create and update installation tracking records.
- Request Body (POST): `{ parkingLotId, supplierId }`
- **Data Fetching:** Utilize React Query for efficient caching, background updates, and optimistic UI updates. Fetch data in Server Components where appropriate for SEO and initial load performance. Use Client Components with React Query for interactive data.
UI/UX DESIGN & VISUAL IDENTITY:
- **Style:** Minimalist Clean with a focus on clarity and data visualization.
- **Color Palette:**
- Primary: #1E40AF (Deep Blue)
- Secondary: #3B82F6 (Bright Blue)
- Accent: #10B981 (Emerald Green for success/positive metrics)
- Background: #FFFFFF (White)
- Text: #1F2937 (Dark Gray)
- Alerts/Warnings: #F59E0B (Amber)
- Errors: #EF4444 (Red)
- **Typography:** Inter (from Google Fonts) - clean, modern, highly readable sans-serif.
- Headings: Inter Bold
- Body Text: Inter Regular
- **Layout:** Use a responsive grid system. Sidebar navigation for authenticated users. Clear card-based design for displaying lot summaries and analysis results. Generous whitespace.
- **Responsiveness:** Mobile-first approach. Ensure usability on devices from 480px to 1440px+.
- **Visual Elements:** Use clean icons (e.g., from Lucide React). Subtle use of gradients in charts and call-to-action buttons. Focus on clear data tables and informative charts.
COMPONENT BREAKDOWN (Next.js App Router):
- **`app/layout.tsx`:** Root layout, includes `<html>`, `<body>`, global providers (theme, query client), global Tailwind CSS setup.
- **`app/(auth)/layout.tsx`:** Auth layout (login, signup pages), minimal chrome.
- **`app/(auth)/login/page.tsx`:** Login form component, handles different providers.
- **`app/(auth)/signup/page.tsx`:** Signup form component.
- **`app/(auth)/reset-password/page.tsx`:** Password reset form.
- **`app/(marketing)/layout.tsx`:** Marketing site layout (navbar, footer).
- **`app/(marketing)/page.tsx`:** Landing Page (App Title, core value prop, feature highlights, testimonials, CTA).
- **`app/(marketing)/about/page.tsx`:** About Us page.
- **`app/(marketing)/contact/page.tsx`:** Contact form/info.
- **`app/(app)/layout.tsx`:** Main application layout (sidebar, header, content area).
- **`app/(app)/dashboard/page.tsx`:** Dashboard overview (summary cards, quick links, recent activity).
- **`app/(app)/parking-lots/page.tsx`:** Displays list of user's parking lots. Includes 'Add New Lot' button.
- **`app/(app)/parking-lots/new/page.tsx`:** Form page for adding a new parking lot.
- **`app/(app)/parking-lots/[id]/page.tsx`:** Detailed view of a single parking lot, includes 'Analyze Solar Potential' button and summary of analysis/installation.
- **`app/(app)/parking-lots/[id]/edit/page.tsx`:** Form page for editing an existing parking lot.
- **`app/(app)/parking-lots/[id]/analysis/page.tsx`:** Displays the detailed solar analysis report (charts, tables, ROI). Includes 'Request Quotes' button.
- **`app/(app)/suppliers/page.tsx`:** List and search functionality for suppliers.
- **`app/(app)/installations/page.tsx`:** Tracking view for active and past installations.
- **`app/(app)/settings/page.tsx`:** User profile and account settings.
- **`components/ui/`:** All shadcn/ui components (Button, Input, Card, Table, Sheet, Dialog, etc.).
- **`components/auth/`:** Auth-related components (e.g., `SignInButton`, `SignOutButton`).
- **`components/charts/`:** Chart components (e.g., `EnergyProductionChart`).
- **`components/forms/`:** Reusable form components and hooks.
- **`components/layout/`:** Sidebar, Header, Footer components.
- **`components/providers/`:** Context providers (e.g., `QueryProvider`).
- **`lib/`:** Utility functions, database client setup (Drizzle), constants, helper functions for calculations.
- **`hooks/`:** Custom React hooks (e.g., `useParkingLots`).
- **`server/actions/`:** Server Actions for form submissions and data mutations.
ANIMATIONS:
- **Page Transitions:** Subtle fade-in/out using Next.js `Transition` component or Framer Motion.
- **Button Hovers:** Slight scale-up or background color change.
- **Loading States:** Use shadcn/ui's `Skeleton` component or spinners (`lucide-react` icons) for data fetching.
- **Chart Animations:** Animate chart data loading.
- **Form Feedback:** Subtle animations on successful validation or submission errors.
EDGE CASES:
- **Empty States:** Display user-friendly messages and clear CTAs when lists are empty (e.g., 'You haven't added any parking lots yet. Click here to add one.').
- **Authentication:** Redirect unauthenticated users to the login page. Handle expired sessions gracefully. Protect API routes and Server Actions.
- **Error Handling:** Global error boundary. Specific error handling for API calls and form submissions. Display user-friendly error messages. Log errors to a service like Sentry.
- **Validation:** Comprehensive client-side and server-side validation using Zod for all forms.
- **Data Accuracy:** Clearly state assumptions used in calculations (e.g., electricity price, installation costs) and encourage users to consult with professionals for precise figures.
- **API Rate Limits:** Implement rate limiting if using external APIs heavily.
SAMPLE/MOCK DATA:
1. **User:**
```json
{
"id": "d290f1ee-6c54-4b01-90e1-013d6380240b",
"name": "Alice Wonderland",
"email": "alice@example.com",
"image": "https://i.pravatar.cc/300?u=alice@example.com"
}
```
2. **Parking Lot (Existing):**
```json
{
"id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
"userId": "d290f1ee-6c54-4b01-90e1-013d6380240b",
"name": "Downtown Central Garage",
"address": "123 Main St, Anytown, USA",
"latitude": 34.0522,
"longitude": -118.2437,
"areaSqMeters": 5000,
"avgShadingPercentage": 15,
"currentUsageType": "Private Commercial",
"createdAt": "2023-10-26T10:00:00Z",
"updatedAt": "2023-10-26T10:00:00Z"
}
```
3. **Solar Analysis Report:**
```json
{
"id": "b1f2a3d4-1234-5678-abcd-ef0123456789",
"parkingLotId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
"potentialKwhPerYear": 750000,
"estimatedInstallationCost": 500000,
"paybackPeriodYears": 8.5,
"roiPercentage": 12.5,
"reportGeneratedAt": "2023-10-26T11:00:00Z"
}
```
4. **Supplier:**
```json
{
"id": "c3d4e5f6-7890-1234-fedc-ba9876543210",
"name": "SunBright Solutions",
"contactPerson": "Jane Doe",
"email": "jane.doe@sunbright.com",
"phone": "(555) 123-4567",
"website": "https://sunbright.com",
"specialization": "Commercial Solar"
}
```
5. **Installation (Quoted):**
```json
{
"id": "d4e5f6a7-8901-2345-abcd-ef0123456789",
"parkingLotId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
"supplierId": "c3d4e5f6-7890-1234-fedc-ba9876543210",
"status": "Quoted",
"quoteAmount": 485000,
"installationDate": null,
"energyProductionKwh": 0,
"createdAt": "2023-10-27T09:00:00Z",
"updatedAt": "2023-10-27T09:00:00Z"
}
```
6. **Parking Lot (Residential Example):**
```json
{
"id": "e5f6a7b8-9012-3456-efab-cd0123456789",
"userId": "d290f1ee-6c54-4b01-90e1-013d6380240b",
"name": "Community Center Lot",
"address": "456 Oak Ave, Anytown, USA",
"latitude": 34.0600,
"longitude": -118.2500,
"areaSqMeters": 2000,
"avgShadingPercentage": 25,
"currentUsageType": "Public",
"createdAt": "2023-10-27T11:00:00Z",
"updatedAt": "2023-10-27T11:00:00Z"
}
```
7. **Supplier (Residential Focus):**
```json
{
"id": "f6a7b8c9-0123-4567-bcde-01234567890a",
"name": "HomeSun Installers",
"contactPerson": "Mike Smith",
"email": "contact@homesun.com",
"phone": "(555) 987-6543",
"website": null,
"specialization": "Residential Solar"
}
```
8. **Installation (In Progress):**
```json
{
"id": "g7b8c9d0-1234-5678-cdef-01234567890a",
"parkingLotId": "e5f6a7b8-9012-3456-efab-cd0123456789",
"supplierId": "f6a7b8c9-0123-4567-bcde-01234567890a",
"status": "In Progress",
"quoteAmount": 150000,
"installationDate": null,
"energyProductionKwh": 0,
"createdAt": "2023-10-28T14:00:00Z",
"updatedAt": "2023-10-28T14:00:00Z"
}
```
9. **Parking Lot (Large Commercial):**
```json
{
"id": "h8c9d0e1-2345-6789-def0-1234567890ab",
"userId": "d290f1ee-6c54-4b01-90e1-013d6380240b",
"name": "MegaMall Rooftop Parking",
"address": "789 Commerce Blvd, Metro City, USA",
"latitude": 34.1000,
"longitude": -118.3000,
"areaSqMeters": 15000,
"avgShadingPercentage": 10,
"currentUsageType": "Private Commercial",
"createdAt": "2023-10-28T16:00:00Z",
"updatedAt": "2023-10-28T16:00:00Z"
}
```
10. **Solar Analysis (Large Commercial):**
```json
{
"id": "i9d0e1f2-3456-7890-ef01-234567890abc",
"parkingLotId": "h8c9d0e1-2345-6789-def0-1234567890ab",
"potentialKwhPerYear": 1500000,
"estimatedInstallationCost": 1000000,
"paybackPeriodYears": 7.2,
"roiPercentage": 13.9,
"reportGeneratedAt": "2023-10-28T17:00:00Z"
}
```
TURKISH TRANSLATIONS:
- App Title: Güneşli Otopark Yöneticisi
- Navigation: Gösterge Paneli, Otoparklarım, Tedarikçiler, Kurulumlar, Ayarlar
- Buttons: Yeni Otopark Ekle, Güneş Potansiyelini Analiz Et, Teklif İste, Kaydet, Güncelle, Sil, Giriş Yap, Kayıt Ol
- Labels: Otopark Adı, Adres, Alan (m²), Ortalama Gölgeleme (%), Kullanım Tipi, Potansiyel Yıllık Üretim (kWh), Tahmini Kurulum Maliyeti, Geri Ödeme Süresi (Yıl), Yatırım Getirisi (%), Durum
- Placeholders: Otopark adı girin, Adres bilgisi, ...
- Messages: Otopark başarıyla eklendi., Analiz tamamlandı., Teklifler alınıyor..., Kurulum sürüyor.
- Headings: Otopark Detayları, Güneş Enerjisi Analiz Raporu, Mevcut Kurulumlar, Tedarikçi Listesi