omega-instructions

byFarhan Lashari

these are the full instructions of the project . let build this

Landing PageScreen D: Login
Landing Page

Comments (0)

No comments yet. Be the first!

System Requirements

System Requirements Document for omega-instructions

1. Introduction

1.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z)

Document Version: 2.0.0

Target Audience: AI Models, Full-Stack Architects, and MERN Developers

Purpose: Comprehensive, turnkey technical documentation describing the entire Solar Care platform from start to finish. Any AI model or engineering team reading this document will have complete context to replicate, maintain, or extend every feature, design token, data schema, and workflow with 100% fidelity.

Page 1 of 43
  1. Data Models & TypeScript Interfaces

  2. How to Run, Build, and Deploy

1.3 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / The High-Conversion Landing Page / Section Breakdown

1.4 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Admin Control Center (Technicians & Database Live Section) / The Portal Switcher

[ 👤 Client View | 🛡️ Admin Portal ]

Allows immediate toggling between what the client sees and what the administrator manages.

  • Project name: omega-instructions.
  • The project is to be built from the full project instructions supplied by the user (attachment: Pasted_prompt.txt).

2. System Overview

2.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Project Overview & Philosophy

Solar Care (styled with an explicit space: Solar Care) is an enterprise-grade CleanTech solar performance monitoring, AI telemetry diagnostic, and after-sales maintenance platform. It addresses the real-world gap between solar installation and post-commissioning maintenance.

2.2 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture

Four primary React Contexts manage the global application state:

Page 3 of 43

3. Functional Requirements

3.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Project Overview & Philosophy / Key Value Propositions

  • For Solar System Owners (Clients): Real-time generation telemetry, automatic string-level fault diagnosis (shading, soiling, inverter clipping), net-metering billing audits, and one-tap booking of verified solar technicians.

  • For System Administrators / Platform Owners: A distinct Admin Control Center to manage the technician fleet, register new certified technicians via comprehensive modal forms, review live database collections, and dispatch field service tickets.

  • For Prospects: A modern, high-conversion landing page with Dark/Half-Light modes, interactive telemetry simulations, and a live Solar ROI/Savings estimator.

Page 4 of 43

3.2 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Repository Directory & File Architecture

├── components/

│   ├── admin/

│   │   └── AdminPortal.tsx       # Admin Control Center (Technicians, DB Live, Tickets, Fleet)

│   ├── alerts/

│   │   └── AlertsView.tsx        # System alert list with severity filters & action triggers

│   ├── assistant/

│   │   └── SolarAssistantChatbot.tsx # Floating AI chat modal with quick prompts

│   ├── auth/

│   │   └── AuthFlow.tsx          # 5-screen login/signup/verify/reset authentication

│   ├── common/

│   │   ├── Header.tsx            # Sticky header with Portal Switcher & System dropdown

│   ├── common/

│   │   └── Sidebar.tsx           # Collapsible sidebar navigation for Client/Admin modes

│   ├── dashboard/

│   │   └── DashboardView.tsx     # Hero KPIs, generation charts, weather sync, savings
Page 5 of 43
│   ├── landing/

│   │   └── LandingPage.tsx       # Landing page (Dark/Half-Light, Simulator, ROI slider)

│   ├── maintenance/

│   │   └── MaintenanceHub.tsx    # Request service form, tracking timeline & job reports

│   ├── onboarding/

│   │   ├── OnboardingModal.tsx   # Modal to add another solar array

│   │   └── SolarSetupScreen.tsx  # Mandatory wizard for newly registered accounts

│   ├── performance/

│   │   └── PerformanceView.tsx   # String DC voltage, MPPT analysis, irradiance tracking

│   ├── profile/

│   │   └── ProfileSettingsView.tsx # Account credentials, inverter IP, language preferences

│   ├── systems/

│   │   └── MySolarSystemsView.tsx # Detailed view of user's registered solar arrays

│   └── technicians/

│       └── TechniciansView.tsx   # Directory of verified technicians with filters & booking

└── utils/
Page 6 of 43
    ├── diagnosticEngine.ts       # Mathematical rules for calculating string deviations

└── utils/

    └── solarCalculations.ts      # Financial ROI, carbon offset, and yield formulas

3.3 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Multilingual & Urdu RTL Typography Engine

Solar Care features full bilingual support: English, native Urdu (Nastaliq script), and Roman Urdu.

3.4 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Multilingual & Urdu RTL Typography Engine / Nastaliq Spacing & Line-Height Standards

  • LanguageContext dynamically sets <html dir="rtl"> for Urdu and <html dir="ltr"> for English/Roman Urdu.

3.5 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture

Four primary React Contexts manage the global application state:

3.6 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture / LanguageContext (src/context/LanguageContext.tsx)

  • Manages language: 'en' | 'ur' | 'ur-roman' and boolean isRtl.

  • Manages language: 'en' | 'ur' | 'ur-roman' and boolean isRtl.

  • Exposes t dictionary containing translated labels for navigation, buttons, alerts, and dashboard stats.

Page 7 of 43

3.7 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture / AuthContext (src/context/AuthContext.tsx)

  • Manages currentUser: User | null, isAuthenticated: boolean, and currentAuthScreen.

  • Session persistence in localStorage under key solarcare_user_session.

  • Handles communication with Express backend endpoints (/api/auth/*).

3.8 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture / SolarContext (src/context/SolarContext.tsx)

  • Stores user's solar arrays (systems: SolarSystem[]).

  • Tracks activeSystem: SolarSystem (e.g., 10 kW DHA Rooftop array).

  • Computes real-time telemetry, mock irradiance, string DC voltages, and unreadAlertCount.

Page 8 of 43

3.9 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Core State Management & Context Architecture / MaintenanceContext (src/context/MaintenanceContext.tsx)

  • Manages serviceRequests: ServiceRequest[] with persistence in solarcare_maintenance_requests.

  • Manages dynamic fleet technicians: Technician[] with persistence in solarcare_technicians_list.

  • Provides CRUD operations:

    • addTechnician(techData): Registers a new technician into state and storage.

    • updateTechnician(id, updates): Updates status, rates, or verification badges.

    • deleteTechnician(id): Removes a technician.

    • assignTechnicianToRequest(requestId, techId, techName): Dispatches tickets.

    • advanceRequestStatus(requestId, status, note): Progresses tickets through Requested → Accepted → In Progress → Completed.

Page 9 of 43

3.10 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / The High-Conversion Landing Page / Section Breakdown

  1. Sticky Header:

    • Left: Solar Care logo with slow-spinning sun icon and spacing.

    • Center: Smooth scroll navigation links (Features, How It Works, FAQ).

    • Right: Dark / Half-Light Toggle, Language Dropdown, Log In button, and Sign Up CTA button.

  2. Hero Section:

    • Shimmer gradient headline: "Your Solar System, Always at Peak."

    • Concise 1-sentence value proposition.

    • Dual CTAs: "Get Started Free" (opens Sign Up) + "Log In to Account".

    • Gradient banner with "Sign Up Free" and "Log In" buttons.

    • Trust micro-badges: No credit card, 95% inverter compatibility, bilingual.

  3. Stat Bar:

    • 4 key metrics: 12,000+ Systems, 99.4% Fault Precision, <15 min Dispatch, 41 GWh Monitored.
  4. Core Capabilities (Features):

    • 4 bento cards: AI Diagnostics, Live Telemetry, Net-Metering Audit, Certified Technicians.
  5. How It Works:

Page 10 of 43
  • 3-step visual guide: Create Account (60s) → Connect Inverter (WiFi) → Monitor & Act.
  1. Live Telemetry Cockpit Preview:

    • Split view: Telemetry feature checklist on left; live metric tiles on right (Current Output 8.42 kW, Inverter Health 98.8%, Yield 44.1 kWh, Sync <30s).
  2. Social Proof & Testimonials:

    • 3 authentic quotes from commercial and residential solar owners across Lahore, Islamabad, and CleanTech PK.
  3. Interactive FAQ Accordion:

    • Expandable questions on inverter compatibility (Huawei, Growatt, Sungrow, Fronius, Sofar, Inverex, Knox), free residential tier, and booking flow.
Page 11 of 43

3.11 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Authentication & Registration Flow (5 Screens)

Landing[Landing Page] -->|Click Log In| LoginScreen[Screen D: Login]

LoginScreen -->|Authenticated| MainApp[Client Dashboard / Admin Portal]

Landing -->|Click Sign Up| SignUpEmail[Screen A: Email OTP Request]

SignUpEmail -->|Sends 6-digit OTP| VerifyCode[Screen B: Email Verification]

VerifyCode -->|Valid Code| CreatePassword[Screen C: Set Password & Name]

CreatePassword -->|Success| SolarSetup[First-Time Solar Setup Wizard]

LoginScreen -->|Forgot Password| ForgotSend[Screen E1: Forgot OTP]

ForgotSend -->|Verifies OTP| ForgotReset[Screen E2: Set New Password]

ForgotReset --> LoginScreen

SolarSetup -->|Setup Completed| MainApp

- **Top Bar Feature:** Includes a **"← Back to Home"** button allowing visitors to return to the landing page at any point.

- **Verification Rule:** Registration cannot be bypassed without email code verification.

- **Password Strength:** Enforces minimum 8 characters with uppercase, lowercase, number, and special character.
Page 12 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Customer / Client Portal (Solar Cockpit)

When authenticated as a customer (portalMode === 'client'), the user accesses:

  1. DashboardView: Live kW generation ticker, daily generation curve, solar savings (USD/PKR), carbon offset, and weather sync.

  2. PerformanceView: String-level voltage comparison (MPPT 1 vs MPPT 2), detecting clipping, partial shading, or dirt accumulation.

  3. MySolarSystemsView: Panel specifications (e.g. 585W TOPCon), inverter connection credentials, and cloud API link.

  4. AlertsView: Diagnostic alerts categorized as Critical, Warning, or Info with actionable recommendations.

  5. TechniciansView: Interactive directory with city search, inverter brand filter, ratings, and one-tap booking.

  6. MaintenanceHub: Submitted requests tracker with visual progress milestones (Requested → Accepted → In Progress → Completed) and before/after production recovery reports.

  7. SolarAssistantChatbot: Floating AI assistant with pre-populated questions and real-time generation troubleshooting.

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Admin Control Center (Technicians & Database Live Section) / The Portal Switcher

Positioned prominently in both Header.tsx and Sidebar.tsx:

Page 13 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Admin Control Center (Technicians & Database Live Section) / Admin Capabilities

  1. Fleet Technicians Management:

    • Delete Action with confirmation prompt.
  2. Fleet Technicians Management:

    • Quick Status Toggle: Change status in 1 click (Available Today → Tomorrow → Booked).
  3. Fleet Technicians Management:

    • Quick Verification Toggle: Add or revoke the Solar Care Certified Partner badge.
  4. Fleet Technicians Management:

    • Comprehensive summary table showing: Name, Direct Phone, City/Area, Inverter Brands, Hourly Rate (PKR), Rating, Jobs Completed, and Availability Status.
  5. "+ Add New Technician" Modal Form:

    • Full Name, Phone / WhatsApp (+92 format).

    • Service Area & City.

    • Hourly Rate (PKR) and Experience (Years).

    • Multi-select Inverter Checkboxes: Huawei, Growatt, Sungrow, Solis, GoodWe, Inverex, Knox, Fronius, Sofar, Crown.

    • Certifications (PEC Engineer, HCIA-Solar, etc.).

    • Bio & Specialization.

    • Verified Partner checkbox.

Page 14 of 43
  • Persistence: Newly added technicians are stored in MaintenanceContext and localStorage, immediately rendering in both Admin and Client views.
  1. Database Live Section:

    • Cluster Connection Ticker: Status (Active), RAM usage, Query Latency (11ms).

    • Interactive Collection Explorer: Tabs for Users, Solar Systems, Service Requests, and Technicians.

    • Formatted JSON records view for direct data inspection.

    • "Export JSON" button to download full database snapshots.

  2. Client Service Tickets Hub:

    • Complete queue of client service requests.

    • Action buttons to Accept, Dispatch, and Resolve tickets with timestamped audit notes.

  3. Client Solar Fleet Overview:

    • Multi-card overview of all monitored client solar arrays across Pakistan.
Page 15 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Backend Express 5 Server & REST Endpoints

| Method | Endpoint | Description |

|---|---|---|

| GET | /api/health | Service health check |

| POST | /api/auth/check-email | Check if email is registered |

| POST | /api/auth/send-code | Generate & send 6-digit OTP via Nodemailer |

| POST | /api/auth/verify-code | Verify OTP code |

| POST | /api/auth/register | Register user with password complexity checks |

| POST | /api/auth/login | Authenticate user credentials against DB |

| POST | /api/auth/forgot-password/send-code | Send password reset OTP |

| POST | /api/auth/forgot-password/verify | Verify reset OTP |

| POST | /api/auth/forgot-password/reset | Update password in database |

| GET | /api/systems/user/:userId | Get solar arrays for specific user |

| POST | /api/systems | Add new solar array |

| PUT | /api/systems/:id | Update solar array configuration |

| DELETE | /api/systems/:id | Remove solar array |

| GET | /api/requests/user/:userId | Get maintenance tickets for user |

| POST | /api/requests | Create new maintenance ticket |

Page 16 of 43

| PATCH | /api/requests/:id | Update ticket status and dispatch notes |

| GET | /api/database/overview | Return collection counts and raw records |

| POST | /api/database/reset | Reset database to seed data |

| POST | /api/chat | AI Brain query endpoint |

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / AI Brain (Domain Classification & Sanitized Output) / Strict Relevance Classifier

Rejects queries outside solar engineering (general knowledge, coding, recipes). Valid queries must match photovoltaic domain keywords (inverters, kW, irradiance, net metering, LiFePO4 batteries, shading, AC sizing).

Page 17 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / AI Brain (Domain Classification & Sanitized Output) / Output Sanitization Rule

Per project standards, all generated AI responses are strictly sanitized of:

  • * (asterisks, markdown bold/italic tags)

  • # (markdown header tags)

  • , (commas in sentences and numbers)

A dedicated cleanText sanitizer enforces this before returning replies:


function cleanText(str) {

  if (typeof str !== 'string') return str;

  return str.replace(/[*#,،]/g, '');

}

Page 18 of 43

3.12 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / User


export interface User {

  id: string;

  name: string;

  email: string;

  isVerified: boolean;

  avatar?: string;

  preferredLanguage: Language;

  createdAt: string;

  role?: 'admin' | 'customer';

}

3.13 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / Technician


export interface Technician {

  id: string;

### Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / ServiceRequest
Page 19 of 43

export interface ServiceRequest {

  id: string;

  systemId: string;

  technicianId?: string;

  technicianName?: string;

  problemCategory: string;

  description: string;

  preferredDate: string;

  photoUrl?: string;

  photoName?: string;

  createdAt: string;

  status: 'Requested' | 'Accepted' | 'In Progress' | 'Completed';

  statusTimeline: {

    status: ServiceStatus;

    timestamp: string;

  }[];

    note: string;

  workReport?: {

    completedDate: string;

    technicianNotes: string;

    workPerformed: string;

    partsReplaced?: string;

    beforeKwhDaily: number;

    afterKwhDaily: number;

    improvementPct: number;

  };
Page 20 of 43

4. User Personas

Solar Care serves three active human roles. The User model carries role?: 'admin' | 'customer'; prospects are unauthenticated visitors. This is not a closed persona catalog.

RoleResponsibilities & GoalsInputsDecisionsObservable SuccessAccess
Solar System Owner (Client)Monitor real-time generation telemetry, act on automatic string-level fault diagnosis (shading, soiling, inverter clipping), audit net-metering billing, book verified techniciansPlant telemetry, fault alerts, billing data, technician directory (city, inverter brand, ratings)Whether and whom to bookFaults diagnosed and resolved; booking completed in one tapAuthenticated Client Portal (Solar Cockpit), portalMode === 'client'; TechniciansView
System Administrator / Platform OwnerManage the technician fleet, register certified technicians, review live database collections, dispatch field service ticketsTechnician records (name, phone, city/area, inverter brands, hourly rate PKR, rating, jobs completed, availability), database collections, ticketsGrant/revoke Solar Care Certified Partner badge; dispatch ticketsFleet verified and current; tickets dispatchedAdmin Control Center (AdminPortal.tsx)
ProspectEvaluate solar viability before committingLanding page content, interactive telemetry simulations, Solar ROI/Savings estimatorWhether to proceedEngagement with estimator and simulationsPublic landing page (Dark/Half-Light modes); no account

4.1 Journeys

Client: authenticate into the Solar Cockpit → review generation telemetry and fault diagnoses → check net-metering billing → open TechniciansView, filter by city and inverter brand, compare ratings → book a technician in one tap.

Administrator: open the Admin Control Center → register a technician via the comprehensive modal form → toggle the Certified Partner badge → review the fleet summary table and live database collections → dispatch field service tickets.

Prospect: land on the page → switch Dark/Half-Light mode → run the ROI/Savings estimator and telemetry simulations → read testimonials from Lahore, Islamabad, and CleanTech PK owners.

Page 21 of 43

4.2 Supporting Actors (not personas)

Telemetry and fault-diagnosis services, the database, and the booking/ticketing system act on behalf of the roles above. Technician records (Technician interface: serviceArea, distanceKm, supportedInverters, verificationBadge, availability, rating, completedJobsCount, hourlyRatePkr, certifications) are managed objects, not a login role in this evidence.

5. Core User Flows

5.1 Prospect registers and completes solar setup

Actors: Prospect, AuthFlow, SolarSetupScreen. Trigger: Prospect selects Get Started Free or Sign Up Free.

  1. Prospect evaluates the landing-page telemetry simulation and Solar ROI/Savings estimator, then opens Screen A (Email OTP Request).
  2. The system checks the email (POST /api/auth/check-email) and sends a 6-digit code through POST /api/auth/send-code (Nodemailer).
  3. Prospect verifies the code on Screen B. Registration cannot bypass email-code verification; invalid codes require correction or another code.
  4. Prospect submits name and a complexity-checked password through POST /api/auth/register on Screen C.
  5. Successful registration opens the mandatory SolarSetupScreen wizard. The completed setup stores the array in SolarContext.systems, sets activeSystem, and opens the Client Dashboard.

Continuation: Additional arrays can later be added through OnboardingModal. Log In opens Screen D; ← Back to Home returns to the landing page.

Page 22 of 43

5.2 User logs in or recovers access

Actors: Client or System Administrator, AuthFlow. Trigger: User selects Log In.

  1. User submits credentials to POST /api/auth/login.
  2. On success, AuthContext sets currentUser and isAuthenticated, persisting the session under solarcare_user_session.
  3. The user enters the Client Portal or Admin Portal according to role. The portal switcher toggles between Client View and Admin Portal.
  4. For recovery, Forgot Password sends an OTP through POST /api/auth/forgot-password/send-code; the user verifies it through POST /api/auth/forgot-password/verify, sets a new password, and returns to Screen D.

5.3 Client monitors systems, performance, and savings

Actors: Client, DashboardView, PerformanceView, MySolarSystemsView. Trigger: Client opens the Solar Cockpit.

  1. Client reviews live kW generation, daily generation curve, USD/PKR savings, carbon offset, and weather synchronization.
  2. Client opens PerformanceView for string-level voltage comparison, including MPPT 1 versus MPPT 2; the system can flag clipping, partial shading, or dirt accumulation.
  3. In My Solar Systems, Client reviews panel specifications, inverter connection credentials, and the cloud API link, then adds another array through OnboardingModal.
Page 23 of 43

5.4 Client reviews alerts and recommendations

Actors: Client, AlertsView. Trigger: Client opens Alerts or unreadAlertCount increases.

  1. Client filters diagnostic alerts by Critical, Warning, or Info.
  2. Client follows an available actionable recommendation and continues to monitoring or maintenance when service is indicated.

5.5 Client finds a technician and tracks service

Actors: Client, TechniciansView, MaintenanceHub, System Administrator, Technician. Trigger: Client needs field service.

  1. Client searches the interactive technician directory by city, filters by inverter brand, reviews ratings, and uses one-tap booking.
  2. Client submits a MaintenanceHub request; it begins at Requested.
  3. The administrator accepts and dispatches the ticket, assigning a technician with assignTechnicianToRequest(requestId, techId, techName).
  4. The request progresses through Accepted → In Progress → Completed using advanceRequestStatus(requestId, status, note).
  5. Client follows visual milestones and, after completion, reviews before/after production-recovery reporting. Supported recovery is continued tracking after status or assignment updates.
Page 24 of 43

5.6 Administrator manages technicians and service tickets

Actors: System Administrator, AdminPortal, MaintenanceContext. Trigger: Administrator opens Fleet Technicians or the Client Service Tickets Hub.

  1. Administrator adds a technician with full name, phone/WhatsApp in +92 format, service area and city, hourly PKR rate, experience in years, supported inverter brands (Huawei, Growatt, Sungrow, Solis, GoodWe, Inverex, Knox, Fronius, Sofar, Crown), certifications, bio, specialization, and Verified Partner status.
  2. The record persists in MaintenanceContext and localStorage, immediately rendering in Admin and Client views.
  3. Administrator toggles availability (Available Today → Tomorrow → Booked), grants or revokes the Solar Care Certified Partner badge, updates records, or deletes a technician after confirmation. Fleet data persists under solarcare_technicians_list.
  4. In the service queue, Administrator uses Accept, Dispatch, and Resolve actions; each creates timestamped audit notes.

5.7 Administrator inspects live data and exports records

Actors: System Administrator, AdminPortal. Trigger: Administrator opens DB Live.

  1. Administrator selects the Users, Solar Systems, Service Requests, or Technicians collection.
  2. The Interactive Collection Explorer displays formatted JSON records for inspection.
  3. Export JSON downloads a full database snapshot. GET /api/health remains available for service health checking.
Page 25 of 43

5.8 User manages preferences and consults the assistant

Actors: User, ProfileSettingsView, LanguageContext, SolarAssistantChatbot. Trigger: User opens Profile Settings or the floating chat modal.

  1. User edits account credentials, inverter IP, and language. Urdu sets <html dir="rtl">; English and Roman Urdu set <html dir="ltr">.
  2. User selects a quick prompt or submits a question; the assistant sends it to POST /api/chat and responds in the modal.

6. Visuals Colors and Theme

[Design proposal; unspecified choices are defaults.]

Muse: Rasmus Andersson — Instrument-panel craft for Solar Care

Solar Care uses a calm, technical CleanTech telemetry language for solar owners, technicians, and administrators. The public entry is a dark instrument frame rather than a marketing image: a 12-column grid with an 8-point spacing rhythm, a split hero, dense ruled data rows, schematic string diagrams, inverter line art, and monospaced data labels. No stock photography, gradient blobs, blue or indigo primary, playful bounce, or heavy shadows.

Concrete design tokens

Page 26 of 43
  • Dark mode: background #07101A covering approximately 70% of each screen; elevated surface #101E2C; sub-panel #0D1824; primary/action emerald #059669; hover #047857; glow #10B981; live-value amber #F59E0B; amber soft #FEF3C7; amber dark #B45309; primary text #E6EDF3.
  • Half-Light mode: background #F1F5F9; elevated cards #FFFFFF; borders #E2E8F0; headings #0F172A; body text #334155 and #475569; sub-panels #E2E8F0 at 60% opacity; accent text #047857 on #ECFDF5; maximum shadow 0 2px 12px rgba(15,23,42,0.06).
  • Typography: Space Grotesk 600 for headings with -0.02em tracking; Inter Tight for body and controls; JetBrains Mono for telemetry numbers, tabular numerals, status labels, and numbered FAQ markers; Noto Nastaliq Urdu for Urdu content. Type scale: 64 / 48 / 36 / 28 / 20 / 16 / 14px, using responsive clamp() sizing so readable text and controls remain whole at 375px, 768px, and 1280px. Urdu uses line-height: 2.4 and word-spacing: 0.05em; language direction switches between RTL and LTR.
  • Geometry: 8px panel radii, 4px control radii, 1px hairline borders, compact 8px spacing increments, ruled rows, and tabular numerals. The wordmark always renders as Solar Care, never SolarCare.

Implementable public-entry visual

Build the hero as a dark, two-column instrument frame. Place the responsive Space Grotesk headline and accepted value proposition on the left with the Sign Up Free CTA and trust micro-badges. On the right, compose a JetBrains Mono telemetry stack showing Current Output 8.42 kW, Inverter Health 98.8%, Yield 44.1 kWh, and Sync <30s; mark Current Output with an amber live dot. A thin emerald rule runs beneath the sticky header, whose left side contains the slow-spinning sun icon and Solar Care wordmark, while the right side contains the Half-Light toggle, language dropdown, Log In, and Sign Up controls. Use only schematic solar/inverter line art and data labels as supporting imagery.

Page 27 of 43

6.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Design System & Theme Engine (Dark & Half-Light Modes) / A. Color Palette Definitions

  • Brand Primary: #059669 (Forest Emerald) / Hover #047857 / Glow #10B981

  • Solar Energy Accent: #F59E0B (Solar Amber) / Soft #FEF3C7 / Dark #B45309

  • Dark Mode Surfaces:

    • Page Background: #07101A (Obsidian Navy)

    • Elevated Cards: #101E2C with border rgba(255, 255, 255, 0.08)

    • Sub-panels: #0D1824

  • "Half-Light" Executive Palette (Never Blinding Paper White):

    • Page Background: #F1F5F9 (Cool Slate-100) — easy on the eyes during prolonged review

    • Elevated Cards: #FFFFFF with border #E2E8F0 and subtle shadow 0 2px 12px rgba(15,23,42,0.06)

    • Sub-panels & Tickers: #E2E8F0 (Slate-200 / 60% opacity)

    • Headings: Deep Obsidian Slate #0F172A (Slate-900)

    • Body Text: #334155 (Slate-700) and #475569 (Slate-600)

    • Accent Text: #047857 (Deep Emerald-700) on #ECFDF5 pills

Page 28 of 43

6.2 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Design System & Theme Engine (Dark & Half-Light Modes) / B. Logo Spacing Rule

Across all headers, footers, and sidebars, the brand identity must always render with an explicit space:

Solar <span className="...">Care</span>

(Never SolarCare without spacing).

6.3 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Multilingual & Urdu RTL Typography Engine / Nastaliq Spacing & Line-Height Standards

In src/index.css and tailwind.config.js:

  • Normal Latin fonts clip Nastaliq ascenders/descenders if standard line-heights are used.

  • Urdu layout enforces line-height: 2.4 and word-spacing: 0.05em on elements with .font-urdu or [dir="rtl"].

6.4 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / The High-Conversion Landing Page / Section Breakdown

  1. Bottom Call-to-Action Banner:

    • Gradient banner with "Sign Up Free" and "Log In" buttons.
  2. Professional Footer:

    • Operational status badge ("🟢 All Systems Operational"), copyright, and clean links.
Page 29 of 43

7. Signature Design Concept

[Design proposal; unspecified choices are defaults.]

Signature Design Concept: Solar Care Instrument Frame

Solar Care presents solar monitoring as a composed operational instrument: trustworthy, dense, and immediately legible. The public entry headline is “Your Solar System, Always at Peak.” with the subline “Solar Care monitors your array, finds faults and sends verified technicians.” The left side establishes the promise and conversion path; the right side proves it through live-looking telemetry surfaces rather than decorative imagery.

The landing page organizes the accepted public-entry content into a sticky header, hero, four-metric stat bar, four capability cards—AI Diagnostics, Live Telemetry, Net-Metering Audit, and Certified Technicians—a Live Telemetry Cockpit preview, interactive FAQ accordion, bottom CTA banner, and professional footer. The stat bar uses 12,000+ Systems, 99.4% Fault Precision, <15 min Dispatch, and 41 GWh Monitored. The cockpit preview pairs a telemetry feature checklist with the specified output, health, yield, and sync values. The FAQ covers inverter compatibility, the free residential tier, and booking flow, with numbered mono labels and hairline rules.

The sticky header carries the explicitly spaced Solar Care logo, navigation links for Features, How It Works, and FAQ, the Dark/Half-Light toggle, language dropdown, Log In, and Sign Up CTA. The footer retains the “🟢 All Systems Operational” badge, copyright, and clean links. The bottom banner retains “Sign Up Free” and “Log In” buttons. Trust micro-badges communicate no credit card, 95% inverter compatibility, and bilingual support.

Page 30 of 43

Dark ground remains dominant while Half-Light provides an executive mode that is never blinding paper white. Emerald signals actions and system pathways; amber signals live energy values. Components should use the accepted React 19, Vite 5, TypeScript 6, Tailwind CSS 3, Lucide React, and local asset architecture. Authentication retains the ← Back to Home return control, while authenticated areas retain the SolarAssistantChatbot and the admin portal switcher with its two-segment control and emerald active state.

7.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Design System & Theme Engine (Dark & Half-Light Modes)

The application avoids generic flat themes and implements a tailored CleanTech visual language.

8. Interaction Model & Motion Direction

[Design proposal; unspecified choices are defaults.]

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Page 31 of 43

8.1 Landing Hero Motion Brief

  • Focal subject: the right-hand JetBrains Mono telemetry tile stack, centered on the amber live dot beside Current Output 8.42 kW, with the emerald rule and schematic line work as quiet framing.
  • Input → transformation → outcome thesis: on page load, accepted telemetry values count up once to the specified readings. This makes monitoring feel live and precise, culminating in a readable operational snapshot that supports the Sign Up Free decision. Existing accepted controls retain their state changes: the theme toggle switches Dark/Half-Light, the language control switches the page between accepted LTR and RTL direction, and the FAQ expands or collapses.
  • Motion vocabulary: fast 120–200ms transitions, restrained opacity and value transitions, no decorative effects or bounce, and a slow continuous spin for the header sun icon. The stat bar and telemetry values use tabular numerals so counting does not cause layout shift. FAQ expansion uses a short height/opacity transition while preserving its hairline structure.
  • Composed first frame: show the dark instrument frame immediately, with the complete left headline, subline, CTA, and right telemetry stack legible; the amber live dot is active and the emerald header rule is visible. Readable text and controls remain whole at 375px, 768px, and 1280px.
  • Reduced-motion state: disable the sun rotation, count-up animation, and animated FAQ transition. Render final telemetry values immediately, preserve dots and rules as static indicators, and wrap or allow horizontal scrolling where necessary so every label and control can be brought fully into view.

The hero remains a flat CSS/UI composition; Canvas, R3F, Drei, and WebGL are not required.

Page 32 of 43

9. Non-Functional Requirements

No additional details specified.

10. Tech Stack

10.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Table of Contents

10.2 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Project Overview & Philosophy / Key Value Propositions

10.3 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Complete Technology Stack & Dependencies / Frontend Stack

  • Framework: React 19 (react ^19.2.8, react-dom ^19.2.8) with Vite 5 (vite ^5.4.14)

  • Language: TypeScript 6 (typescript ~6.0.2)

  • Styling: Tailwind CSS 3 (tailwindcss ^3.4.17) with PostCSS and Autoprefixer

  • Iconography: Lucide React (lucide-react ^1.55.0)

  • Typography: Inter (Latin, body/headings), Noto Nastaliq Urdu (Urdu Nastaliq font), JetBrains Mono (monospaced telemetry)

Page 33 of 43

10.4 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Complete Technology Stack & Dependencies / Backend Stack

  • Runtime: Node.js (ES Module syntax: "type": "module")

  • Server: Express 5 (express ^5.3.0)

  • CORS: Enabled (cors ^2.8.6)

  • Email Delivery: Nodemailer (nodemailer ^10.1.7) for real OTP delivery via Gmail SMTP

  • Environment Management: Dotenv (dotenv ^18.0.7)

  • Database Engine: File-backed local JSON cluster (server/data/solarcare_db.json) accessed via an atomic read/write abstraction layer (server/db.js), compatible with MongoDB Document API standards.

10.5 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Repository Directory & File Architecture

Page 34 of 43

Solar performance/

├── .env                              # Backend configuration (SMTP credentials, PORT=5000)

├── .env.example                      # Template environment variables

├── index.html                        # HTML entry point with preconnected Google Fonts

├── package.json                      # NPM dependencies and scripts

├── postcss.config.js                 # PostCSS setup with Tailwind & Autoprefixer

├── tailwind.config.js                # Custom color palettes, shadows, fonts & animations

├── tsconfig.json                     # TypeScript root configuration

├── tsconfig.app.json                 # TypeScript client compiler options

├── tsconfig.node.json                # TypeScript node environment

├── vite.config.ts                    # Vite build configuration with React plugin

│

├── public/                           # Static assets

├── server/                           # Express backend service

│   ├── aiBrain.js                    # Solar engineering AI classifier & sanitized generator

│   ├── db.js                         # Database controller, user store & seed records

│   ├── index.js                      # Express 5 server routes & static dist serving

│   ├── mailer.js                     # Nodemailer OTP email transporter

│   └── data/

│       └── solarcare_db.json         # Persistent JSON database (Users, Systems, Requests)

│

└── src/

    ├── App.css                       # Minimal supplementary utility CSS

    ├── App.tsx                       # Main router, auth guard & portal switcher

    ├── index.css                     # Tailwind layers, Nastaliq font styles & animations

    ├── main.tsx                      # React 19 root DOM mount

    │

    ├── assets/                       # Local images and hero artwork

    ├── context/

    │   ├── AuthContext.tsx           # Authentication state, login, registration, OTP handlers

    │   ├── LanguageContext.tsx       # i18n localization state, RTL direction toggle

    │   ├── MaintenanceContext.tsx    # Service requests & dynamic technician fleet state

    │   └── SolarContext.tsx          # Solar systems, active array selector, mock telemetry

    │

    ├── data/

    │   ├── mockAlerts.ts             # Default mock anomaly and maintenance alerts

    │   ├── mockChatbot.ts            # Client-side chatbot knowledge base & fallbacks

    │   ├── mockMaintenance.ts        # Pre-seeded maintenance tickets and status logs

    │   ├── mockSolarData.ts          # Hourly, daily, and monthly generation curves

    │   └── mockTechnicians.ts        # Baseline certified solar engineers in Pakistan

    │

    ├── i18n/

    │   ├── en.ts                     # English UI dictionary

    │   ├── index.ts                  # Language bundle selector

    │   ├── ur.ts                     # Native Urdu (Nastaliq script) UI dictionary

    │   └── urRoman.ts                # Roman Urdu (Latin transliteration) UI dictionary

    │

Page 35 of 43
├── services/

│   └── api.ts                    # REST client with automatic localhost fallback

├── types/

│   └── index.ts                  # Central TypeScript definitions (User, System, Technician, etc.)

10.6 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / The High-Conversion Landing Page

Located at src/components/landing/LandingPage.tsx.

10.7 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Authentication & Registration Flow (5 Screens)

Located at src/components/auth/AuthFlow.tsx.


flowchart TD

### Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Admin Control Center (Technicians & Database Live Section)

Located at `src/components/admin/AdminPortal.tsx`.

### Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Backend Express 5 Server & REST Endpoints

Located at `server/index.js` (listening on port 5000).

### Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / AI Brain (Domain Classification & Sanitized Output)

Located at `server/aiBrain.js`.
Page 36 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces

Located at src/types/index.ts.

Page 37 of 43

Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / Technician

name: string;

initials: string;

avatar?: string;

phone: string;

serviceArea: string;

distanceKm: number;

supportedInverters: string[];

isVerified: boolean;

verificationBadge: string;

availability: 'Available Today' | 'Next Available: Tomorrow' | 'Booked This Week';

experienceYears: number;

rating: number;

completedJobsCount: number;

specialization: string;

hourlyRatePkr: number;

bio: string;

certifications: string[];

}

Page 38 of 43

10.8 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / ServiceRequest

}


### Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / Data Models & TypeScript Interfaces / SolarSystem

```typescript

export interface SolarSystem {

  id: string;

  name: string;

  location: string;

  capacityKw: number;

  inverterBrand: string;

  inverterModel: string;

  installationDate: string;

  connectionMethod: string;

  connectionStatus: 'demo' | 'connected' | 'unavailable';

  panelCount: number;

  panelType: string;

  batteryCapacityKwh?: number;

}

Page 39 of 43

10.9 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / How to Run, Build, and Deploy / Installation


npm install

10.10 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / How to Run, Build, and Deploy / Running the Full Platform

In separate terminal windows:


### Terminal 1: Start Express 5 Backend (Port 5000)

npm run server

### Terminal 2: Start Vite Dev Server (Port 5173)

npm run dev

Or run the combined startup batch script:


start.bat

Page 40 of 43

10.11 Terminal 2: Start Vite Dev Server (Port 5173) / Production Build


npm run build

Build output is emitted to dist/. The Express backend is configured to statically serve dist/ with single-page application (SPA) fallback routing when accessed on http://localhost:5000.

Build output is emitted to dist/. The Express backend is configured to statically serve dist/ with single-page application (SPA) fallback routing when accessed on http://localhost:5000.

11. Assumptions and Constraints

11.1 Solar Care — Complete System Specification & Architecture Blueprint (A to Z) / How to Run, Build, and Deploy / Prerequisites

  • Node.js 18+ (tested on Node v24)

  • npm 9+

Page 41 of 43

12. Glossary

Solar Care — the product name, styled with an explicit space; an enterprise-grade CleanTech platform for solar performance monitoring, AI telemetry diagnostics, and after-sales maintenance, addressing the gap between solar installation and post-commissioning maintenance.

Language — the active interface language, typed as 'en' | 'ur' | 'ur-roman': English, native Urdu (Nastaliq script), and Roman Urdu. Each User records a preferredLanguage of this type.

isRtl — boolean flag exposed by LanguageContext (src/context/LanguageContext.tsx) alongside language; indicates whether the interface renders right-to-left.

t — the translation dictionary exposed by LanguageContext, holding translated labels for navigation, buttons, alerts, and dashboard stats.

User — an account holder with id, name, email, isVerified, optional avatar, preferredLanguage, createdAt, and optional role of 'admin' or 'customer'.

Technician — a service provider record identified by id (further fields per the Technician interface).

ServiceRequest — a maintenance request carrying id, systemId, optional technicianId and technicianName, problemCategory, description, preferredDate, optional photoUrl and photoName, createdAt, and status.

ServiceStatus — the lifecycle state of a ServiceRequest: 'Requested' | 'Accepted' | 'In Progress' | 'Completed'.

Page 42 of 43

statusTimeline — an ordered array of { status: ServiceStatus; timestamp: string } entries recording each status transition of a request; the request also carries a note.

workReport — the optional completion record on a ServiceRequest: completedDate, technicianNotes, workPerformed, optional partsReplaced, beforeKwhDaily, afterKwhDaily, and improvementPct.

Page 43 of 43
Live
Landing Page design preview

Administrator selects Log In

Credentials forgotten

Recovery OTP verified

New password set, return to login

Authentication succeeds with admin role

Administrator opens Admin Portal

Administrator registers technician

Technician record persisted

Badge granted or revoked

Administrator removes technician

Fleet kept current

Administrator opens service queue

Ticket accepted

Technician dispatched

Administrator opens DB Live

Collection explorer opened

Collection selected

Records inspected

Administrator opens profile settings

Landing Page: Open Log In

Screen D: Login: 1. Submit credentials

Screen E1: Forgot OTP: 2. Request recovery code

Screen E2: Set New Password: 3. Set new password

Client Dashboard / Admin Portal: Switch to Admin Portal

Admin Control Center: Open technician fleet

Control Center: Add new technician

Control Center: Toggle Certified Partner badge

Control Center: Toggle availability status

Control Center: Delete technician with confirmation

Control Center: Review fleet summary table

Control Center: Accept service ticket

Control Center: Dispatch technician to ticket

Control Center: Resolve ticket with audit note

Admin Control Center Technicians & Database Live Section : Open DB Live section

Database Live: Select collection tab

Database Live: Inspect JSON records

Database Live: Export JSON snapshot

ProfileSettingsView: Update account preferences

Live
Landing Page design preview

Administrator selects Log In

Credentials forgotten

Recovery OTP verified

New password set, return to login

Authentication succeeds with admin role

Administrator opens Admin Portal

Administrator registers technician

Technician record persisted

Badge granted or revoked

Administrator removes technician

Fleet kept current

Administrator opens service queue

Ticket accepted

Technician dispatched

Administrator opens DB Live

Collection explorer opened

Collection selected

Records inspected

Administrator opens profile settings

Landing Page: Open Log In

Screen D: Login: 1. Submit credentials

Screen E1: Forgot OTP: 2. Request recovery code

Screen E2: Set New Password: 3. Set new password

Client Dashboard / Admin Portal: Switch to Admin Portal

Admin Control Center: Open technician fleet

Control Center: Add new technician

Control Center: Toggle Certified Partner badge

Control Center: Toggle availability status

Control Center: Delete technician with confirmation

Control Center: Review fleet summary table

Control Center: Accept service ticket

Control Center: Dispatch technician to ticket

Control Center: Resolve ticket with audit note

Admin Control Center Technicians & Database Live Section : Open DB Live section

Database Live: Select collection tab

Database Live: Inspect JSON records

Database Live: Export JSON snapshot

ProfileSettingsView: Update account preferences