# System & UI/UX Architecture Document
## Personal & Agency Portfolio Platform: Er. Sujeet Pandit & TechoMaster

---

## 1. High-Level Architecture Overview

The platform is designed following a **JAMstack (JavaScript, APIs, Markup)** architecture, decoupled into a lightning-fast client-side presentation tier and resilient serverless integration microservices for lead capture, email dispatches, and webhook notifications.

```mermaid
graph TB
    subgraph Client Tier ["Client Browser Tier (Modern Desktop & Mobile)"]
        HTML[Semantic HTML5 DOM]
        CSS[Vanilla CSS3 Engine & Tokens]
        JS[ES6+ Modular JavaScript Controller]
        WebGL[Three.js Interactive 3D Canvas]
        CLI[Terminal Emulation Engine]
        Calc[Scope Estimator Reactive State]
    end

    subgraph CDN ["Global CDN & Edge Delivery"]
        VercelEdge[Edge Cache / Cloudflare CDN]
        Assets[Optimized SVGs, Fonts & Media]
    end

    subgraph Backend Services ["Serverless Integration & API Tier"]
        ContactAPI["/api/v1/contact (Edge Function)"]
        AnalyticsAPI["/api/v1/analytics (Telemetry)"]
        EstimatorAPI["/api/v1/quote-request"]
    end

    subgraph External Ecosystem ["External Channels & Ecosystem"]
        EmailService[Resend / SendGrid SMTP]
        TelegramBot[Instant Lead Telegram Alert]
        CRM[HubSpot / Notion Lead DB]
        Socials[GitHub / LinkedIn / X / WhatsApp]
    end

    Client Tier -->|HTTP/2 Static Asset Requests| VercelEdge
    VercelEdge --> Assets
    JS --> WebGL
    JS --> CLI
    JS --> Calc
    
    JS -->|POST JSON Payload| ContactAPI
    JS -->|POST Telemetry| AnalyticsAPI
    JS -->|POST Quote Config| EstimatorAPI

    ContactAPI --> EmailService
    ContactAPI --> TelegramBot
    ContactAPI --> CRM
    Client Tier -->|Direct External Linking| Socials
```

---

## 2. Frontend Component Hierarchy & Layering

The UI is structured into modular, self-contained sections organized with clear separation of visual layout, state logic, and interaction handlers.

```mermaid
classDiagram
    class AppController {
        +init()
        +setupNavigation()
        +setupScrollSpy()
        +registerGlobalEvents()
    }
    
    class ThreeSceneController {
        +scene: THREE.Scene
        +camera: THREE.PerspectiveCamera
        +renderer: THREE.WebGLRenderer
        +particles: THREE.Points
        +animate()
        +onPointerMove(event)
        +onResize()
    }

    class TerminalController {
        +history: string[]
        +commands: Map
        +handleCommand(input)
        +renderOutput(text, type)
        +autocomplete()
    }

    class PortfolioController {
        +activeCategory: string
        +projects: ProjectItem[]
        +filterProjects(category)
        +openModal(projectId)
        +closeModal()
    }

    class ScopeEstimatorController {
        +baseRate: number
        +selectedType: string
        +selectedTimeline: string
        +selectedAddons: string[]
        +calculateEstimate()
        +exportToContactForm()
    }

    class ContactFormController {
        +validateField(fieldId)
        +handleSubmit(event)
        +showToast(message, type)
    }

    AppController --> ThreeSceneController
    AppController --> TerminalController
    AppController --> PortfolioController
    AppController --> ScopeEstimatorController
    AppController --> ContactFormController
```

---

## 3. UI Component Breakdown

### 3.1 Component Directory & Specifications

```
├── [01] Navigation Bar (Sticky Glassmorphic Header)
│   ├── Brand Identity (Logo + Er. Sujeet Pandit & TechoMaster)
│   ├── Desktop Nav Links (Home, About, Services, Stack, Portfolio, Estimator, Reviews, Contact)
│   ├── Quick Actions (CLI Terminal Toggle, Resume Modal, WhatsApp Connect)
│   └── Mobile Hamburger Drawer with smooth backdrop-filter blur
│
├── [02] Hero Viewport & Particle Canvas
│   ├── Three.js WebGL Particle Node Constellation (Physics & Mouse parallax)
│   ├── Headline & Value Proposition
│   ├── Live Metric Badges (150+ Projects, 45+ Clients, 5+ Years, 99.9% Quality)
│   └── Dual Action Buttons (Get in Touch / Explore Projects / Open CLI)
│
├── [03] Interactive Developer Terminal (Embedded CLI)
│   ├── Retro-modern Monospace Terminal Window (Controls: Minimize, Maximize, Close)
│   ├── Command Line Prompt (`sujeet@techomaster:~$ `)
│   ├── Dynamic Command Execution (`help`, `skills`, `projects`, `hire`, `clear`, etc.)
│   └── Quick Command Helper Chips for 1-click execution
│
├── [04] About & Leadership Section
│   ├── Founder Profile & Engineering Philosophy
│   ├── Key Pillars (Innovation, Scalability, AI-First Approach, Client Centricity)
│   ├── Dual Identity: Senior Full Stack Engineer + Agency Founder
│   └── Geographic Footprint Cards (Jabalpur, Mumbai, Sambhajinagar)
│
├── [05] TechoMaster Services Grid
│   ├── 6 Core Capabilities Cards with 3D Tilt Hover Physics
│   ├── Technology Badges & Key Deliverables
│   └── 1-Click "Inquire Service" Deep Linking
│
├── [06] Comprehensive Tech Stack Matrix
│   ├── Tabbed Stack Explorer (Frontend, Backend, AI/ML, Cloud/DevOps, Databases, Tools)
│   ├── Skill Cards with Level Indicator & Experience Metrics
│   └── Live Tech Radar Visualizations
│
├── [07] Portfolio & Case Study Showcase
│   ├── Category Filter Pills (All, AI/ML, Full Stack Web, Mobile, Cloud, Enterprise)
│   ├── Responsive Card Grid with Hover Previews and Tag Pills
│   └── Modal Detail Drawer with Architecture Summary, Tech Stack, and Live Links
│
├── [08] Interactive Project Scope & Cost Estimator
│   ├── Project Type Selector (Web, Mobile, AI/ML, Cloud, Custom Enterprise)
│   ├── Delivery Speed Toggle (Standard, Accelerated, Sprint)
│   ├── Add-on Capability Checkboxes (UI/UX, DevOps/CI/CD, 24/7 SLA, SEO)
│   └── Live Price & Timeline Calculation with "Apply to Inquiry" Button
│
├── [09] Testimonials & Social Proof Carousel
│   ├── Executive Reviews (Anoop Ahuja, Satish Batra, Ashok Argade)
│   ├── Verified 5-Star Ratings & Company Titles
│   └── Animated Carousel Controls (Next/Prev + Auto-play)
│
├── [10] Contact & Booking Hub
│   ├── Reactive Form with Real-time Field Validation & Local Storage draft saving
│   ├── Direct WhatsApp & Phone Connect Buttons
│   ├── Office Locations & Operating Hours
│   └── Multi-Platform Social Media Grid (GitHub, LinkedIn, X, Instagram, Facebook, ZoomInfo)
│
└── [11] Modal Dialogs & Toasts
    ├── Interactive Resume Modal with downloadable format
    ├── Project Case Study Deep-Dive Modal
    └── Non-blocking Status Toast Notifications
```

---

## 4. Visual Rendering Pipeline & Performance Optimization

```mermaid
graph LR
    subgraph Assets ["1. Asset Optimization"]
        SVG[Inline SVG Icons]
        Fonts[Preconnected Google WebFonts]
        CSSOpt[Minified Zero-Dependency CSS]
    end

    subgraph Compositing ["2. GPU-Accelerated Compositing"]
        Canvas3D[Three.js WebGL Buffer]
        Glassmorphism[backdrop-filter CSS Hardware Layer]
        Transforms[transform: translate3d / will-change]
    end

    subgraph Runtime ["3. DOM & State Execution"]
        ReqAnim[requestAnimationFrame Loop (60 FPS)]
        EventDelegation[Passive Scroll & Resize Listeners]
        DOMUpdates[Microtask Batched DOM Updates]
    end

    Assets --> Compositing
    Compositing --> Runtime
```

---

## 5. Responsive Design & Breakpoint Matrix

The layout utilizes modern CSS Grid and Flexbox with fluid scaling tokens (`clamp()`) to ensure optimal viewing across all hardware profiles:

| Breakpoint Name | Media Query Range | Layout Adjustments |
|---|---|---|
| **Mobile Portrait** | `< 640px` | 1-column layout, compact floating terminal, simplified 3D particle count (400 particles), full-screen navigation drawer. |
| **Tablet Portrait / Large Phone** | `640px - 768px` | 2-column service/stack grid, medium typography scale, optimized touch tap-targets (minimum 48x48px). |
| **Tablet Landscape / Laptop** | `769px - 1024px` | 2 to 3-column portfolio grid, full desktop navigation bar, standard 3D particle density (800 particles). |
| **Desktop High-Res** | `1025px - 1440px` | Full multi-column grid, interactive 3D particle mesh (1200 particles), complete side-by-side terminal & hero layout. |
| **Ultrawide / 4K** | `> 1440px` | Max-width content containment (`1320px`), centered layout with peripheral ambient illumination effects. |

---

## 6. Accessibility (WCAG 2.1 AA) & Security Architecture

### 6.1 Accessibility Principles
- **Color Contrast**: All primary text maintains a minimum contrast ratio of `7:1` against dark backgrounds, exceeding the `4.5:1` WCAG AA threshold.
- **Keyboard Navigation**: Complete focus-visible outlines (`outline: 2px solid #00f2fe`), logical tab indexing, and Escape-key listeners for all modals and dialogs.
- **Screen Reader Support**: Meaningful `aria-label`, `role="region"`, `role="dialog"`, and `aria-expanded` state tracking on interactive components.
- **Reduced Motion Support**: `@media (prefers-reduced-motion: reduce)` automatically disables 3D particle motion, smooth scrolling animations, and continuous keyframe loops.

### 6.2 Security Posture
- **Content Security Policy (CSP)**: Disallows unauthorized external script injection.
- **Zero Third-Party Dependency Vulnerabilities**: Written in pure native web technologies (HTML5, Vanilla CSS3, Vanilla ES6+ JavaScript, standalone Three.js CDN).
- **Client-side Sanitization**: Form inputs sanitized to prevent Cross-Site Scripting (XSS) and injection attacks.