SunCube AI - Comprehensive Documentation

# SunCube AI - Comprehensive Documentation

## 📑 Table of Contents

- [Overview](#overview)
- [Objective](#objective)
- [Platform Architecture Overview](#platform-architecture-overview)
  - [Parent-Child App Structure](#parent-child-app-structure)
  - [Key Design Principles](#key-design-principles)
  - [Hybrid Modular Architecture](#hybrid-modular-architecture)
    - [Architecture Components](#architecture-components)
    - [Implementation Strategy](#implementation-strategy)
- [Design Theme & Branding](#design-theme--branding)
  - [Logo Design](#logo-design)
  - [Color Palette](#color-palette)
  - [Typography](#typography)
  - [Design Style](#design-style)
- [Architecture](#architecture)
  - [Technology Stack](#technology-stack)
  - [Database Architecture](#database-architecture)
    - [Current Implementation: PostgreSQL Database](#current-implementation-postgresql-database-november-4-2025)
    - [PostgreSQL Database Setup](#postgresql-database-setup-implemented-november-3-2025)
    - [Hybrid Upload Tool](#hybrid-upload-tool-implemented-november-4-2025)
    - [Content Management System Implementation](#content-management-system-implementation-november-3-2025)
  - [Application Structure](#application-structure)
  - [Content Management Architecture](#content-management-architecture)
    - [Content Isolation Strategy](#content-isolation-strategy)
    - [Development Environment Setup](#development-environment-setup)
  - [Component Architecture](#component-architecture)
  - [Data Flow](#data-flow)
  - [API Server Management](#api-server-management)
    - [Quick Commands](#quick-commands)
    - [Background Process Features](#background-process-features)
    - [Auto-Start Setup (Optional)](#auto-start-setup-optional)
    - [Server Status Information](#server-status-information)
    - [Workflow Recommendations](#workflow-recommendations)
    - [Troubleshooting](#troubleshooting)
- [Design Principles](#design-principles)
  - [UI/UX Design](#uiux-design)
  - [Code Organization](#code-organization)
  - [Performance Considerations](#performance-considerations)
- [Data Management](#data-management)
  - [Data Structure](#data-structure)
    - [Core Types](#core-types)
  - [Data Sources](#data-sources)
  - [Data Persistence](#data-persistence)
  - [Data Flow Patterns](#data-flow-patterns)
- [Key Features](#key-features)
  - [Study Hub](#study-hub)
  - [Question Bank System](#question-bank-system)
  - [Mock Test System](#mock-test-system)
  - [User Management](#user-management)
  - [Admin Features](#admin-features)
- [User Journey](#user-journey)
- [Business Logic](#business-logic)
  - [Monetization Strategy](#monetization-strategy)
  - [Referral System](#referral-system)
  - [Content Strategy](#content-strategy)
  - [Fraud Prevention (Current Implementation)](#fraud-prevention-current-implementation)
  - [AI Development Safety Measures](#ai-development-safety-measures)
    - [AI-Assisted Development Risks](#ai-assisted-development-risks)
    - [Prevention Strategies](#prevention-strategies)
    - [Validation Procedures](#validation-procedures)
- [Development Setup](#development-setup)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Environment Setup](#environment-setup)
  - [VS Code Workspace Configuration](#vs-code-workspace-configuration)
  - [Development Workflow](#development-workflow)
  - [Zoho Catalyst Deployment (Production)](#zoho-catalyst-deployment-production)
  - [Content Management Workflow](#content-management-workflow)
  - [AI Development Guidelines](#ai-development-guidelines)
- [Future Development Plans](#future-development-plans)
  - [Current Business Focus](#current-business-focus)
  - [Deferred Features (Post-Launch Phase)](#deferred-features-post-launch-phase)
  - [AI Integration](#ai-integration)
  - [Enhanced Features](#enhanced-features)
  - [Technical Improvements](#technical-improvements)
  - [Multi-Exam Expansion](#multi-exam-expansion)
- [File Structure Details](#file-structure-details)
  - [Modular Application Structure](#modular-application-structure)
  - [Content Management Structure](#content-management-structure)
  - [Static Assets](#static-assets)
  - [Development and Deployment](#development-and-deployment)
  - [Key Components](#key-components)
  - [Data Organization](#data-organization)
  - [Context and Hooks](#context-and-hooks)
- [Security Considerations](#security-considerations)
- [Testing Strategy](#testing-strategy)
- [Code Quality Assurance](#code-quality-assurance)
  - [Overview](#overview-1)
  - [Linting and Code Formatting](#linting-and-code-formatting)
    - [ESLint Configuration](#eslint-configuration)
    - [Prettier Configuration](#prettier-configuration)
  - [Type Checking](#type-checking)
    - [TypeScript Strict Mode](#typescript-strict-mode)
  - [Testing Framework](#testing-framework)
    - [Unit Testing](#unit-testing)
    - [Integration Testing](#integration-testing)
    - [End-to-End Testing](#end-to-end-testing)
    - [Test Organization](#test-organization)
  - [Pre-commit Hooks](#pre-commit-hooks)
    - [Husky + lint-staged Setup](#husky--lint-staged-setup)
    - [Hook Commands](#hook-commands)
  - [CI/CD Quality Gates](#cicd-quality-gates)
    - [GitHub Actions Workflow](#github-actions-workflow)
    - [Quality Metrics](#quality-metrics)
  - [Code Review Process](#code-review-process)
    - [Pull Request Template](#pull-request-template)
    - [Review Criteria](#review-criteria)
  - [Performance Monitoring](#performance-monitoring)
    - [Bundle Analysis](#bundle-analysis)
    - [Runtime Performance](#runtime-performance)
  - [Security Scanning](#security-scanning)
    - [Dependency Scanning](#dependency-scanning)
    - [Code Security](#code-security)
  - [Documentation Updates](#documentation-updates)
    - [Automated Documentation](#automated-documentation)
    - [Documentation Quality Checks](#documentation-quality-checks)
  - [Quality Assurance Workflow](#quality-assurance-workflow)
    - [Development Process](#development-process)
    - [Quality Commands](#quality-commands)
    - [Quality Metrics Dashboard](#quality-metrics-dashboard)
  - [Best Practices](#best-practices)
    - [Code Standards](#code-standards)
    - [Development Guidelines](#development-guidelines)
    - [Maintenance](#maintenance)
- [Deployment and Maintenance](#deployment-and-maintenance)
- [📋 Document Guidelines](#-document-guidelines)
  - [How to Use This Document](#how-to-use-this-document)
- [📊 Current Development Status](#-current-development-status)
  - [Database State (November 5, 2025)](#database-state-november-5-2025)
  - [Application Features Status](#application-features-status)
  - [Pending Development](#pending-development)
  - [Known Issues and Limitations](#known-issues-and-limitations)
- [Recent Updates](#recent-updates)
  - [Version Updates and Changes](#version-updates-and-changes)
    - [Hybrid PostgreSQL Approach Documentation (November 5, 2025)](#hybrid-postgresql-approach-documentation-november-5-2025)
    - [Paper 1/Paper 2 Filtering Implementation (November 5, 2025)](#paper-1paper-2-filtering-implementation-november-5-2025)
    - [Hybrid Upload Tool Implementation (November 4-5, 2025)](#hybrid-upload-tool-implementation-november-4-5-2025)
    - [Bulk Question Upload System - Planning Phase (November 4, 2025)](#bulk-question-upload-system---planning-phase-november-4-2025)
    - [API Server Management and Persistence (November 4, 2025)](#api-server-management-and-persistence-november-4-2025)
    - [PostgreSQL Migration and Flat File Removal (November 4, 2025)](#postgresql-migration-and-flat-file-removal-november-4-2025)
    - [PostgreSQL Integration Implementation (November 3, 2025)](#postgresql-integration-implementation-november-3-2025)
    - [Database-Backed Content Management System Implementation (November 3, 2025)](#database-backed-content-management-system-implementation-november-3-2025)
    - [Data Migration Scripts Implementation (November 3, 2025)](#data-migration-scripts-implementation-november-3-2025)
    - [Modular Architecture Implementation (November 3, 2025)](#modular-architecture-implementation-november-3-2025)
    - [Business Strategy Refinement (November 3, 2025)](#business-strategy-refinement-november-3-2025)
    - [Design Theme Implementation (October 31, 2025)](#design-theme-implementation-october-31-2025)
    - [Logo Optimization for Mobile (October 31, 2025)](#logo-optimization-for-mobile-october-31-2025)
    - [Question Bank Interface Implementation (November 3, 2025)](#question-bank-interface-implementation-november-3-2025)
- [Bulk Question Upload System](#bulk-question-upload-system)
  - [Overview](#overview-2)
  - [Admin Question Management Structure](#admin-question-management-structure)
    - [1. Questions Tab (CRUD Operations)](#1-questions-tab-crud-operations)
    - [2. Bulk Upload Tab (NEW)](#2-bulk-upload-tab-new)
    - [3. Upload History Tab (NEW)](#3-upload-history-tab-new)
  - [Database Schema for Bulk Upload](#database-schema-for-bulk-upload)
    - [New Tables](#new-tables)
  - [JSON File Format](#json-file-format)
  - [Bulk Upload Workflow](#bulk-upload-workflow)
  - [Technical Implementation](#technical-implementation)
    - [Backend API Endpoints](#backend-api-endpoints)
    - [Frontend Components](#frontend-components)
  - [UI Design (SunCube Theme)](#ui-design-suncube-theme)
  - [Best Practices & Guidelines](#best-practices--guidelines)
    - [For Administrators](#for-administrators)
    - [Data Integrity](#data-integrity)
    - [Performance](#performance)
  - [Common Use Cases](#common-use-cases)
    - [1. Initial Data Population](#1-initial-data-population)
    - [2. Update Existing Questions](#2-update-existing-questions)
    - [3. Review Pending Questions](#3-review-pending-questions)
  - [Troubleshooting](#troubleshooting-1)
    - [Upload Fails with Validation Errors](#upload-fails-with-validation-errors)
    - [Duplicate Questions Detected](#duplicate-questions-detected)
    - [Hindi Characters Not Displaying](#hindi-characters-not-displaying)
    - [Upload Takes Too Long](#upload-takes-too-long)
- [📚 Related Documentation](#-related-documentation)
  - [Database and Backend](#database-and-backend)
  - [Upload and Data Management](#upload-and-data-management)
  - [Business and Design](#business-and-design)
  - [Development Guidelines](#development-guidelines-1)
- [🔄 Documentation Maintenance Workflow](#-documentation-maintenance-workflow)
  - [When Planning New Features](#when-planning-new-features)
  - [During Development](#during-development)
  - [After Completing Development](#after-completing-development)
  - [Example Documentation Update Commit Message](#example-documentation-update-commit-message)
- [🎯 Development Best Practices](#-development-best-practices)
  - [Code Organization](#code-organization-1)
  - [Database Operations](#database-operations)
  - [Component Development](#component-development)
  - [Testing Requirements](#testing-requirements)
  - [Version Control](#version-control)
  - [AI-Assisted Development](#ai-assisted-development-1)
- [🚀 Quick Start for New Developers](#-quick-start-for-new-developers)
  - [First-Time Setup](#first-time-setup)
- [🔒 Comprehensive Backup & Disaster Recovery Plan](#-comprehensive-backup--disaster-recovery-plan)
  - [Overview](#overview-3)
  - [Backup Philosophy](#backup-philosophy)
  - [1. Database Backup Strategy (PostgreSQL)](#1-database-backup-strategy-postgresql)
    - [A. Automated Continuous Backups](#a-automated-continuous-backups)
    - [B. NPM Scripts for Database Backups](#b-npm-scripts-for-database-backups)
    - [C. Database Restore Procedure](#c-database-restore-procedure)
    - [D. Cloud Backup Strategy (Production)](#d-cloud-backup-strategy-production)
  - [2. Code Repository Backup (Git)](#2-code-repository-backup-git)
    - [A. Primary Repository Protection](#a-primary-repository-protection)
    - [B. Secondary Remote Repositories](#b-secondary-remote-repositories)
    - [C. Local Code Archives](#c-local-code-archives)
  - [3. Configuration & Secrets Backup](#3-configuration--secrets-backup)
    - [A. Environment Variables Backup](#a-environment-variables-backup)
    - [B. Documentation Backup](#b-documentation-backup)
  - [4. Disaster Recovery Procedures](#4-disaster-recovery-procedures)
    - [Scenario 1: Database Corruption](#scenario-1-database-corruption)
    - [Scenario 2: Accidental Code Deletion](#scenario-2-accidental-code-deletion)
    - [Scenario 3: Complete System Failure](#scenario-3-complete-system-failure)
  - [5. Backup Storage Locations](#5-backup-storage-locations)
    - [Local Backups (Development Environment)](#local-backups-development-environment)
    - [Cloud Backups (Production)](#cloud-backups-production)
  - [6. Quick Reference - Backup Commands](#6-quick-reference---backup-commands)
  - [7. Backup Checklist for Developers](#7-backup-checklist-for-developers)
    - [Before Major Changes](#before-major-changes)
    - [Weekly Maintenance](#weekly-maintenance)
    - [Monthly Tasks](#monthly-tasks)
    - [Quarterly Tasks](#quarterly-tasks)
  - [Summary](#summary)
- [Essential Commands](#essential-commands)
- [Understanding the Codebase](#understanding-the-codebase)
- [Making Your First Contribution](#making-your-first-contribution)

---

## Overview

**SunCube AI** is an AI-first EduTech platform designed for comprehensive exam preparation, specifically targeting the Central Teacher Eligibility Test (CTET). The application provides a complete study ecosystem with interactive materials, question banks, mock tests, and user management features.

The platform follows a **hybrid modular architecture** where SunCube AI serves as the parent platform hosting multiple exam preparation applications (starting with CTET/EasyCTET). This approach enables content isolation, non-disruptive updates, and scalable expansion to additional exams.

## Objective

The primary objective of SunCube AI is to revolutionize teacher exam preparation by:

1. **Providing Comprehensive Study Materials**: Detailed, chapter-wise content covering the complete CTET syllabus across all subjects
2. **Enabling Interactive Learning**: Through question banks with detailed explanations and comprehension passages
3. **Offering Realistic Practice**: Via configurable mock tests that simulate real exam conditions
4. **Facilitating Personalized Learning**: With user profiles, progress tracking, and adaptive content
5. **Building Community**: Through referral systems and user engagement features
6. **Leveraging AI**: Future integration of AI-powered features for personalized learning paths and intelligent assessments
7. **Ensuring Content Safety**: Strict modular boundaries and AI development safety measures prevent cross-contamination
8. **Supporting Scalable Growth**: Modular architecture allows seamless addition of new exam applications

## Platform Architecture Overview

### Parent-Child App Structure
- **SunCube AI (Parent)**: Core platform providing shared services, user management, payments, and navigation
- **Exam Apps (Children)**: Specialized applications for specific exams (CTET, SSC, Banking, etc.)
- **Content Management System**: Centralized system for content creation, versioning, and deployment

### Key Design Principles
1. **Content Isolation**: Each exam app maintains independent content without cross-contamination
2. **Non-Disruptive Updates**: Content updates don't affect other apps or platform stability
3. **Scalable Architecture**: Easy addition of new exam apps without platform refactoring
4. **Shared Services**: Common functionality (auth, payments, analytics) shared across apps
5. **Version Control**: Content versioning with rollback capabilities
6. **AI Safety**: Strict protocols for AI-assisted development to prevent unintended changes

### Hybrid Modular Architecture

#### Architecture Components

**1. Core Platform (SunCube AI)**
- User authentication and profiles
- Payment processing and subscriptions
- Referral system and commissions
- Analytics and reporting
- App discovery and navigation
- Shared UI components and themes

**2. Exam Modules (Plugin Architecture)**
- Independent content modules for each exam
- Isolated data structures and APIs
- Module-specific routing and navigation
- Dedicated content management interfaces
- Version-controlled content deployment

**3. Content Management System (CMS)**
- Centralized content authoring and editing
- Version control and approval workflows
- Automated content validation and testing
- Scheduled deployment with rollback capabilities
- Content analytics and performance monitoring

#### Implementation Strategy

**Phase 1: Foundation (Current - CTET Only)**
```
SunCube AI Platform
├── Core Services (Auth, Payments, Analytics)
├── CTET Module (Integrated)
└── Content Management (Basic)
```

**Phase 2: Modularization (Adding 2nd Exam)**
```
SunCube AI Platform
├── Core Services (Auth, Payments, Analytics)
├── Module Registry
├── CTET Module (Isolated)
├── SSC Module (New)
└── Content Management System
```

**Phase 3: Full CMS (3+ Exams)**
```
SunCube AI Platform
├── Core Services
├── Module Registry & Loader
├── Content Management System
│   ├── Content Authoring
│   ├── Version Control
│   └── Deployment Pipeline
├── CTET Module
├── SSC Module
├── Banking Module
└── UPSC Module
```

## Design Theme & Branding

### Logo Design
The SunCube AI logo features a sleek, modern design with a 3D wireframe cube and three visible faces:

- **Front face**: Deep Purple (#4B0082) with letter "S" in white Montserrat Bold
- **Top face**: Light Purple (#D8BFD8) with letter "U" in white Montserrat Bold
- **Side face**: Soft Gray (#666666) with letter "N" in white Montserrat Bold
- **Brand Name**: "SunCube AI" in Deep Purple Poppins SemiBold below the cube
- **Tagline**: "An AI-first EduTech Enterprise" in Soft Gray Montserrat Light Italic
- **Style**: Minimalistic, geometric, and tech-inspired with white/transparent background

### Color Palette
- **Primary Color**: Deep Purple (#4B0082) - headers, buttons, key highlights
- **Secondary Color**: Light Purple (#D8BFD8) - backgrounds, cards, accents
- **Neutral Color**: Soft Gray (#666666) - body text, borders, subtle UI elements
- **Background**: White or transparent for clean, minimalistic look

### Typography
- **Headings & Brand Name**: Poppins SemiBold
- **Body Text**: Montserrat Regular
- **Taglines & Subtext**: Montserrat Light Italic

### Design Style
- Minimalistic, geometric, and tech-inspired
- Clean lines, subtle shadows, and responsive layout
- Prioritizes accessibility and readability
- Mobile-optimized with responsive logo sizing

## Architecture

### Technology Stack

- **Frontend Framework**: React 19 with TypeScript
- **Build Tool**: Vite
- **Styling**: Tailwind CSS with custom theme
- **State Management**: React Context API
- **Data Persistence**: Browser localStorage (current), PostgreSQL (planned)
- **Deployment Platform**: Static hosting (current), Zoho Catalyst (planned)
- **AI Integration**: Google Gemini API (planned/configured)
- **Content Management**: Modular CMS with version control and rollback capabilities

### Database Architecture

#### Current Implementation: PostgreSQL Database (November 4, 2025)
The application is now **fully database-driven** using PostgreSQL as the primary data source with API-first architecture. All flat file dependencies have been removed.

**Current Database State (November 4, 2025):**
- **Total Questions**: 45 questions uploaded
  - Child Development: 30 questions (4 chapters)
  - Mathematics & Science: 5 questions (1 chapter)
  - Social Studies: 5 questions (1 chapter)
  - English: 5 questions (1 chapter)
- **Total Chapters**: 8 chapters across 4 subjects
- **Upload Method**: Hybrid Upload Tool (UI validation + SQL generation)
- **Data Status**: ✅ All questions visible in Study Hub, Admin Panel, Question Bank, and Mock Tests

**Current Data Storage (PostgreSQL):**
- **ctet.questions**: All exam questions with metadata, options, correct answers, explanations (45 rows)
- **ctet.chapters**: Chapter information with summaries and subject organization (8 rows)
- **ctet.upload_history**: Bulk upload tracking with detailed reports
- **ctet.comprehension_passages**: Comprehension passages linked to questions (planned)
- **User Data**: Authentication state, profile information, payment status (localStorage)
- **User Progress**: Chapter completion and test results (planned)
- **Referral Data**: Commission tracking and earnings (localStorage)

**Data Management:**
- **API Server**: Express.js REST API serving data from PostgreSQL (port 9998)
- **Endpoints**: 
  - `GET /api/questions` - Returns all 45 questions with chapter JOIN
  - `GET /api/chapters` - Returns all 8 chapters
  - `POST /api/admin/validate-upload` - Validates JSON before upload
  - `POST /api/admin/bulk-upload` - Processes bulk upload (currently disabled - using SQL instead)
  - `GET /api/admin/upload-history` - Returns upload history
- **CRUD Operations**: Full create, read, update, delete via API endpoints
- **Data Upload**: Hybrid Upload Tool (JSON validation → SQL generation → pgAdmin execution)
- **Backup Strategy**: PostgreSQL automated backups with point-in-time recovery
- **Cache Layer**: localStorage cache for offline access with "Refresh DB" button

#### PostgreSQL Database Setup (Implemented November 3, 2025)
PostgreSQL has been implemented with comprehensive schema design supporting modular architecture and future scaling requirements.

**PostgreSQL Setup (Windows Native Installation):**
```yaml
# PostgreSQL 18 installed natively on Windows
# Host: localhost
# Port: 5433 (non-default to avoid conflicts)
# Database: suncube_ai_dev
# User: developer
# Password: devpassword

# Database Schemas:
# - core: Platform core tables (users, payments, referrals)
# - ctet: CTET-specific content (questions, chapters, passages)
# - cms: Content management system tables
# - analytics: Analytics and tracking data

# Current Data State:
# - ctet.questions: 45 rows
# - ctet.chapters: 8 rows
# - ctet.upload_history: 1 row (CDP upload - 30 questions)
```

**API Server:**
```javascript
// api-server.js - Express API serving PostgreSQL data
const express = require('express');
const { Pool } = require('pg');

const pool = new Pool({
  host: 'localhost',
  port: 5433,
  database: 'suncube_ai_dev',
  user: 'developer',
  password: 'devpassword'
});

// Returns all questions with chapter details
app.get('/api/questions', async (req, res) => {
  const result = await pool.query(`
    SELECT
      q.id, q.chapter_id, q.question_number, q.subject, 
      q.paper_type as paper, q.question, q.options, 
      q.correct_answer, q.explanation, q.passage_id,
      'Dec 2024' as term,
      c.title as chapter_title, c.subject as chapter_subject
    FROM ctet.questions q
    LEFT JOIN ctet.chapters c ON q.chapter_id = c.id
    ORDER BY q.subject, q.chapter_id, q.question_number
  `);
  res.json(result.rows); // Returns 45 questions
});

// Returns all chapters
app.get('/api/chapters', async (req, res) => {
  const result = await pool.query(`
    SELECT id, subject, title, summary, order_index
    FROM ctet.chapters
    ORDER BY order_index
  `);
  res.json(result.rows); // Returns 8 chapters
});
```

**Database Schema Design (Implemented):**
Complete PostgreSQL schema with modular architecture supporting CTET, core, CMS, and analytics schemas. See `scripts/schema.sql` for full implementation details.

**Data Migration Status (✅ Completed November 4, 2025):**
- ✅ **Removed all flat file dependencies** from application
- ✅ **App.tsx** now fetches chapters from `/api/chapters` and builds Study Hub dynamically
- ✅ **Study Hub** displays 4 subjects, 8 chapters, 45 questions from PostgreSQL
- ✅ **Admin Panel** shows all 45 questions with filters (subject, term, language, status)
- ✅ **Question Bank** displays all questions from database
- ✅ **Mock Tests** work with uploaded questions
- ✅ **dataManager.ts** no longer falls back to flat files
- ✅ **Question interface** updated with database fields (`chapter_id`, `passage_id`, etc.)
- ✅ **Refresh DB button** added for cache clearing and data reload
- ✅ **Hybrid Upload Tool** created for bulk uploads via SQL
- ✅ **Data flow**: PostgreSQL → API Server → React UI → localStorage cache
- ✅ **30 CDP questions uploaded** successfully via Hybrid Upload Tool
- ⏳ **Remaining uploads**: English (90q), Hindi (90q), Math/Science (120q), SST (120q)
- ⏳ **Passages table**: Creation and content migration (next phase)

#### Hybrid Upload Tool (Implemented November 4, 2025)

**Location**: Admin Page → Bulk Upload tab

**Upload Process**:
1. **Upload JSON file** with questions and chapters
2. **UI validates** structure, fields, language detection
3. **Generate SQL script** with proper schema mapping
4. **Download SQL file** to local machine
5. **Execute in pgAdmin** to insert data
6. **Verify in Admin Panel** using "Refresh DB" button

**Features**:
- ✅ File upload with drag & drop
- ✅ Metadata auto-detection (subject, term from filename)
- ✅ Client-side validation (required fields, data types)
- ✅ SQL script generation with proper type conversion (JSONB → text[], auto-increment IDs)
- ✅ Copy to clipboard and download buttons
- ✅ Upload statistics display
- ✅ Comprehensive documentation in `docs/Hybrid-Upload-Guide.md`

**SQL Generation Features**:
- Auto-increment chapter IDs with RETURNING clause
- JSONB to PostgreSQL array conversion for options
- Duplicate detection based on chapter_id + question_number
- Batch processing with transaction handling
- Upload history tracking

#### Content Management System Implementation (November 3, 2025)

**CMS Architecture:**
- **Service Layer**: `ContentManagementService` with full database operations for content versioning and approvals
- **React Hooks**: Custom hooks for content creation, approval workflow, version history, and statistics
- **UI Components**: Content editor, approval queue, version history browser, and statistics dashboard
- **Admin Integration**: CMS fully integrated into admin panel with tabbed interface

**Content Authoring:**
- **Dynamic Forms**: Schema-driven content creation for different content types (questions, chapters, lessons)
- **Version Control**: Automatic versioning with change summaries and metadata tracking
- **Validation**: Form validation with required fields and data type checking
- **Rich Text Support**: Support for formatted content and structured data

**Approval Workflow:**
- **Multi-Step Process**: Content submission → pending review → approved/rejected → published
- **Reviewer Interface**: Dedicated approval queue with content preview and decision tracking
- **Audit Trail**: Complete history of approvals, rejections, and reviewer comments
- **Status Management**: Real-time status updates and workflow progression

**Version Management:**
- **Version History**: Complete version timeline with change summaries and timestamps
- **Rollback Capability**: Point-in-time content restoration and version comparison
- **Content Diff**: Side-by-side version comparison for change visualization
- **Version Metadata**: Author information, timestamps, and change descriptions

**Statistics & Monitoring:**
- **Content Metrics**: Total content items, versions, approval status, and publication tracking
- **Workflow Analytics**: Approval queue status, reviewer productivity, and content velocity
- **Quality Metrics**: Content approval rates, rejection reasons, and improvement trends
- **Real-time Dashboard**: Live statistics with filtering and export capabilities

**Technical Implementation:**
- **Environment Detection**: Browser-compatible code with Node.js environment checks
- **Error Handling**: Comprehensive error handling with user-friendly messages
- **Performance Optimization**: Efficient database queries and React state management
- **Security**: Input validation, SQL injection prevention, and access control

### Application Structure

```
src/
├── components/         # React components
│   ├── AdminPage.tsx  # Admin interface with CMS integration
│   ├── App.tsx        # Main app with PostgreSQL integration
│   ├── ChapterView.tsx # Chapter display (from PostgreSQL)
│   ├── ChapterList.tsx # Chapter navigation
│   ├── MockTestPage.tsx # Mock tests (from PostgreSQL)
│   └── QuestionBank.tsx # Question bank (from PostgreSQL)
├── context/           # React contexts
│   └── AuthContext.tsx # Authentication
├── data/              # Data layer (now API-based)
│   └── dataManager.ts # API client for PostgreSQL
├── hooks/             # Custom React hooks
│   └── useQuestionBank.ts # Questions hook (API-based)
├── types.ts           # TypeScript type definitions
├── api-server.js      # Express API server (PostgreSQL)
└── App.tsx            # Root component

docs/                   # Documentation
├── PostgreSQL-Configuration.md
├── PostgreSQL-Connection-and-Testing.md
├── PostgreSQL-Migration-Summary.md
├── Content-Management-Approach.md
├── SunCube-AI-Business-Plan.md
└── SunCube-AI-Documentation.md

data/ (archived)        # Flat files (archived, no longer used at runtime)
├── studyData.ts       # Historical data reference
├── child-development/ # Historical chapter files
├── english/           # Historical chapter files
├── math-science/      # Historical chapter files
├── social-studies/    # Historical chapter files
└── hindi/             # Historical chapter files
```

### Content Management Architecture

#### Content Isolation Strategy

**Database Design:**
- **Shared Tables**: Users, payments, referrals, platform analytics
- **Isolated Tables**: Exam-specific content with proper namespacing
- **Content Metadata**: Version tracking, approval status, deployment history

**Content Versioning:**
- Semantic versioning for content releases (e.g., CTET-v2.1.0)
- Content snapshots before major updates
- Rollback capabilities to previous versions
- Audit trail for all content changes

#### Development Environment Setup

**Local Development with PostgreSQL:**
- Native PostgreSQL 18 installation on Windows
- Database: `suncube_ai_dev` on port 5433
- Service: `postgresql-x64-18`
- See `PostgreSQL-Configuration.md` for complete setup details

**VS Code Multi-Root Workspace:**
- Separate workspace folders for core platform and exam modules
- ESLint rules preventing cross-module imports
- Module-specific settings and configurations

### Component Architecture

- **App.tsx**: Root component managing routing and main layout
- **AuthProvider**: Context provider for authentication state
- **useQuestionBank**: Custom hook for question bank management
- **CMS Components**: Content editor, approval queue, version history, and statistics dashboard
- **Modular Components**: Each feature area has dedicated components
- **Content Management**: Centralized CMS with authoring, versioning, and deployment

### Data Flow

1. **PostgreSQL Database**: Primary data source for questions, chapters, and passages
2. **API Server**: Express.js server (port 9998) serving data from PostgreSQL
3. **User Authentication**: Managed through AuthContext with localStorage persistence
4. **Question Bank**: CRUD operations via API with PostgreSQL backend
5. **Content Management**: Version-controlled content updates with rollback capabilities
6. **Module Isolation**: Strict boundaries prevent cross-exam contamination
7. **AI Safety**: Validation procedures prevent unintended AI-assisted changes
8. **Cache Layer**: localStorage cache for offline capability (optional fallback)

### API Server Management

The application uses a persistent Express.js API server that connects the frontend to PostgreSQL. Multiple management options are available:

#### Quick Commands
```bash
# Start API server (runs in background, survives terminal closure)
npm run api:start

# Check server status and health
npm run api:status

# Stop API server
npm run api:stop

# Start both API and frontend together
npm start
```

#### Background Process Features
- **Persistent Process**: Runs in hidden background window
- **Terminal Independence**: Survives terminal closure
- **Process Management**: Saves PID to `logs/api-server.pid`
- **Logging**: Output saved to `logs/api-server-YYYY-MM-DD.log`
- **Health Monitoring**: Built-in health check endpoint at `/api/health`

#### Auto-Start Setup (Optional)
For automatic startup after machine restarts:

```powershell
# Run as Administrator
.\scripts\setup-api-autostart.ps1
```

Creates Windows Scheduled Task that:
- Starts automatically on system boot
- Starts automatically on user login
- Auto-restarts on failure (3 retry attempts)
- Runs with elevated privileges

**Manage Auto-Start:**
```powershell
# Disable auto-start (as Administrator)
.\scripts\disable-api-autostart.ps1

# Re-enable auto-start (as Administrator)
.\scripts\enable-api-autostart.ps1
```

#### Server Status Information
The `npm run api:status` command displays:
- Port listening status (9998)
- Process ID and uptime
- API health endpoint status
- Database connection status
- Number of questions in database

#### Workflow Recommendations

**Development Workflow:**
```bash
# Option 1: Single command for both servers
npm start

# Option 2: Separate control
npm run api:start  # Start API once
npm run dev        # Start/restart frontend as needed
```

**Production/Demo Setup:**
```bash
# One-time setup (as Administrator)
.\scripts\setup-api-autostart.ps1

# Server auto-starts on boot
# Only need to run frontend: npm run dev
```

#### Troubleshooting

**If API won't start:**
```bash
# Check if port is already in use
npm run api:status

# Stop any existing instance
npm run api:stop

# Start fresh
npm run api:start
```

**If frontend can't connect to API:**
1. Verify API is running: `npm run api:status`
2. Check environment variable: `VITE_API_URL=http://localhost:9998/api` in `.env.local`
3. Restart API if needed: `npm run api:stop && npm run api:start`

**After machine restart (without auto-start):**
```bash
# Manually start API server
npm run api:start
```

For complete API server documentation, see: **`docs/API-Server-Management.md`**

## Design Principles

### UI/UX Design

- **Mobile-First Approach**: Fully responsive design optimized for mobile devices
- **Purple Theme**: Custom color scheme with deep-purple (#4B0082) and light-purple (#D8BFD8)
- **Typography**: Montserrat for body text, Poppins for headings
- **Clean Interface**: Minimalist design with focus on content readability
- **Progressive Disclosure**: Information revealed contextually to avoid overwhelming users
- **Mobile Logo Optimization**: Responsive logo sizing with transparent background for clean header integration
- **Branding**: Custom favicon/logo for professional browser tab appearance

### Code Organization

- **Component-Based Architecture**: Modular, reusable React components
- **Type Safety**: Comprehensive TypeScript usage for type safety
- **Separation of Concerns**: Clear separation between UI, business logic, and data management
- **Custom Hooks**: Encapsulation of complex logic in reusable hooks
- **Context Pattern**: Global state management for authentication and user data

### Performance Considerations

- **Lazy Loading**: Components loaded as needed
- **Efficient Re-renders**: Proper use of React hooks and memoization
- **Local Storage Optimization**: Minimal data storage with efficient serialization
- **Bundle Optimization**: Vite's tree-shaking and code splitting

## Data Management

### Data Structure

#### Core Types

```typescript
interface Question {
  id: string;
  questionNumber: number;
  subject: string;
  paper: string; // "Paper 1" or "Paper 2"
  question: string;
  options: string[];
  correctAnswer: number;
  explanation: string;
}

interface Chapter {
  id: number;
  subject: string;
  title: string;
  summary: string;
  questions: Question[];
  passages?: ComprehensionPassage[];
}

interface User {
  username: string;
  hasPaid: boolean;
  onboardingCompleted: boolean;
  role: 'teacher' | 'learner';
  // Optional progressive profiling fields
  gender?: string;
  mobileNumber?: string;
  countryCode?: string;
  postalCode?: string;
  country?: string;
  residencyStatus?: string;
  wantsCommunication?: boolean;
  // Teacher-specific fields
  schoolName?: string;
  schoolPostalCode?: string;
  teachingLevels?: string[];
  subjects?: string[];
  educationQualification?: string;
  teacherEducationCourse?: string;
  // Referral system
  referralCode: string;
  referredBy?: string;
  referrals: Referral[];
  referralEarnings: number;
}
```

### Data Sources

1. **Static Study Data**: Pre-defined content in TypeScript modules organized by subject
2. **User-Generated Content**: Questions can be added/modified via admin interface
3. **User Data**: Authentication and profile information
4. **Session Data**: Current user state and preferences

### Data Persistence

- **localStorage**: Primary storage mechanism for:
  - User authentication data
  - Modified question bank
  - User preferences
  - All users data (for admin referral management)

- **Data Manager**: Centralized data management with functions for:
  - Loading default data
  - Saving modifications
  - Resetting to defaults
  - ID generation for questions

### Data Flow Patterns

1. **Initial Load**: Static data loaded from modules, processed, and stored in localStorage
2. **CRUD Operations**: Question modifications tracked and persisted
3. **User Management**: Authentication state and user profiles managed via context
4. **Referral System**: Commission tracking and payout management

## Key Features

### Study Hub
- **Subject Organization**: Content organized by 5 main subjects
- **Chapter Navigation**: Hierarchical navigation through subjects and chapters
- **Content Display**: Rich text summaries with key concepts
- **Question Integration**: Inline questions with explanations

### Question Bank System
- **Dedicated Interface**: Standalone Question Bank page accessible from main navigation
- **Search & Filtering**: Full-text search through questions and answers, filter by subject and exam term
- **Exam Term Display**: Shows CTET exam terms (e.g., "Dec 2024") for all questions
- **Data Sharing**: Uses same data source as chapter views for consistency
- **Premium Access**: Requires payment for access to question bank
- **Dynamic Loading**: Questions loaded from shared dataManager for all Paper 2 content
- **Admin Management**: CRUD operations for question maintenance via useQuestionBank hook
- **Change Tracking**: Modifications tracked for potential synchronization

### Mock Test System
- **Configurable Tests**: Customizable test parameters
- **Timer Functionality**: Realistic exam timing
- **Results Analysis**: Performance tracking and feedback
- **Paper-Specific**: Separate preparation for Paper 1 and Paper 2

### User Management
- **Authentication**: Email-based login/registration
- **Progressive Profiling**: Optional user information collection
- **Referral Program**: 10% commission system (₹499 mock test price)
- **Role-Based Access**: Different features for teachers vs learners

### Admin Features
- **User Management**: View and manage all users
- **Referral Payouts**: Process referral commissions
- **Content Management**: Modify question bank
- **CMS Integration**: Full content management system with authoring, approvals, versioning, and statistics
- **Analytics**: User and content statistics

## User Journey

1. **Discovery**: User lands on marketing-focused landing page
2. **Registration**: Email-based signup with optional referral code
3. **Onboarding**: Progressive profile completion
4. **Study Selection**: Choose between Paper 1 or Paper 2 preparation
5. **Question Bank Access**: Browse all questions with search and filtering capabilities
6. **Chapter Study**: Navigate subjects and chapters, practice questions
7. **Practice**: Take mock tests to assess readiness
8. **Premium Access**: Pay for full access to premium features
9. **Referral**: Earn commissions by referring others

## Business Logic

### Monetization Strategy
- **One-Time Payment Model**: Simple, trust-based transactions with manual verification
- **Content Publishing Focus**: Priority on delivering comprehensive study materials
- **Referral Commissions**: 10% commission system for teacher referrals
- **Future Expansion**: Advanced account sharing controls (deferred to post-launch)

### Access Control System

**Implemented:** November 6, 2025  
**Status:** ✅ Production Ready

A comprehensive database-driven access control system providing scalable freemium and paper-level access management.

#### Architecture

**Database Table: `core.product_access`**
```sql
- user_id UUID (FK to core.users)
- product_type VARCHAR(50) ('paper', 'chapter', 'course', 'mock-test')
- product_key VARCHAR(255) ('paper1', 'chapter:101', etc.)
- access_type VARCHAR(50) ('purchased', 'freemium', 'trial', 'granted')
- price, purchased_at, expires_at, source
- 4 performance-optimized indexes
```

#### Access Tiers

| Tier | Paper 1 | Paper 2 | Mock Tests | Question Bank |
|------|---------|---------|------------|---------------|
| **Freemium** | Chapter 1 FREE | Chapter 1 FREE | 10 questions | 10 questions |
| **Paper 1** | Full Access | Chapter 1 FREE | 60 questions | Unlimited |
| **Paper 2** | Chapter 1 FREE | Full Access | 60 questions | Unlimited |
| **Both Papers** | Full Access | Full Access | 60 questions | Unlimited |

#### Key Features

✅ **Freemium Model**: Chapter 1 of all subjects free for all users (Chapter ID % 100 === 1)  
✅ **Granular Control**: Paper-level AND chapter-level access permissions  
✅ **Scalable Design**: Easy to add courses, bundles, trials, subscriptions  
✅ **Performance**: Indexed database queries for fast access checks  
✅ **Backward Compatible**: Dual-write to old columns during transition period  
✅ **API-First**: RESTful endpoints for access management  

#### API Endpoints

```bash
# Check user access
GET /api/access/check?productType=paper&productKey=paper1

# User info with access details
GET /api/auth/me  # Returns productAccess field

# Admin operations
POST /api/admin/access/grant    # Grant access
DELETE /api/admin/access/revoke/:userId/:productType/:productKey  # Revoke
```

#### Frontend Integration

```typescript
import { useAuth } from './context/AuthContext';

const { hasAccess, user } = useAuth();

// Check paper access
const hasPaper1 = user?.productAccess?.ownsPaper1;

// Check chapter access
const canAccess = hasAccess('chapter', 'chapter:102');
```

#### Components Updated

- **ChapterList**: Shows FREE badges, lock icons based on access
- **ChapterView**: Premium overlay when content is locked
- **MockTestPage**: Enforces question limits (10 freemium, 60 paid)
- **MockTestConfig**: Locks 30/60 question options for freemium
- **QuestionBank**: Filters and limits based on access level
- **PaperSelector**: Displays appropriate access messages

#### Testing

**Automated Tests:** 20/20 passing ✅
- Freemium access validation
- Paper-level access checks
- Chapter-level access checks
- Database consistency verification
- API endpoint validation

**Documentation:**
- Implementation Guide: `docs/ACCESS_CONTROL_MATRIX.md`
- Design Document: `docs/ACCESS_CONTROL_DESIGN.md`
- Testing Guide: `docs/MANUAL_TESTING_GUIDE.md`
- QA Checklist: `docs/QA_CHECKLIST.md`

#### Migration Status

- ✅ Database table created with 4 indexes
- ✅ 5 user records migrated (3 Paper 1, 2 Paper 2)
- ✅ API endpoints implemented
- ✅ Frontend components updated
- ✅ All tests passing
- ✅ Comprehensive documentation completed

### Referral System
- **Teacher-Focused**: Verified teachers with educational credentials
- **Commission Tracking**: Automatic calculation and tracking of earnings (10% of successful referrals)
- **Payout Management**: Admin interface for processing payments
- **Multi-level**: Supports nested referral relationships

### Content Strategy
- **CTET-Focused**: Specifically designed for teacher eligibility exams
- **Paper Differentiation**: Separate content tracks for Paper 1 (primary) and Paper 2 (upper primary)
- **Comprehensive Coverage**: All major subjects and topics included
- **Quality Assurance**: Detailed explanations and accurate content
- **Modular Architecture**: Enables seamless addition of new exam types

### Fraud Prevention (Current Implementation)
- **Payment Verification**: Manual admin review for all transactions
- **Transaction Tracking**: UPI reference number validation
- **Account Sharing Controls**: Deferred to future development phase
- **Referral Monitoring**: Source verification for teacher referrers

### AI Development Safety Measures

#### AI-Assisted Development Risks
AI tools can inadvertently cause unintended changes due to:
1. **Context Overreach**: AI modifying related but unrelated components
2. **Pattern Matching Issues**: AI applying changes to similar code patterns
3. **Import/Dependency Changes**: AI updating shared dependencies
4. **Refactoring Cascade**: AI changes propagating beyond intended scope

#### Prevention Strategies
- **Scoped Prompts**: Always specify exact files and components
- **Change Verification**: Never accept AI changes without review
- **Incremental Changes**: Break large changes into smaller updates
- **Pre-commit Hooks**: Automated validation before commits
- **Module Boundaries**: Strict isolation prevents cross-contamination

#### Validation Procedures
- **Pre-AI-Change**: Create backups and define scope clearly
- **Post-AI-Change**: Review all modified files and run tests
- **Module Isolation**: Ensure changes don't affect other exam modules
- **Rollback Ready**: Maintain ability to revert changes quickly

## Development Setup

### Prerequisites
- Node.js (LTS version)
- npm or yarn
- PostgreSQL 18 (local installation)
- VS Code (recommended IDE)
- Git

### Installation
```bash
# Clone repository
git clone <repository-url>
cd suncube-ai

# Install dependencies
npm install
```

### Environment Setup

**Current Development Setup:**
The application currently uses localStorage for data persistence and requires no database setup for development.

**Implemented Database Setup:**
PostgreSQL has been implemented for future scaling with the following environment configuration:
```bash
# .env.local (for development)
DATABASE_URL=postgresql://developer:devpassword@localhost:5433/suncube_ai_dev
DB_HOST=localhost
DB_PORT=5433
DB_NAME=suncube_ai_dev
DB_USER=developer
DB_PASSWORD=devpassword

# AI Integration
GEMINI_API_KEY=your_gemini_api_key_here

# Application
NODE_ENV=development
VITE_API_URL=http://localhost:3000/api
```

**Database Migration (Implemented):**
Automated migration scripts have been created to transition from localStorage to PostgreSQL while preserving all user data. See `scripts/migrate-data.js` for the complete migration implementation.

### VS Code Workspace Configuration

**Multi-Root Workspace Setup:**
1. Open VS Code
2. File → Save Workspace As → `suncube-ai.code-workspace`
3. Configure workspace settings for module isolation

**Essential Extensions:**
- ESLint
- Prettier
- TypeScript Importer
- Path Intellisense
- Git Graph
- Todo Tree

**Workspace Settings:**
```json
{
  "git.ignoreLimitWarning": true,
  "eslint.workingDirectories": [
    "src/modules/ctet",
    "src/modules/ssc",
    "src/core"
  ],
  "typescript.preferences.includePackageJsonAutoImports": false
}
```

### Development Workflow
```bash
# Start development server
npm run dev

# Run tests
npm run test

# Build for production
npm run build
```

**Database Development Workflow (Implemented):**
PostgreSQL has been implemented with the following workflow:
```bash
# Initialize database (Windows)
npm run db:init

# Start database services
npm run db:start

# Run data migration
npm run migrate

# Run dry-run migration (preview changes)
npm run migrate:dry-run

# Rollback migration if needed
npm run migrate:rollback

# View database logs
npm run db:logs

# Stop database services
npm run db:stop

# Reset database (destroys all data)
npm run db:reset
```

### Zoho Catalyst Deployment (Production)

**Account Setup:**
1. Create Zoho Catalyst account
2. Register domain (suncube-ai.com)
3. Set up project and database

**Deployment Commands:**
```bash
# Install Catalyst CLI
npm install -g @zohocorp/catalyst-cli

# Login and deploy
catalyst login
catalyst deploy --env production
```

**Environment Configuration:**
```bash
# .env.production
DATABASE_URL=postgresql://[username]:[password]@[host]:[port]/[database]
NODE_ENV=production
VITE_API_URL=https://suncube-ai.com/api
```

### Content Management Workflow

**Current Content Development:**
1. Make changes to content files in `data/` directory
2. Test content with localStorage-based application
3. Commit changes with descriptive messages

**Database Content Management (Next Phase):**
When data migration to PostgreSQL is complete, content management will include database validation and deployment workflows with full CMS capabilities.

### AI Development Guidelines

**Safe AI-Assisted Development:**
- **Scoped Prompts**: Specify exact files and components
- **Change Verification**: Review all AI modifications
- **Incremental Changes**: Apply changes in small batches
- **Backup First**: Commit before AI-assisted changes
- **Module Isolation**: Ensure changes stay within module boundaries

**Validation Scripts:**
```bash
# Validate AI changes
npm run validate:changes

# Check module isolation
npm run test:modules

# Run comprehensive tests
npm run quality-check
```

## Production Launch Readiness

### Pre-Launch Todo List (25 Critical Items)

#### Security & Authentication (Items 1-3, 7-10, 17-18)
1. **Secure Admin Password & Authentication** - Replace hardcoded admin password with environment variable
2. **Move Requirements Tab to Admin Login** - Make Requirements page accessible only after admin login
3. **Secure JWT Secret for Production** - Replace default JWT secret with strong production secret
7. **Configure CORS for Production** - Restrict CORS to production domain only (suncube-ai.com)
8. **Database Connection String Security** - Use Zoho Catalyst secrets manager for DB credentials
9. **API Rate Limiting** - Implement rate limiting on auth endpoints, bulk upload, admin operations
10. **Admin API Endpoint Protection** - Add authentication middleware to all /api/admin/* endpoints
17. **Security Headers Configuration** - Add helmet.js middleware with CSP, X-Frame-Options headers
18. **Input Validation & Sanitization** - Add express-validator, sanitize all inputs

#### Data & Environment (Items 4-6, 11, 15)
4. **Create UAT Document** - End-to-end testing document for production launch
5. **Environment Variables Security Audit** - Ensure all sensitive data in environment variables
6. **Remove/Secure Debug Scripts** - Move debug-user.js, check-users.js to scripts/dev/
11. **Remove Test Users from Production** - Clear test users (neil@, nia@, summs@) before launch
15. **Database Backup Strategy** - Implement automated production backups via Zoho Catalyst cron

#### Infrastructure & Deployment (Items 12-13, 16, 20-21)
12. **SSL/HTTPS Configuration** - Configure SSL certificate, update URLs to https://
13. **Error Handling & Logging** - Generic client errors, detailed server logs, integrate Sentry
16. **Performance Optimization** - Database indexes, caching, minify assets, lazy loading
20. **Analytics & Monitoring Setup** - Integrate Google Analytics 4, error tracking dashboard
21. **Production Deployment Checklist** - DNS, SSL, env vars, migration, smoke tests, rollback plan

#### Business Features (Items 14, 19, 25)
14. **Payment Gateway Integration Testing** - Test Razorpay/Stripe in sandbox mode
19. **Terms of Service & Privacy Policy** - Draft legal documents, add consent checkbox
25. **Email Notification System** - Configure SendGrid/AWS SES for transactional emails

#### Testing & Quality Assurance (Items 22-24)
22. **Content Review & Proofreading** - Review all questions and chapters for accuracy
23. **Mobile Responsiveness Testing** - Test on iOS/Android, various screen sizes
24. **Browser Compatibility Testing** - Test on Chrome, Firefox, Safari, Edge

### Current Business Focus
1. **Content Publishing**: Deliver comprehensive CTET study materials and question banks
2. **One-Time Payment Collection**: Streamlined UPI-based payment system with manual verification
3. **Teacher Referral Network**: 10% commissions for authentic user acquisition
4. **Modular Architecture**: Enable seamless addition of new exam applications

### Deferred Features (Post-Launch Phase)
1. **Account Sharing Prevention**: Netflix-style device management and concurrent session limits
2. **Advanced Fraud Controls**: Geographic usage analysis and automated monitoring
3. **Staging Environment**: Enterprise-grade testing infrastructure (Zoho Catalyst optional staging)

### AI Integration
- **Personalized Learning Paths**: AI-driven content recommendations
- **Intelligent Assessments**: Adaptive question difficulty
- **Automated Explanations**: AI-generated answer explanations
- **Progress Analytics**: ML-powered performance insights

### Enhanced Features
- **Offline Mode**: PWA capabilities for offline study
- **Social Learning**: Study groups and peer discussions
- **Video Content**: Integrated video lectures and tutorials
- **Mobile App**: Native mobile applications
- **Real-time Collaboration**: Live study sessions

### Technical Improvements
- **Backend Migration**: Move from localStorage to proper database (in progress)
- **API Architecture**: RESTful APIs for data management
- **Real-time Features**: WebSocket integration for live updates
- **Advanced Analytics**: Comprehensive user behavior tracking
- **Performance Optimization**: Code splitting and lazy loading enhancements

### Multi-Exam Expansion
- **SSC Module**: Staff Selection Commission exam preparation
- **Banking Module**: Banking exam preparation
- **UPSC Module**: Civil services exam preparation
- **Module Registry**: Dynamic loading system for new exam types
- **Content Management**: Full CMS with authoring interface and approval workflows

## File Structure Details

### Modular Application Structure
```
src/
├── modules/                    # Exam-specific modules
│   ├── ctet/                  # CTET exam module
│   │   ├── components/        # Module-specific components
│   │   │   ├── QuestionCard.tsx
│   │   │   ├── ChapterView.tsx
│   │   │   └── MockTestPage.tsx
│   │   ├── hooks/            # Module-specific hooks
│   │   │   └── useQuestionBank.ts
│   │   ├── utils/            # Module utilities
│   │   └── index.ts          # Module exports
│   ├── ssc/                  # SSC exam module (future)
│   └── shared/               # Truly shared components
│       ├── components/       # Cross-module components
│       └── utils/           # Shared utilities
├── core/                      # Platform core services
│   ├── auth/                 # Authentication services
│   ├── payments/             # Payment processing
│   ├── analytics/            # Analytics tracking
│   └── cms/                  # Content management system
│       ├── ContentManagementService.ts
│       ├── types.ts
│       ├── hooks.ts
│       ├── ContentEditor.tsx
│       ├── ContentApprovalQueue.tsx
│       ├── ContentVersionHistory.tsx
│       └── index.ts
├── components/                # Legacy components (migrating to modules)
├── context/                  # React contexts
├── data/                     # Static data (being modularized)
├── hooks/                    # Custom hooks
├── types.ts                  # TypeScript definitions
└── App.tsx                   # Main application component
```

### Content Management Structure
```
content/
├── exams/                    # Exam-specific content
│   ├── ctet/
│   │   ├── questions/        # Question banks by paper/subject
│   │   │   ├── paper1/
│   │   │   │   ├── child-development.json
│   │   │   │   ├── mathematics.json
│   │   │   │   └── environmental-studies.json
│   │   │   └── paper2/
│   │   │       ├── mathematics-science.json
│   │   │       └── social-studies.json
│   │   ├── chapters/         # Chapter summaries
│   │   │   ├── summaries/
│   │   │   └── practice-materials/
│   │   └── metadata.json     # Content metadata
│   └── ssc/                  # Future exam content
├── shared/                   # Shared content assets
│   ├── templates/
│   └── assets/
└── versions/                 # Version control snapshots
    ├── ctet-v2.1.0/
    └── ctet-v2.0.0/
```

### Static Assets
- **public/favicon.png**: Application favicon/logo displayed in browser tabs
- **public/Suncobe_logo_-_only_cube.png**: Transparent cube logo for header display
- **media/Logo for favicon.png**: Original logo source file for reference

### Development and Deployment
```
scripts/                      # Development scripts
├── validate-changes.sh      # AI change validation
├── deploy-content.sh        # Content deployment
├── backup-content.sh        # Content backup
└── migrate-to-production.sh # Production migration

docs/                        # Documentation
├── Content-Management-Approach.md
├── SunCube-AI-Business-Plan.md
├── Suncube design theme.txt
└── SunCube-AI-Documentation.md
```

### Key Components
- **LandingPage.tsx**: Marketing page with features and testimonials
- **Auth Components**: LoginPage, RegisterPage, OnboardingPage
- **Study Components**: ChapterList, ChapterView, PaperSelector
- **Test Components**: MockTestPage, MockTestResults, QuestionCard
- **Admin Components**: AdminPage, QuestionEditor
- **CMS Components**: ContentEditor, ContentApprovalQueue, ContentVersionHistory
- **Utility Components**: FormattedContent, PremiumContentOverlay

### Data Organization
- **Modular Data**: Exam-specific data isolated by module
- **Shared Data**: Common data in core services
- **Content Data**: Version-controlled content in content/ directory
- **Data Manager**: Handles persistence and data operations

### Context and Hooks
- **AuthContext**: User authentication and profile management
- **useQuestionBank**: Question CRUD operations and change tracking
- **Module Hooks**: Exam-specific hooks within each module

## Security Considerations

- **Client-side Storage**: Sensitive data stored in browser localStorage
- **Input Validation**: Basic validation on forms and inputs
- **API Key Management**: Environment-based API key configuration
- **User Data Privacy**: Minimal data collection with user consent

## Testing Strategy

- **Unit Tests**: Component and hook testing
- **Integration Tests**: User flow testing
- **E2E Tests**: Full application testing
- **Performance Testing**: Load and responsiveness testing

## Code Quality Assurance

### Overview

SunCube AI implements a comprehensive code quality assurance process to ensure maintainable, reliable, and performant code. All changes must pass through multiple quality gates before being merged.

### Linting and Code Formatting

#### ESLint Configuration
- **Configuration**: Strict ESLint rules for React/TypeScript
- **Rules**: Enforces best practices, prevents common errors
- **Integration**: IDE integration and pre-commit hooks

#### Prettier Configuration
- **Code Formatting**: Consistent code style across the codebase
- **Integration**: Pre-commit formatting and CI checks
- **Configuration**: Tailwind CSS compatible formatting rules

### Type Checking

#### TypeScript Strict Mode
- **Strict Type Checking**: All TypeScript files use strict mode
- **Interface Validation**: Comprehensive type definitions for all data structures
- **Build-time Validation**: Type errors prevent builds from completing

### Testing Framework

#### Unit Testing
- **Framework**: Jest with React Testing Library
- **Coverage**: Minimum 80% code coverage required
- **Test Files**: `.test.tsx` or `.spec.tsx` alongside components
- **Mocking**: Proper mocking of external dependencies and APIs

#### Integration Testing
- **Scope**: Component interactions and data flow
- **Tools**: React Testing Library for DOM testing
- **Coverage**: Critical user flows and business logic

#### End-to-End Testing
- **Framework**: Playwright or Cypress
- **Scenarios**: Complete user journeys and critical paths
- **CI Integration**: Automated E2E tests on deployment

#### Test Organization
```
__tests__/
├── unit/
├── integration/
└── e2e/
```

### Pre-commit Hooks

#### Husky + lint-staged Setup
- **Pre-commit**: Runs linting, formatting, and unit tests
- **Pre-push**: Runs integration tests and build verification
- **Configuration**: `.husky/` directory with hook scripts

#### Hook Commands
```bash
# Pre-commit
npx lint-staged

# Pre-push
npm run test:integration && npm run build
```

### CI/CD Quality Gates

#### GitHub Actions Workflow
```yaml
name: Code Quality
on: [push, pull_request]
jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Type checking
        run: npm run type-check
      - name: Linting
        run: npm run lint
      - name: Formatting check
        run: npm run format:check
      - name: Unit tests
        run: npm run test:unit
      - name: Build
        run: npm run build
```

#### Quality Metrics
- **Test Coverage**: >80% overall, >90% for critical paths
- **Build Success**: All builds must pass
- **Type Errors**: Zero TypeScript errors
- **Lint Violations**: Zero ESLint errors

### Code Review Process

#### Pull Request Template
- **Checklist**: Quality assurance checklist for reviewers
- **Testing Requirements**: Evidence of testing completion
- **Documentation**: Updates to documentation when needed

#### Review Criteria
- **Code Quality**: Clean, readable, maintainable code
- **Testing**: Adequate test coverage for new features
- **Performance**: No performance regressions
- **Security**: Security best practices followed
- **Documentation**: Code and documentation updated

### Performance Monitoring

#### Bundle Analysis
- **Build Size**: Monitor bundle size with `vite-bundle-analyzer`
- **Code Splitting**: Ensure proper lazy loading
- **Asset Optimization**: Image and font optimization

#### Runtime Performance
- **Lighthouse Scores**: Target >90 for all metrics
- **Core Web Vitals**: Monitor FCP, LCP, CLS, FID, TBT
- **Memory Usage**: Prevent memory leaks in React components

### Security Scanning

#### Dependency Scanning
- **npm audit**: Regular security audits of dependencies
- **Snyk Integration**: Automated vulnerability scanning
- **License Compliance**: Check for license compatibility

#### Code Security
- **Static Analysis**: Security-focused linting rules
- **Input Validation**: Sanitize all user inputs
- **API Security**: Secure API key management

### Documentation Updates

#### Automated Documentation
- **README Updates**: Keep setup and usage instructions current
- **API Documentation**: Document all public interfaces
- **Changelog**: Maintain detailed change history

#### Documentation Quality Checks
- **Link Validation**: Ensure all links are working
- **Content Accuracy**: Verify technical accuracy
- **Completeness**: Cover all new features and changes

### Quality Assurance Workflow

#### Development Process
1. **Local Development**: Run quality checks locally
2. **Pre-commit**: Automated checks prevent bad commits
3. **Pull Request**: Code review with quality checklist
4. **CI/CD**: Automated testing and validation
5. **Merge**: Only high-quality code gets merged

#### Quality Commands
```json
{
  "scripts": {
    "lint": "eslint src --ext .ts,.tsx",
    "lint:fix": "eslint src --ext .ts,.tsx --fix",
    "format": "prettier --write src/**/*.{ts,tsx,json,md}",
    "format:check": "prettier --check src/**/*.{ts,tsx,json,md}",
    "type-check": "tsc --noEmit",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "test:e2e": "playwright test",
    "build": "vite build",
    "preview": "vite preview",
    "quality-check": "npm run lint && npm run type-check && npm run test && npm run build"
  }
}
```

#### Quality Metrics Dashboard
- **Code Coverage**: Track coverage trends over time
- **Build Health**: Monitor build success rates
- **Performance Metrics**: Track bundle size and load times
- **Security Score**: Regular security assessment reports

### Best Practices

#### Code Standards
- **Consistent Naming**: Follow established naming conventions
- **Component Structure**: Standard component organization
- **Error Handling**: Proper error boundaries and handling
- **Accessibility**: WCAG 2.1 AA compliance

#### Development Guidelines
- **Feature Flags**: Use feature flags for gradual rollouts
- **Progressive Enhancement**: Ensure core functionality works without JavaScript
- **Mobile First**: Test on mobile devices first
- **Cross-browser**: Support modern browsers (last 2 versions)

#### Maintenance
- **Regular Audits**: Monthly code quality reviews
- **Dependency Updates**: Keep dependencies updated and secure
- **Performance Reviews**: Quarterly performance optimization
- **Security Reviews**: Regular security assessments

---

*This code quality assurance framework ensures that SunCube AI maintains high standards of code quality, reliability, and maintainability throughout its development lifecycle.*

## Deployment and Maintenance

- **CI/CD**: Automated build and deployment pipelines
- **Monitoring**: Error tracking and performance monitoring
- **Backup**: Data backup and recovery procedures
- **Updates**: Content updates and feature rollouts

---

---

## 📋 Document Guidelines

### How to Use This Document

**This document is the SINGLE SOURCE OF TRUTH for SunCube AI development.**

**Before Starting Any Development:**
1. ✅ **Read relevant sections** to understand current implementation
2. ✅ **Check "Current Development Status"** for latest state
3. ✅ **Review "Recent Updates"** for recent changes
4. ✅ **Understand architecture** before making changes
5. ✅ **Follow established patterns** and design principles

**After Completing Any Development:**
1. ✅ **Update relevant sections** with new implementation details
2. ✅ **Add entry to "Recent Updates"** with date and description
3. ✅ **Update "Current Development Status"** to reflect new state
4. ✅ **Document new patterns** in appropriate sections
5. ✅ **Commit documentation changes** alongside code changes

**For AI-Assisted Development:**
- Always provide this document as context before making changes
- Request AI to update documentation after implementing changes
- Verify AI-generated changes against established patterns
- Follow "AI Development Safety Measures" guidelines

---

## 📊 Current Development Status

### Database State (November 5, 2025)

**PostgreSQL Database:**
- **Status**: ✅ Fully operational and integrated
- **Connection**: localhost:5433 → suncube_ai_dev
- **API Server**: Running on port 9998 with background process management
- **Current Data**:
  - **45 questions** across 4 subjects (Child Development: 30q, Math/Science: 5q, Social Studies: 5q, English: 5q)
  - **8 chapters** organized by subject
  - **1 upload history** record (CDP bulk upload - 30 questions)

**Data Flow:**
```
PostgreSQL → Express API (port 9998) → React Frontend → localStorage cache (optional)
```

**Flat File Status:**
- ✅ All runtime dependencies removed
- ✅ `data/` folder archived for reference only
- ✅ App fully database-driven

### Application Features Status

| Feature | Status | Notes |
|---------|--------|-------|
| **Study Hub** | ✅ Fully Functional | Displays 4 subjects, 8 chapters, 45 questions from database |
| **Question Bank** | ✅ Fully Functional | Shows all database questions with search/filter, Paper 1/Paper 2 filtering |
| **Mock Tests** | ✅ Functional | Works with uploaded questions; passage integration pending |
| **Admin Panel** | ✅ Fully Functional | CRUD operations, filters (subject, term, language, status, paper type) |
| **Bulk Upload Tool** | ✅ Implemented (Hybrid) | JSON validation → SQL generation → Manual pgAdmin execution |
| **User Authentication** | ✅ Functional | localStorage-based; database migration pending |
| **Referral System** | ✅ Functional | localStorage-based; database migration pending |
| **CMS Integration** | ✅ Implemented | Content authoring, approval workflow, version control |
| **API Server** | ✅ Fully Operational | Background process with auto-start capability |

### Pending Development

**Immediate Priority:**
1. ⏳ **Hybrid Upload Tool Documentation**: Create comprehensive verification workflow guide
2. ⏳ **Data Protection Mechanisms**: Document 4-layer protection system
3. ⏳ **Paper 1 Content Upload**: Upload remaining Paper 1 questions (Child Development complete with 24 questions)
4. ⏳ **Paper 2 Content Upload**: Upload remaining Paper 2 subjects (English: 90q, Hindi: 90q, Math/Science: 120q, SST: 120q)

**Medium Priority:**
5. ⏳ **Passages Table**: Create and populate comprehension passages
6. ⏳ **User Data Migration**: Move user data from localStorage to PostgreSQL
7. ⏳ **Referral Data Migration**: Move referral tracking to database
8. ⏳ **Payment Integration**: Implement database-backed payment verification

**Future Enhancements:**
9. 📋 **Progress Tracking**: Database-backed chapter completion
10. 📋 **Test Results History**: Store mock test results in database
11. 📋 **Analytics Dashboard**: Real-time statistics from database
12. 📋 **Multi-Exam Expansion**: Add SSC, Banking, UPSC modules

### Known Issues and Limitations

**Current Limitations:**
- Mock Test passages use placeholder content (database passages table not yet populated)
- Some database fields like `term` are hardcoded to "Dec 2024" (needs dynamic handling)
- Upload history table has minimal data (only 1 upload recorded)

**No Known Bugs:** All features working as expected with current data

---

## Recent Updates

### Version Updates and Changes

#### Hybrid PostgreSQL Approach Documentation (November 5, 2025)
- **Comprehensive Reference Guide**: Created complete documentation for hybrid PostgreSQL approach
- **File**: `docs/Hybrid-PostgreSQL-Approach-Reference-Guide.md` (1000+ lines)
- **Coverage**: Philosophy, PostgreSQL setup, API server, database schema, SQL generation, protection mechanisms
- **Sections**: 12 comprehensive sections with code examples, configurations, and best practices
- **Purpose**: Reusable reference for implementing same approach in future applications
- **Platforms**: Setup instructions for Windows, macOS, and Linux
- **Protection System**: Complete 4-layer protection mechanism documented
- **SQL Patterns**: Reusable templates for bulk insert, verification, transactions
- **Deployment Guide**: Production setup with SSL, backups, and performance optimization

#### Paper 1/Paper 2 Filtering Implementation (November 5, 2025)
- **Admin Panel Enhancement**: Added Paper Type filter to Question Management
- **Study Hub Fix**: Removed "Work in Progress" message for Paper 1, now shows 4 chapters with 24 questions
- **Question Bank Sync**: Made Question Bank sync with Study Hub's paper selection
- **Dropdown Lock**: Question Bank paper dropdown disabled when Study Hub enforces specific paper
- **Data Validation**: Confirmed Paper 1 CDP questions (24) visible across all UI components
- **Filter Integration**: Paper Type filter works alongside existing filters (subject, term, language, status)
- **Commits**: 3 commits made (f466582, 253b079, 50af196)

#### Hybrid Upload Tool Implementation (November 4-5, 2025)
- **Upload Workflow**: JSON validation → SQL generation → Manual pgAdmin execution
- **Validation Features**: Client-side structure checks, database duplicate detection, Devanagari language detection
- **SQL Generation**: DO $$ blocks with variables, loops, exception handling, ON CONFLICT clauses
- **Protection Layers**: Pre-upload validation, SQL verification checks, database triggers, backup tables
- **Unique Constraint**: `(chapter_id, question_number, paper_type)` allows Paper 1/Paper 2 coexistence
- **Success Rate**: 30 CDP questions uploaded successfully via hybrid tool
- **Documentation**: Created comprehensive guides in docs/ folder

#### Bulk Question Upload System - Planning Phase (November 4, 2025)
- **Comprehensive Upload Tool Design**: Planned system for bulk importing CTET Paper 2 Dec 2024 questions
- **Three-Tab Admin Structure**: Separated concerns - Questions (CRUD), Bulk Upload (Import), Upload History (Audit)
- **Multilingual Support**: Native support for Hindi (Devanagari) and English content
- **Passage Management**: Designed passages table for comprehension-based questions
- **Database Schema Enhancements**: Added language, pdf_page, answer_key_page, status columns to questions table
- **Validation Framework**: Multi-level validation (JSON structure, duplicates, required fields)
- **Upload Workflow**: Designed end-to-end workflow from file selection to database insertion
- **SunCube Theme Integration**: UI/UX design following Deep Purple (#4B0082) and Light Purple (#D8BFD8) theme
- **Audit Trail**: Upload history tracking for governance and troubleshooting
- **Expected Capacity**: Handle 450+ questions across 5 subjects (CDP, English, Hindi, Maths-Sci, SST)
- **Status**: Awaiting confirmation for implementation

#### API Server Management and Persistence (November 4, 2025)
- **Background Process Implementation**: API server now runs as persistent background process
- **Terminal Independence**: Server survives terminal closure using hidden PowerShell window
- **NPM Script Commands**: Added `api:start`, `api:stop`, and `api:status` commands
- **Process Management**: Automatic PID tracking in `logs/api-server.pid`
- **Comprehensive Logging**: Server output saved to `logs/api-server-YYYY-MM-DD.log`
- **Auto-Start Scripts**: Windows Scheduled Task setup for automatic startup on boot/login
- **Health Monitoring**: Built-in status checking with database connection verification
- **Documentation Created**: Complete API-Server-Management.md guide with workflows and troubleshooting
- **PowerShell Scripts**: Created start, stop, status, and auto-start management scripts
- **Reboot Persistence**: Optional auto-start configuration survives machine restarts

#### PostgreSQL Migration and Flat File Removal (November 4, 2025)
- **Complete Flat File Removal**: Removed all runtime dependencies on flat file data (`studyData.ts`)
- **API-First Architecture**: All data now fetched from PostgreSQL via Express API server (port 9998)
- **App.tsx Refactoring**: Study Hub builds `enrichedStudyData` dynamically from API chapters and questions
- **Dynamic Chapter Loading**: Added `/api/chapters` endpoint and React state for chapter management
- **MockTestPage Update**: Removed `studyData` import, added passage content placeholder for database integration
- **dataManager.ts Cleanup**: Removed `processInitialData()`, flat file fallback, and `studyData` import
- **Data Flow Updated**: PostgreSQL → API Server → dataManager → React Components → localStorage cache (optional)
- **Documentation Created**: PostgreSQL-Migration-Summary.md with complete migration details and next steps
- **Current Limitation**: Database has 20 sample questions (5-6 per subject); full data migration pending

#### PostgreSQL Integration Implementation (November 3, 2025)
- **Native PostgreSQL 18**: Installed on Windows with native service (port 5433, non-default to avoid conflicts)
- **Database Schemas**: Created `core`, `ctet`, `cms`, and `analytics` schemas for modular data organization
- **API Server Built**: Express.js REST API (`api-server.js`) serving data from PostgreSQL
- **Sample Data Loaded**: 20 questions and 4 chapters uploaded for integration testing
- **Environment Setup**: `.env.local` configured with database connection details
- **Documentation**: PostgreSQL-Configuration.md and PostgreSQL-Connection-and-Testing.md created
- **Integration Verified**: UI successfully fetches and displays data from PostgreSQL via API

#### Database-Backed Content Management System Implementation (November 3, 2025)
- **Complete CMS Architecture**: Full database-backed content management system with PostgreSQL integration
- **Content Authoring Interface**: Dynamic form generation for different content types (questions, chapters, lessons, quizzes)
- **Approval Workflow**: Multi-step content approval process with reviewer comments and status tracking
- **Version Control**: Complete version history with change summaries, rollback capabilities, and version comparison
- **Admin Integration**: CMS integrated into admin panel with four sub-tabs: Editor, Approvals, History, Statistics
- **Content Statistics**: Real-time dashboard showing content items, versions, pending approvals, and publication status
- **Environment Safety**: Browser-compatible code with Node.js environment detection for database operations

#### Data Migration Scripts Implementation (November 3, 2025)
- **Automated Migration Tool**: Node.js script to migrate all localStorage data to PostgreSQL
- **Data Validation**: Comprehensive validation and error handling during migration
- **Rollback Capability**: Safe rollback functionality for failed migrations
- **Dry Run Support**: Preview migration changes without making actual changes
- **Migration State Tracking**: Database table to track migration versions and status

#### Modular Architecture Implementation (November 3, 2025)
- **Hybrid Modular Architecture**: Implemented parent-child app structure with SunCube AI as parent platform
- **Content Isolation**: Strict module boundaries prevent cross-exam contamination
- **CMS Foundation**: Basic content management system with version control capabilities
- **AI Safety Measures**: Comprehensive protocols for AI-assisted development
- **PostgreSQL Setup**: Local development environment with database service
- **Zoho Catalyst Integration**: Production deployment configuration with optional staging

#### Business Strategy Refinement (November 3, 2025)
- **Content Publishing Focus**: Prioritized content delivery and one-time payment collection
- **Deferred Account Sharing Controls**: Netflix-style validations moved to future development
- **Teacher Referral Network**: Focused initial launch on verified teacher referrals
- **Cost Optimization**: Optional staging environment to control infrastructure costs
- **Revenue Model**: Simplified one-time payments with manual verification

#### Design Theme Implementation (October 31, 2025)
- **Logo Design**: 3D wireframe cube with colored faces (Deep Purple, Light Purple, Soft Gray)
- **Typography System**: Poppins SemiBold for headings, Montserrat for body text
- **Color Palette**: Deep Purple (#4B0082), Light Purple (#D8BFD8), Soft Gray (#666666)
- **Mobile Optimization**: Responsive logo sizing and clean header integration
- **Brand Consistency**: Applied theme across all UI components and marketing materials

#### Logo Optimization for Mobile (October 31, 2025)
- **Mobile-first logo design**: Implemented responsive logo sizing optimized for mobile devices
- **Transparent background**: Removed background from cube logo for cleaner header integration
- **Responsive sizing**:
  - Mobile: 48px × 48px (increased from 24px for better visibility)
  - Small screens: 32px × 32px
  - Medium screens and up: 40px × 40px
- **Mobile text hiding**: "SunCube AI" text hidden on mobile, showing only cube logo
- **File updates**:
  - Added `Suncobe_logo_-_only_cube.png` (transparent version)
  - Updated Logo component to use new transparent logo file
  - Maintained responsive design principles

#### Question Bank Interface Implementation (November 3, 2025)
- **Dedicated Question Bank Page**: Standalone interface for browsing all Paper 2 questions
- **Advanced Search & Filtering**: Full-text search and filtering by subject and exam term
- **Exam Term Display**: Added term field to questions showing "Dec 2024" for CTET exams
- **Shared Data Source**: Question Bank uses same dataManager as chapter views for consistency
- **Navigation Integration**: Added Question Bank tab to main navigation menu
- **Premium Access Control**: Requires payment for question bank access
- **Responsive Design**: Mobile-optimized interface with proper filtering controls

---

## Bulk Question Upload System

### Overview

The Bulk Upload system is a comprehensive tool for administrators to efficiently import large question sets from structured JSON files into the PostgreSQL database. This system is designed to handle the CTET Paper 2 December 2024 question bank (450+ questions across 5 subjects) with multilingual content support (English and Hindi).

### Admin Question Management Structure

The Admin Panel's Question Management is organized into three distinct tabs:

#### **1. Questions Tab (CRUD Operations)**

**Purpose:** Manual management of questions already in the database

**Functionality:**
- **View All Questions**: Browse all uploaded questions with pagination
- **Search & Filter**: Filter by subject, chapter, paper type, status, language
- **Edit Questions**: Modify individual question details
  - Question text and options
  - Correct answer
  - Explanation
  - Metadata (chapter, subject, etc.)
- **Delete Questions**: Remove questions from database
- **Status Management**: Update question status
  - `pending` - Newly uploaded, needs review
  - `verified` - Reviewed and approved
  - `published` - Live on platform for students
  - `archived` - Removed from active use
- **Manual Creation**: Add new questions one at a time using the QuestionEditor form
- **Quick Actions**: Bulk status updates, bulk delete

**UI Features:**
- Sortable columns (question number, subject, status)
- Inline editing for quick updates
- Preview modal for full question view
- Responsive table with mobile optimization
- Color-coded status indicators (SunCube theme)

**Use Cases:**
- Fix typos in uploaded questions
- Update explanations
- Change correct answer if mistake found
- Review and approve pending questions
- Delete duplicate or incorrect questions

---

#### **2. Bulk Upload Tab (NEW)**

**Purpose:** Import questions from JSON files in bulk (initial data population)

**Functionality:**
- **File Selection**: Choose JSON file from `docs/Guide-Paper2-Dec24/` folder
- **File Formats Supported**:
  - `Guide-Paper2-Dec24-D-CDP.json` (Child Development & Pedagogy)
  - `Guide-Paper2-Dec24-D-ENG.json` (English Language)
  - `Guide-Paper2-Dec24-D-Hindi.json` (Hindi Language - हिन्दी)
  - `Guide-Paper2-Dec24-D-Maths-Sci.json` (Mathematics & Science)
  - `Guide-Paper2-Dec24-D-SST.json` (Social Studies)

- **Pre-Upload Validation**:
  - JSON structure validation
  - Required fields check
  - Question number uniqueness
  - Correct answer index validation (0-3)
  - Options array validation (exactly 4 options)
  - Subject name validation
  - Duplicate detection against existing database

- **Preview & Statistics**:
  - Total chapters and questions count
  - Language detection (automatic: English vs Hindi)
  - Chapter-wise breakdown
  - Warning indicators for issues
  - Estimated upload time

- **Upload Options**:
  - ☑ Create passages for comprehension questions
  - ☑ Auto-generate passage IDs
  - ☑ Skip duplicate questions
  - ☑ Set initial status (pending/verified)
  - ☑ Validate question numbering

- **Upload Process**:
  - Batch processing for performance
  - Real-time progress tracking
  - Atomic transactions (all-or-nothing for each chapter)
  - Detailed error reporting

- **Upload Report**:
  - ✅ Successfully uploaded count
  - ⚠️ Skipped (duplicates) count
  - ❌ Failed uploads with reasons
  - Time taken
  - Database impact summary

**UI Features:**
- Drag & drop file upload
- Visual progress bar
- Expandable chapter preview
- Color-coded validation results
- Upload history integration
- SunCube theme styling (Deep Purple, Light Purple)

**Use Cases:**
- Initial import of CTET Dec 2024 question bank
- Add new exam papers
- Update questions from revised guide
- Bulk import after content team preparation

**Important Notes:**
- ⚠️ Not for editing existing questions (use Questions tab)
- ⚠️ Creates new entries in database
- ⚠️ Requires admin authentication
- ✅ Validates before upload to prevent data corruption

---

#### **3. Upload History Tab (NEW)**

**Purpose:** Track and audit all bulk upload operations

**Functionality:**
- **Upload Records**: List of all bulk uploads with details
  - Upload ID and timestamp
  - File name and size
  - Subject/exam
  - Questions count (uploaded/skipped/failed)
  - Upload status (success/partial/failed)
  - Uploaded by (admin username)

- **Detailed Reports**:
  - Click to expand full upload report
  - Success/failure breakdown
  - Error logs for failed uploads
  - Data integrity checks

- **Upload Statistics Dashboard**:
  - Total uploads count
  - Total questions imported
  - Success rate percentage
  - Recent upload activity timeline

- **Filter & Search**:
  - Filter by date range
  - Filter by status
  - Filter by subject
  - Search by filename

**UI Features:**
- Timeline view of uploads
- Expandable report cards
- Download upload logs
- Visual statistics (charts/graphs)
- Mobile-responsive table

**Use Cases:**
- Audit data import operations
- Troubleshoot failed uploads
- Track who uploaded what and when
- Generate reports for data governance

---

### Database Schema for Bulk Upload

#### New Tables

**A. `ctet.passages` Table**
```sql
CREATE TABLE IF NOT EXISTS ctet.passages (
    id TEXT PRIMARY KEY,                    -- e.g., 'passage-hindi-1', 'passage-eng-1'
    chapter_id INTEGER NOT NULL,
    subject TEXT NOT NULL,
    passage_type TEXT NOT NULL,             -- 'prose', 'poem', 'scenario'
    title TEXT NOT NULL,                    -- Chapter title from JSON
    content TEXT NOT NULL,                  -- Summary/passage text from JSON
    language TEXT DEFAULT 'en',             -- 'hi' for Hindi, 'en' for English
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (chapter_id) REFERENCES ctet.chapters(id) ON DELETE CASCADE
);

CREATE INDEX idx_passages_chapter ON ctet.passages(chapter_id);
CREATE INDEX idx_passages_language ON ctet.passages(language);
```

**Purpose:** Store passages/poems for comprehension-based questions (English and Hindi subjects)

**B. Enhanced `ctet.questions` Table**
```sql
ALTER TABLE ctet.questions 
ADD COLUMN IF NOT EXISTS language TEXT DEFAULT 'en';

ALTER TABLE ctet.questions 
ADD COLUMN IF NOT EXISTS pdf_page INTEGER;

ALTER TABLE ctet.questions 
ADD COLUMN IF NOT EXISTS answer_key_page INTEGER;

ALTER TABLE ctet.questions 
ADD COLUMN IF NOT EXISTS status TEXT DEFAULT 'pending';

CREATE INDEX IF NOT EXISTS idx_questions_language ON ctet.questions(language);
CREATE INDEX IF NOT EXISTS idx_questions_status ON ctet.questions(status);
CREATE INDEX IF NOT EXISTS idx_questions_passage ON ctet.questions(passage_id);
```

**New Columns Explained:**
- `language`: 'en' (English) or 'hi' (Hindi) - auto-detected from question text
- `pdf_page`: Source PDF page number from guide book
- `answer_key_page`: Answer key page number for verification
- `status`: Workflow status for review process

**C. Upload History Table**
```sql
CREATE TABLE IF NOT EXISTS ctet.upload_history (
    id SERIAL PRIMARY KEY,
    file_name TEXT NOT NULL,
    file_size INTEGER,
    subject TEXT,
    chapters_count INTEGER,
    questions_uploaded INTEGER,
    questions_skipped INTEGER,
    questions_failed INTEGER,
    upload_status TEXT NOT NULL,            -- 'success', 'partial', 'failed'
    upload_report JSONB,                    -- Detailed report
    uploaded_by TEXT,
    uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_upload_history_date ON ctet.upload_history(uploaded_at);
CREATE INDEX idx_upload_history_subject ON ctet.upload_history(subject);
```

---

### JSON File Format

**Expected Structure:**
```json
[
  {
    "id": 1,
    "title": "Chapter Title or Passage Title",
    "summary": "Passage content or chapter description",
    "questions": [
      {
        "questionNumber": 121,
        "subject": "Hindi" | "English" | "Maths and Science" | "Social Studies" | "Child Development & Pedagogy",
        "question": "Question text (Hindi or English)",
        "options": ["Option 1", "Option 2", "Option 3", "Option 4"],
        "correctAnswer": 0-3,
        "pdfPage": 75,
        "answerKeyPage": 13,
        "status": "verified",
        "paper": "Paper 2",
        "explanation": "Detailed explanation (supports Markdown)"
      }
    ]
  }
]
```

**Language Handling:**
- **Hindi Subject**: All content in Devanagari script (हिन्दी)
- **English Subject**: All content in English
- **Other Subjects**: English only
- **Auto-detection**: System detects language from question text using Unicode range

---

### Bulk Upload Workflow

```
┌─────────────────────────────────────────────────────┐
│ 1. Admin selects JSON file                         │
│    (Guide-Paper2-Dec24-D-Hindi.json)                │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│ 2. Frontend parses & validates JSON                │
│    - Check structure                                │
│    - Validate required fields                       │
│    - Detect language (Hindi/English)                │
│    - Check for duplicates                           │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│ 3. Show preview with statistics                     │
│    ✓ File: Guide-Paper2-Dec24-D-Hindi.json         │
│    ✓ Chapters: 7                                    │
│    ✓ Questions: 90                                  │
│    ✓ Language: Hindi (हिन्दी)                       │
│    ⚠ Warnings: 2 duplicate questions found          │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│ 4. User confirms upload                             │
│    [✓] Create passages for comprehension            │
│    [✓] Skip duplicate questions                     │
│    [Upload to Database] button                      │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│ 5. Backend processes data                           │
│    For each chapter:                                │
│    → Create/update chapter in ctet.chapters         │
│    → Create passage in ctet.passages (if needed)    │
│    → Batch insert questions in ctet.questions       │
│    → Link questions to passage via passage_id       │
│    → Set language and metadata                      │
└──────────────────┬──────────────────────────────────┘
                   ↓
┌─────────────────────────────────────────────────────┐
│ 6. Show upload report                               │
│    ✅ Successfully uploaded: 88 questions           │
│    ⚠️  Skipped (duplicates): 2 questions            │
│    ❌ Failed: 0 questions                           │
│    ⏱️  Time taken: 3.2 seconds                      │
│    [View Details] [Go to Questions Tab]             │
└─────────────────────────────────────────────────────┘
```

---

### Technical Implementation

#### Backend API Endpoints

**1. Validate Upload**
```javascript
POST /api/admin/validate-upload
Headers: { Authorization: 'Bearer <admin_token>' }
Body: {
  jsonData: [...],  // Parsed JSON content
  fileName: "Guide-Paper2-Dec24-D-Hindi.json"
}

Response: {
  valid: true,
  stats: {
    chaptersCount: 7,
    questionsCount: 90,
    language: "hi",
    subjects: ["Hindi"]
  },
  errors: [],
  warnings: [
    { type: 'duplicate', questionNumber: 123, message: '...' }
  ]
}
```

**2. Bulk Upload Questions**
```javascript
POST /api/admin/bulk-upload
Headers: { Authorization: 'Bearer <admin_token>' }
Body: {
  jsonData: [...],
  fileName: "Guide-Paper2-Dec24-D-Hindi.json",
  options: {
    createPassages: true,
    skipDuplicates: true,
    initialStatus: "verified",
    validateNumbering: true
  }
}

Response: {
  success: true,
  uploadId: 123,
  uploaded: 88,
  skipped: 2,
  failed: 0,
  timeTaken: "3.2s",
  report: {
    chapters: [...],
    skippedQuestions: [...],
    errors: []
  }
}
```

**3. Upload History**
```javascript
GET /api/admin/upload-history?limit=50&offset=0
Headers: { Authorization: 'Bearer <admin_token>' }

Response: {
  uploads: [
    {
      id: 123,
      fileName: "Guide-Paper2-Dec24-D-Hindi.json",
      subject: "Hindi",
      questionsUploaded: 88,
      questionsSkipped: 2,
      uploadStatus: "success",
      uploadedBy: "[email protected]",
      uploadedAt: "2025-11-04T10:30:00Z"
    },
    ...
  ],
  totalCount: 5
}
```

#### Frontend Components

**New Component: `BulkUploadTool.tsx`**
```tsx
interface BulkUploadToolProps {
  onUploadComplete: () => void;
}

interface UploadState {
  step: 'select' | 'validate' | 'preview' | 'uploading' | 'complete';
  file: File | null;
  jsonData: any[] | null;
  validationResult: ValidationResult | null;
  uploadProgress: number;
  uploadReport: UploadReport | null;
  error: string | null;
}
```

**Features:**
- File upload with drag & drop support
- Real-time JSON parsing and validation
- Preview table with expandable chapters
- Progress bar during upload
- Detailed success/error reporting
- Color-coded status indicators (SunCube theme)
- Responsive design for mobile/tablet

---

### UI Design (SunCube Theme)

**Color Scheme:**
- **Primary**: Deep Purple (#4B0082) - Headers, primary buttons
- **Secondary**: Light Purple (#D8BFD8) - Backgrounds, cards, highlights
- **Success**: Green (#10B981) - Upload success, verified status
- **Warning**: Amber (#F59E0B) - Validation warnings, pending status
- **Error**: Red (#EF4444) - Failed uploads, errors
- **Neutral**: Soft Gray (#666666) - Body text, borders

**Typography:**
- **Headings**: Poppins SemiBold (16px-24px)
- **Body Text**: Montserrat Regular (14px)
- **Hindi Text**: Noto Sans Devanagari (fallback font)
- **Buttons**: Montserrat Bold (14px)

**Layout Example:**
```
┌─────────────────────────────────────────────────────────┐
│  📤 Bulk Question Upload                  [Deep Purple] │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────┐           │
│  │  📁 Select JSON File                    │           │
│  │  [Drag & Drop Here or Click to Browse]  │           │
│  │  Supported: Guide-Paper2-Dec24-D-*.json │           │
│  └─────────────────────────────────────────┘           │
│                                                         │
│  Preview: [Light Purple Card]                          │
│  ┌─────────────────────────────────────────┐           │
│  │ 📄 Guide-Paper2-Dec24-D-Hindi.json      │           │
│  │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │           │
│  │ Chapters: 7                              │           │
│  │ Total Questions: 90                      │           │
│  │ Language: हिन्दी (Hindi)                 │           │
│  │ Subject: Hindi                           │           │
│  │                                          │           │
│  │ ✓ All validations passed                │ [Green]   │
│  │ ⚠ 2 duplicate questions detected        │ [Amber]   │
│  └─────────────────────────────────────────┘           │
│                                                         │
│  Upload Options:                                        │
│  ☑ Create passages for comprehension                   │
│  ☑ Skip duplicate questions                            │
│  ☑ Set status as 'verified'                            │
│                                                         │
│  [Validate Data] [Upload to Database] [Deep Purple]    │
└─────────────────────────────────────────────────────────┘
```

---

### Best Practices & Guidelines

#### For Administrators

**Before Upload:**
1. ✅ Verify JSON file format matches expected structure
2. ✅ Review validation results carefully
3. ✅ Check preview statistics
4. ✅ Backup database before large uploads
5. ✅ Start with smaller files to test

**After Upload:**
1. ✅ Review upload report for errors
2. ✅ Navigate to Questions tab to verify data
3. ✅ Spot-check random questions for accuracy
4. ✅ Update question statuses as needed
5. ✅ Publish verified questions for students

#### Data Integrity

- **Transaction Safety**: Each chapter upload is atomic (all-or-nothing)
- **Duplicate Detection**: Prevents duplicate question numbers in same subject
- **Validation**: Multi-level validation before database insertion
- **Error Handling**: Failed uploads don't corrupt existing data
- **Audit Trail**: Upload history tracks all operations

#### Performance

- **Batch Processing**: Questions inserted in batches of 50
- **Indexing**: Database indexes on frequently queried columns
- **Progress Tracking**: Real-time progress updates during upload
- **Timeout Protection**: Large uploads chunked to prevent timeouts

---

### Common Use Cases

#### 1. Initial Data Population
**Scenario:** Import all 5 subjects for CTET Dec 2024

**Steps:**
1. Go to Admin → Question Management → Bulk Upload
2. Upload Guide-Paper2-Dec24-D-CDP.json → Review → Upload
3. Upload Guide-Paper2-Dec24-D-ENG.json → Review → Upload
4. Upload Guide-Paper2-Dec24-D-Hindi.json → Review → Upload
5. Upload Guide-Paper2-Dec24-D-Maths-Sci.json → Review → Upload
6. Upload Guide-Paper2-Dec24-D-SST.json → Review → Upload
7. Verify in Questions tab: ~450 questions total

#### 2. Update Existing Questions
**Scenario:** Question #123 has a typo in explanation

**Steps:**
1. Go to Admin → Question Management → Questions
2. Search for question #123
3. Click Edit icon
4. Update explanation text
5. Save changes
6. Status auto-updates to show modification timestamp

#### 3. Review Pending Questions
**Scenario:** Bulk upload completed, need to review before publishing

**Steps:**
1. Go to Admin → Question Management → Questions
2. Filter by status: "pending"
3. Review each question
4. Update status to "verified" or "published"
5. Or bulk-select and update status for multiple questions

---

### Troubleshooting

#### Upload Fails with Validation Errors
**Solution:** 
- Check JSON structure matches expected format
- Ensure all required fields are present
- Verify question numbers are integers
- Check correct answer is 0-3

#### Duplicate Questions Detected
**Solution:**
- Enable "Skip duplicates" option
- Or manually delete duplicates from Questions tab first
- Check if questions already exist in database

#### Hindi Characters Not Displaying
**Solution:**
- Ensure proper UTF-8 encoding in JSON file
- Check browser font support for Devanagari
- Verify `language` field is set to 'hi'

#### Upload Takes Too Long
**Solution:**
- Upload files one at a time instead of all together
- Check internet connection
- Verify API server is running
- Review server logs for bottlenecks

---

## 📚 Related Documentation

This document serves as the master reference. For specific technical details, refer to:

### Database and Backend
- **`docs/Hybrid-PostgreSQL-Approach-Reference-Guide.md`**: Complete reference for hybrid SQL approach
- **`docs/PostgreSQL-Configuration.md`**: Database setup and configuration
- **`docs/PostgreSQL-Connection-and-Testing.md`**: Connection testing and verification
- **`docs/PostgreSQL-Migration-Summary.md`**: Flat file to database migration details
- **`docs/API-Server-Management.md`**: API server commands and workflows

### Upload and Data Management
- **`docs/Hybrid-Upload-Guide.md`**: User guide for bulk upload tool
- **`docs/Data-Upload-Tool-Approach.md`**: Technical approach for upload system
- **`docs/Verification-Workflow-Guide.md`**: Verification and protection workflow
- **`docs/Troubleshooting-Upload-Verification.md`**: Common issues and solutions
- **`docs/Data-Protection-Mechanisms.md`**: 4-layer protection system details

### Business and Design
- **`docs/SunCube-AI-Business-Plan.md`**: Business strategy and monetization
- **`docs/Content-Management-Approach.md`**: CMS architecture and workflows
- **`docs/Suncube design theme.txt`**: Design guidelines and branding

### Development Guidelines
- **Update this document first** when planning new features
- **Reference related docs** for technical implementation details
- **Keep all docs synchronized** when making changes
- **Commit documentation changes** alongside code changes

---

## 🔄 Documentation Maintenance Workflow

### When Planning New Features
1. **Review this document** for current architecture and patterns
2. **Check related docs** for specific technical details
3. **Update "Pending Development"** section with new plans
4. **Document design decisions** before implementation

### During Development
1. **Follow established patterns** documented in this file
2. **Reference technical docs** for implementation details
3. **Take notes** of deviations or new patterns discovered
4. **Test against documented workflows**

### After Completing Development
1. **Update "Current Development Status"** with new state
2. **Add entry to "Recent Updates"** with date, description, and impact
3. **Update relevant sections** (Architecture, Features, Database, etc.)
4. **Update related technical docs** if implementation differs from plan
5. **Commit all documentation changes** with descriptive message
6. **Tag git commit** with reference to documentation update

### Example Documentation Update Commit Message
```
feat: Add Paper Type filtering across UI components

- Added Paper Type filter to Admin Panel Question Management
- Fixed Study Hub to show Paper 1 chapters (removed WIP message)
- Synchronized Question Bank with Study Hub paper selection
- Locked Question Bank dropdown when paper enforced by Study Hub

Updated Documentation:
- docs/SunCube-AI-Documentation.md: Added Paper 1/2 filtering to Recent Updates
- docs/SunCube-AI-Documentation.md: Updated Current Development Status
- Commits: f466582, 253b079, 50af196

Closes #issue-number
```

---

## 🎯 Development Best Practices

### Code Organization
- **Modular Structure**: Keep exam modules isolated in `src/modules/`
- **Shared Components**: Only truly shared components in `src/modules/shared/`
- **Type Safety**: All TypeScript interfaces in `types.ts` or module-specific type files
- **Consistent Naming**: Follow established naming conventions (see Code Quality Assurance section)

### Database Operations
- **API-First**: All database access through Express API endpoints
- **Validation**: Client-side and server-side validation for all mutations
- **Transactions**: Wrap related operations in database transactions
- **Error Handling**: Comprehensive error handling with user-friendly messages
- **Logging**: Log all database operations for debugging and auditing

### Component Development
- **Reusability**: Design components for reuse across modules
- **Props Interface**: Define TypeScript interfaces for all component props
- **State Management**: Use React Context for global state, local state for component-specific
- **Performance**: Memoize expensive computations, lazy load large components
- **Accessibility**: Follow WCAG 2.1 AA guidelines

### Testing Requirements
- **Unit Tests**: All business logic and utility functions
- **Component Tests**: React components with React Testing Library
- **Integration Tests**: API endpoints and data flow
- **E2E Tests**: Critical user journeys (auth, study, mock tests, admin)
- **Coverage**: Maintain >80% overall, >90% for critical paths

### Version Control
- **Commit Messages**: Use conventional commits (feat, fix, docs, refactor, etc.)
- **Branch Strategy**: Feature branches from main, PR-based merging
- **Documentation**: Update docs in same commit as code changes
- **Tags**: Tag releases with semantic versioning (v1.0.0, v1.1.0, etc.)

### AI-Assisted Development
- **Context**: Always provide this documentation as context
- **Scope**: Clearly define scope of AI-generated changes
- **Review**: Manually review all AI changes before committing
- **Validation**: Run tests and quality checks after AI changes
- **Documentation**: Update docs to reflect AI-generated code

---

## 🚀 Quick Start for New Developers

### First-Time Setup
```bash
# 1. Clone repository
git clone <repository-url>
cd suncube-ai

# 2. Install dependencies
npm install

# 3. Setup environment
cp .env.example .env.local
# Edit .env.local with your database credentials

# 4. Start PostgreSQL (if not running)
# Check: npm run api:status

# 5. Start API server
npm run api:start

# 6. Start development server
npm run dev

# 7. Open browser
# http://localhost:5173
```

---

## 🔒 Comprehensive Backup & Disaster Recovery Plan

### Overview

This section outlines the complete backup strategy for SunCube AI, covering all data layers, code repositories, configurations, and recovery procedures. The backup plan ensures business continuity and data protection across development, staging, and production environments.

### Backup Philosophy

**Three-Tier Protection Strategy:**
1. **Automated Continuous Backups**: Real-time/hourly backups for critical data
2. **Scheduled Daily/Weekly Backups**: Full system snapshots at regular intervals
3. **Manual Pre-Change Backups**: Before major deployments or data migrations

**Recovery Time Objectives (RTO) and Recovery Point Objectives (RPO):**
- **Production Database**: RTO: 4 hours, RPO: 15 minutes
- **Code Repository**: RTO: 1 hour, RPO: Real-time (Git)
- **User Data**: RTO: 2 hours, RPO: 1 hour
- **Application Configuration**: RTO: 30 minutes, RPO: Daily

---

### 1. Database Backup Strategy (PostgreSQL)

#### A. Automated Continuous Backups

**PostgreSQL Point-in-Time Recovery (PITR):**
```bash
# Enable WAL archiving in postgresql.conf
wal_level = replica
archive_mode = on
archive_command = 'copy "%p" "C:\\PostgreSQL\\archives\\%f"'
archive_timeout = 900  # 15 minutes

# Configure continuous archiving
max_wal_senders = 3
wal_keep_size = 1GB
```

**Automated Backup Script (Windows PowerShell):**
```powershell
# scripts/db-backup.ps1
param(
    [string]$BackupType = "full",  # full, incremental, manual
    [string]$Retention = "30"       # days to keep backups
)

$timestamp = Get-Date -Format "yyyy-MM-dd_HH-mm-ss"
$backupDir = "C:\PostgreSQL\backups"
$dbName = "suncube_ai_dev"
$pgDumpPath = "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe"
$pgPassword = $env:PGPASSWORD

# Create backup directory if not exists
New-Item -ItemType Directory -Force -Path "$backupDir\$timestamp"

# Full database backup
Write-Host "Starting $BackupType backup at $timestamp..."
& $pgDumpPath `
    --host=localhost `
    --port=5433 `
    --username=developer `
    --dbname=$dbName `
    --format=custom `
    --compress=9 `
    --file="$backupDir\$timestamp\suncube_ai_$timestamp.backup" `
    --verbose

# Schema-only backup (for version control)
& $pgDumpPath `
    --host=localhost `
    --port=5433 `
    --username=developer `
    --dbname=$dbName `
    --schema-only `
    --format=plain `
    --file="$backupDir\$timestamp\schema_$timestamp.sql"

# Data-only backup for each schema
foreach ($schema in @("core", "ctet", "cms", "analytics")) {
    & $pgDumpPath `
        --host=localhost `
        --port=5433 `
        --username=developer `
        --dbname=$dbName `
        --data-only `
        --schema=$schema `
        --format=custom `
        --file="$backupDir\$timestamp\${schema}_data_$timestamp.backup"
}

# Calculate backup size
$backupSize = (Get-ChildItem "$backupDir\$timestamp" -Recurse | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host "Backup completed: $backupSize MB"

# Cleanup old backups (keep last 30 days)
Get-ChildItem $backupDir -Directory | 
    Where-Object { $_.CreationTime -lt (Get-Date).AddDays(-$Retention) } |
    Remove-Item -Recurse -Force

# Log backup completion
Add-Content -Path "$backupDir\backup-log.txt" -Value "$timestamp,$BackupType,$backupSize MB,SUCCESS"
```

**Schedule Automated Backups (Windows Task Scheduler):**
```powershell
# scripts/schedule-db-backups.ps1 (Run as Administrator)

# Daily full backup at 2 AM
$dailyTrigger = New-ScheduledTaskTrigger -Daily -At 2am
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" `
    -Argument "-ExecutionPolicy Bypass -File C:\Users\Admin\Summs\suncube-ai\scripts\db-backup.ps1 -BackupType full"

Register-ScheduledTask -TaskName "SunCube-DB-Daily-Backup" `
    -Trigger $dailyTrigger `
    -Action $action `
    -Description "Daily PostgreSQL database backup" `
    -User "SYSTEM" `
    -RunLevel Highest

# Weekly full backup every Sunday at 1 AM with extended retention
$weeklyTrigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Sunday -At 1am
$weeklyAction = New-ScheduledTaskAction -Execute "PowerShell.exe" `
    -Argument "-ExecutionPolicy Bypass -File C:\Users\Admin\Summs\suncube-ai\scripts\db-backup.ps1 -BackupType full -Retention 90"

Register-ScheduledTask -TaskName "SunCube-DB-Weekly-Backup" `
    -Trigger $weeklyTrigger `
    -Action $weeklyAction `
    -Description "Weekly PostgreSQL database backup (90-day retention)" `
    -User "SYSTEM" `
    -RunLevel Highest
```

#### B. NPM Scripts for Database Backups

**package.json additions:**
```json
{
  "scripts": {
    "db:backup": "powershell -ExecutionPolicy Bypass -File scripts/db-backup.ps1 -BackupType manual",
    "db:backup:full": "powershell -ExecutionPolicy Bypass -File scripts/db-backup.ps1 -BackupType full",
    "db:restore": "powershell -ExecutionPolicy Bypass -File scripts/db-restore.ps1",
    "db:backup:list": "powershell Get-ChildItem C:\\PostgreSQL\\backups -Directory | Sort-Object CreationTime -Descending | Select-Object Name, CreationTime, @{Name='Size(MB)';Expression={(Get-ChildItem $_.FullName -Recurse | Measure-Object -Property Length -Sum).Sum / 1MB}}"
  }
}
```

**Usage:**
```bash
# Manual backup before major changes
npm run db:backup

# Full scheduled backup
npm run db:backup:full

# List all available backups
npm run db:backup:list

# Restore from backup (interactive)
npm run db:restore
```

#### C. Database Restore Procedure

**Restore Script (scripts/db-restore.ps1):**
```powershell
param(
    [string]$BackupFile,
    [string]$TargetDB = "suncube_ai_dev"
)

$pgRestorePath = "C:\Program Files\PostgreSQL\18\bin\pg_restore.exe"
$psqlPath = "C:\Program Files\PostgreSQL\18\bin\psql.exe"

# List available backups if no file specified
if (-not $BackupFile) {
    Write-Host "Available backups:"
    $backups = Get-ChildItem "C:\PostgreSQL\backups" -Directory | Sort-Object CreationTime -Descending
    for ($i = 0; $i -lt $backups.Count; $i++) {
        Write-Host "$i : $($backups[$i].Name) - $($backups[$i].CreationTime)"
    }
    $selection = Read-Host "Select backup number to restore"
    $BackupFile = "$($backups[$selection].FullName)\suncube_ai_*.backup"
}

# Confirm restore operation
Write-Host "`nWARNING: This will replace all data in database '$TargetDB'" -ForegroundColor Red
$confirm = Read-Host "Type 'YES' to confirm restore operation"
if ($confirm -ne "YES") {
    Write-Host "Restore cancelled."
    exit
}

# Create pre-restore backup
Write-Host "`nCreating pre-restore backup..."
& powershell -ExecutionPolicy Bypass -File "$PSScriptRoot\db-backup.ps1" -BackupType "pre-restore"

# Drop and recreate database
Write-Host "`nDropping existing database..."
& $psqlPath -U developer -h localhost -p 5433 -c "DROP DATABASE IF EXISTS $TargetDB;" postgres

Write-Host "Creating fresh database..."
& $psqlPath -U developer -h localhost -p 5433 -c "CREATE DATABASE $TargetDB;" postgres

# Restore from backup
Write-Host "`nRestoring from backup: $BackupFile"
& $pgRestorePath `
    --host=localhost `
    --port=5433 `
    --username=developer `
    --dbname=$TargetDB `
    --verbose `
    --single-transaction `
    --no-owner `
    --no-privileges `
    $BackupFile

if ($LASTEXITCODE -eq 0) {
    Write-Host "`nDatabase restored successfully!" -ForegroundColor Green
    
    # Verify restore
    $questionCount = & $psqlPath -U developer -h localhost -p 5433 -d $TargetDB -t -c "SELECT COUNT(*) FROM ctet.questions;"
    Write-Host "Verification: Found $questionCount questions in database"
} else {
    Write-Host "`nRestore failed! Check logs for details." -ForegroundColor Red
}
```

#### D. Cloud Backup Strategy (Production)

**Zoho Catalyst Database Backups:**
```yaml
# Zoho Catalyst provides automated backups
# Configuration in catalyst.yml

database:
  backups:
    enabled: true
    schedule: "0 2 * * *"  # Daily at 2 AM
    retention: 30           # Keep 30 days
    point_in_time_recovery: true
    
# Export to external storage (S3, Azure, GCP)
backup_exports:
  - provider: "aws-s3"
    bucket: "suncube-ai-backups"
    region: "ap-south-1"
    schedule: "0 3 * * 0"  # Weekly on Sunday 3 AM
    retention: 90
    encryption: true
```

**Manual Cloud Backup:**
```bash
# Export production database to cloud storage
npm run prod:db:export
```

---

### 2. Code Repository Backup (Git)

#### A. Primary Repository Protection

**GitHub Repository Setup:**
- **Main Repository**: `github.com/suncube-ai/suncube-ai` (private)
- **Branch Protection**: Main branch protected, requires PR reviews
- **Automated Backups**: GitHub's infrastructure (triple redundancy)

**Local Repository Mirroring:**
```bash
# scripts/repo-mirror.sh
#!/bin/bash

# Clone bare repository for backup
git clone --mirror https://github.com/suncube-ai/suncube-ai.git backup-mirror.git

# Schedule daily mirror updates
cd backup-mirror.git
git remote update --prune

# Create dated archive
tar -czf "../backups/repo-backup-$(date +%Y%m%d).tar.gz" .
```

#### B. Secondary Remote Repositories

**Setup Multiple Remotes:**
```bash
# Add backup remote (GitLab, Bitbucket, or Azure DevOps)
git remote add backup https://gitlab.com/suncube-ai/suncube-ai.git

# Push to both remotes
git remote add all https://github.com/suncube-ai/suncube-ai.git
git remote set-url --add --push all https://github.com/suncube-ai/suncube-ai.git
git remote set-url --add --push all https://gitlab.com/suncube-ai/suncube-ai.git

# Single push to multiple remotes
git push all main
```

**Automated Daily Push to Backup Remote:**
```powershell
# scripts/push-to-backup.ps1
cd C:\Users\Admin\Summs\suncube-ai
git fetch origin
git push backup --all
git push backup --tags

Add-Content -Path "logs\backup-log.txt" -Value "$(Get-Date) - Repository backed up to secondary remote"
```

#### C. Local Code Archives

**Weekly Local Snapshots:**
```powershell
# scripts/create-code-archive.ps1
$timestamp = Get-Date -Format "yyyy-MM-dd"
$sourceDir = "C:\Users\Admin\Summs\suncube-ai"
$backupDir = "C:\Backups\SunCube-Code"
$archiveName = "suncube-ai-$timestamp.zip"

# Create backup directory
New-Item -ItemType Directory -Force -Path $backupDir

# Create compressed archive (exclude node_modules, .git)
Compress-Archive `
    -Path "$sourceDir\*" `
    -DestinationPath "$backupDir\$archiveName" `
    -Force `
    -CompressionLevel Optimal

# Cleanup old archives (keep last 12 weeks)
Get-ChildItem $backupDir -Filter "*.zip" |
    Where-Object { $_.CreationTime -lt (Get-Date).AddDays(-84) } |
    Remove-Item -Force

Write-Host "Code archive created: $archiveName"
```

**NPM Script:**
```json
{
  "scripts": {
    "backup:code": "powershell -ExecutionPolicy Bypass -File scripts/create-code-archive.ps1"
  }
}
```

---

### 3. Configuration & Secrets Backup

#### A. Environment Variables Backup

**Secure Backup of .env Files:**
```powershell
# scripts/backup-env.ps1
$timestamp = Get-Date -Format "yyyy-MM-dd"
$envFiles = @(".env.local", ".env.production", ".env.staging")
$backupDir = "C:\Backups\SunCube-Configs"

New-Item -ItemType Directory -Force -Path "$backupDir\$timestamp"

foreach ($envFile in $envFiles) {
    if (Test-Path $envFile) {
        # Encrypt before backing up (using 7-Zip with AES-256)
        & "C:\Program Files\7-Zip\7z.exe" a `
            -mhe=on `
            -mx=9 `
            "$backupDir\$timestamp\$envFile.7z" `
            $envFile
        
        Write-Host "Backed up: $envFile (encrypted)"
    }
}

# Backup other sensitive configs
Copy-Item "scripts\api-server.js" "$backupDir\$timestamp\" -Force
Copy-Item "vite.config.ts" "$backupDir\$timestamp\" -Force
Copy-Item "tsconfig.json" "$backupDir\$timestamp\" -Force
```

#### B. Documentation Backup

**Automated Documentation Snapshots:**
```powershell
# scripts/backup-docs.ps1
$timestamp = Get-Date -Format "yyyy-MM-dd"
$docsDir = "docs"
$backupDir = "C:\Backups\SunCube-Docs\$timestamp"

# Create backup directory
New-Item -ItemType Directory -Force -Path $backupDir

# Copy all documentation
Copy-Item -Path "$docsDir\*" -Destination $backupDir -Recurse -Force

# Create archive
Compress-Archive -Path $backupDir -DestinationPath "$backupDir.zip" -Force

Write-Host "Documentation backed up to: $backupDir.zip"
```

---

### 4. Disaster Recovery Procedures

#### Scenario 1: Database Corruption

**Recovery Steps:**
```powershell
# 1. Stop API server
npm run api:stop

# 2. Verify corruption
psql -U developer -h localhost -p 5433 -d suncube_ai_dev -c "SELECT * FROM ctet.questions LIMIT 1;"

# 3. Restore from latest backup
npm run db:restore

# 4. Verify restoration
psql -U developer -h localhost -p 5433 -d suncube_ai_dev -c "SELECT COUNT(*) FROM ctet.questions;"

# 5. Restart API server
npm run api:start

# 6. Test application
npm run dev
```

**Estimated Recovery Time:** 30 minutes - 2 hours

#### Scenario 2: Accidental Code Deletion

**Recovery Steps:**
```bash
# 1. Check Git history
git reflog

# 2. Restore from commit
git reset --hard <commit-hash>

# Or restore specific file
git checkout <commit-hash> -- path/to/file.tsx

# 3. Verify application works
npm run build && npm run dev
```

**Estimated Recovery Time:** 5-15 minutes

#### Scenario 3: Complete System Failure

**Recovery from Scratch:**
```powershell
# 1. Clone repository from GitHub
git clone https://github.com/suncube-ai/suncube-ai.git
cd suncube-ai

# 2. Install dependencies
npm install

# 3. Install PostgreSQL 18
# (Download from official website)

# 4. Restore database from backup
npm run db:restore

# 5. Restore environment variables
Copy-Item "C:\Backups\SunCube-Configs\latest\.env.local" .

# 6. Start services
npm run api:start
npm run dev

# 7. Verify all functionality
```

**Estimated Recovery Time:** 2-4 hours

---

### 5. Backup Storage Locations

#### Local Backups (Development Environment)

| Data Type | Location | Retention | Frequency |
|-----------|----------|-----------|-----------|
| **Database** | `C:\PostgreSQL\backups\` | 30 days (daily), 90 days (weekly) | Daily + Weekly |
| **Code** | `C:\Backups\SunCube-Code\` | 12 weeks | Weekly |
| **Documentation** | `C:\Backups\SunCube-Docs\` | 12 weeks | Weekly |
| **Configuration** | `C:\Backups\SunCube-Configs\` (encrypted) | Indefinite | On change |
| **Logs** | `logs\` (local repo) | 30 days | Continuous |

#### Cloud Backups (Production)

| Data Type | Provider | Location | Retention | Cost Estimate |
|-----------|----------|----------|-----------|---------------|
| **Database** | Zoho Catalyst | India Region | 30 days | Included |
| **Database (Extended)** | AWS S3 | ap-south-1 | 90 days | ~₹500/month |
| **Code Repository** | GitHub | Global | Indefinite | Free |
| **Code Mirror** | GitLab | Global | Indefinite | Free |

**Total Estimated Cloud Cost:** ₹500-1,500/month (~₹6,000-18,000/year)

---

### 6. Quick Reference - Backup Commands

```bash
# === Database Backups ===
npm run db:backup              # Manual database backup
npm run db:backup:full         # Full scheduled backup
npm run db:restore             # Interactive restore
npm run db:backup:list         # List all backups

# === Code Backups ===
npm run backup:code            # Create code archive
git push backup --all          # Push to backup remote

# === Recovery Commands ===
npm run db:restore             # Restore database
git reset --hard <commit>      # Restore code from Git
npm run api:start              # Restart services
```

---

### 7. Backup Checklist for Developers

#### Before Major Changes
- [ ] Create database backup: `npm run db:backup`
- [ ] Commit all changes to Git
- [ ] Push to remote: `git push origin main`
- [ ] Document changes

#### Weekly Maintenance
- [ ] Verify latest database backup exists
- [ ] Check backup storage space
- [ ] Review backup logs for errors

#### Monthly Tasks
- [ ] Test database restore
- [ ] Clean up old backups (automated)
- [ ] Review backup procedures

#### Quarterly Tasks
- [ ] Perform disaster recovery drill
- [ ] Review retention policies
- [ ] Audit backup costs

---

### Summary

**SunCube AI Backup Strategy provides:**
- ✅ **Multiple layers**: Database, code, config, documentation
- ✅ **Automated scheduling**: Daily/weekly without manual intervention
- ✅ **Quick recovery**: Tested procedures for common scenarios
- ✅ **Data integrity**: Verification and testing protocols
- ✅ **Cost-effective**: Minimal cloud costs

**Recovery Confidence:**
- Database: Restore within 2 hours to any point in last 30 days
- Code: Restore within 15 minutes to any Git commit
- Complete System: Rebuild from scratch in 4 hours

**Next Steps:**
1. Create `scripts/db-backup.ps1`
2. Create `scripts/db-restore.ps1`
3. Schedule automated backups
4. Test restore procedure
5. Set up secondary Git remote

---

*Backup Plan Version: 1.0*  
*Last Updated: November 5, 2025*  
*Prepared by: SunCube AI Team*

---

### Essential Commands
```bash
# Development
npm run dev                    # Start frontend dev server
npm run api:start              # Start API server in background
npm run api:status             # Check API server status
npm run api:stop               # Stop API server

# Code Quality
npm run lint                   # Run ESLint
npm run type-check             # TypeScript type checking
npm run test                   # Run all tests
npm run quality-check          # Run all quality checks

# Database
# See API-Server-Management.md for database commands

# Build
npm run build                  # Production build
npm run preview                # Preview production build
```

### Understanding the Codebase
1. **Read this document** (SunCube-AI-Documentation.md) completely
2. **Review architecture section** to understand system design
3. **Check current status** to see what's implemented vs pending
4. **Read recent updates** to understand latest changes
5. **Explore codebase** starting from `App.tsx`
6. **Run the app** and interact with all features
7. **Review related docs** for specific technical areas

### Making Your First Contribution
1. **Pick a task** from "Pending Development" or create an issue
2. **Create feature branch**: `git checkout -b feat/your-feature`
3. **Update this doc** with your planned changes (Pending Development section)
4. **Implement feature** following established patterns
5. **Write tests** for new functionality
6. **Run quality checks**: `npm run quality-check`
7. **Update documentation** with implementation details
8. **Commit with descriptive message** following conventional commits
9. **Create pull request** with reference to documentation updates
10. **Address review feedback** and update docs if needed

---

*Document Version: 9.0 - Complete Single Source of Truth*
*Last Updated: November 5, 2025*
*Major Changes: Added comprehensive guidelines, current status tracking, documentation workflow*
*Purpose: Master reference for all SunCube AI development and changes*
*Prepared by: SunCube AI Team*