SunCube AI - Comprehensive Documentation

📑 Table of Contents

Overview
Objective
Platform Architecture Overview
- Parent-Child App Structure
- Key Design Principles
- Hybrid Modular Architecture
  - Architecture Components
  - Implementation Strategy
Design Theme & Branding
- Logo Design
- Color Palette
- Typography
- Design Style
Architecture
- Technology Stack
- Database Architecture
- Application Structure
- Content Management Architecture
  - Content Isolation Strategy
  - Development Environment Setup
- Component Architecture
- Data Flow
- API Server Management
Design Principles
- UI/UX Design
- Code Organization
- Performance Considerations
Data Management
- Data Structure
  - Core Types
- Data Sources
- Data Persistence
- Data Flow Patterns
Key Features
- Study Hub
- Question Bank System
- Mock Test System
- User Management
- Admin Features
User Journey
Business Logic
- Monetization Strategy
- Referral System
- Content Strategy
- Fraud Prevention (Current Implementation)
- AI Development Safety Measures
Development Setup
- Prerequisites
- Installation
- Environment Setup
- VS Code Workspace Configuration
- Development Workflow
- Zoho Catalyst Deployment (Production)
- Content Management Workflow
- AI Development Guidelines
Future Development Plans
- Current Business Focus
- Deferred Features (Post-Launch Phase)
- AI Integration
- Enhanced Features
- Technical Improvements
- Multi-Exam Expansion
File Structure Details
- Modular Application Structure
- Content Management Structure
- Static Assets
- Development and Deployment
- Key Components
- Data Organization
- Context and Hooks
Security Considerations
Testing Strategy
Code Quality Assurance
- Overview
- Linting and Code Formatting
  - ESLint Configuration
  - Prettier Configuration
- Type Checking
  - TypeScript Strict Mode
- Testing Framework
- Pre-commit Hooks
  - Husky + lint-staged Setup
  - Hook Commands
- CI/CD Quality Gates
  - GitHub Actions Workflow
  - Quality Metrics
- Code Review Process
  - Pull Request Template
  - Review Criteria
- Performance Monitoring
  - Bundle Analysis
  - Runtime Performance
- Security Scanning
  - Dependency Scanning
  - Code Security
- Documentation Updates
  - Automated Documentation
  - Documentation Quality Checks
- Quality Assurance Workflow
- Best Practices
Deployment and Maintenance
📋 Document Guidelines
- How to Use This Document
📊 Current Development Status
- Database State (November 5, 2025)
- Application Features Status
- Pending Development
- Known Issues and Limitations
Recent Updates
- Version Updates and Changes
Bulk Question Upload System
- Overview
- Admin Question Management Structure
- Database Schema for Bulk Upload
  - New Tables
- JSON File Format
- Bulk Upload Workflow
- Technical Implementation
  - Backend API Endpoints
  - Frontend Components
- UI Design (SunCube Theme)
- Best Practices & Guidelines
- Common Use Cases
- Troubleshooting
📚 Related Documentation
- Database and Backend
- Upload and Data Management
- Business and Design
- Development Guidelines
🔄 Documentation Maintenance Workflow
- When Planning New Features
- During Development
- After Completing Development
- Example Documentation Update Commit Message
🎯 Development Best Practices
- Code Organization
- Database Operations
- Component Development
- Testing Requirements
- Version Control
- AI-Assisted Development
🚀 Quick Start for New Developers
- First-Time Setup
🔒 Comprehensive Backup & Disaster Recovery Plan
- Overview
- Backup Philosophy
- 1. Database Backup Strategy (PostgreSQL)
- 2. Code Repository Backup (Git)
- 3. Configuration & Secrets Backup
  - A. Environment Variables Backup
  - B. Documentation Backup
- 4. Disaster Recovery Procedures
- 5. Backup Storage Locations
  - Local Backups (Development Environment)
  - Cloud Backups (Production)
- 6. Quick Reference - Backup Commands
- 7. Backup Checklist for Developers
- Summary
Essential Commands
Understanding the Codebase
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:

Providing Comprehensive Study Materials: Detailed, chapter-wise content covering the complete CTET syllabus across all subjects
Enabling Interactive Learning: Through question banks with detailed explanations and comprehension passages
Offering Realistic Practice: Via configurable mock tests that simulate real exam conditions
Facilitating Personalized Learning: With user profiles, progress tracking, and adaptive content
Building Community: Through referral systems and user engagement features
Leveraging AI: Future integration of AI-powered features for personalized learning paths and intelligent assessments
Ensuring Content Safety: Strict modular boundaries and AI development safety measures prevent cross-contamination
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

Content Isolation: Each exam app maintains independent content without cross-contamination
Non-Disruptive Updates: Content updates don't affect other apps or platform stability
Scalable Architecture: Easy addition of new exam apps without platform refactoring
Shared Services: Common functionality (auth, payments, analytics) shared across apps
Version Control: Content versioning with rollback capabilities
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):

# 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:

// 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:

Upload JSON file with questions and chapters
UI validates structure, fields, language detection
Generate SQL script with proper schema mapping
Download SQL file to local machine
Execute in pgAdmin to insert data
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

PostgreSQL Database: Primary data source for questions, chapters, and passages
API Server: Express.js server (port 9998) serving data from PostgreSQL
User Authentication: Managed through AuthContext with localStorage persistence
Question Bank: CRUD operations via API with PostgreSQL backend
Content Management: Version-controlled content updates with rollback capabilities
Module Isolation: Strict boundaries prevent cross-exam contamination
AI Safety: Validation procedures prevent unintended AI-assisted changes
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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

Verify API is running: npm run api:status
Check environment variable: VITE_API_URL=http://localhost:9998/api in .env.local
Restart API if needed: npm run api:stop && npm run api:start

After machine restart (without auto-start):

# 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

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

Static Study Data: Pre-defined content in TypeScript modules organized by subject
User-Generated Content: Questions can be added/modified via admin interface
User Data: Authentication and profile information
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

Initial Load: Static data loaded from modules, processed, and stored in localStorage
CRUD Operations: Question modifications tracked and persisted
User Management: Authentication state and user profiles managed via context
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

Discovery: User lands on marketing-focused landing page
Registration: Email-based signup with optional referral code
Onboarding: Progressive profile completion
Study Selection: Choose between Paper 1 or Paper 2 preparation
Question Bank Access: Browse all questions with search and filtering capabilities
Chapter Study: Navigate subjects and chapters, practice questions
Practice: Take mock tests to assess readiness
Premium Access: Pay for full access to premium features
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

- 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

# 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

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:

Context Overreach: AI modifying related but unrelated components
Pattern Matching Issues: AI applying changes to similar code patterns
Import/Dependency Changes: AI updating shared dependencies
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

# 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:

# .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:

Open VS Code
File → Save Workspace As → suncube-ai.code-workspace
Configure workspace settings for module isolation

Essential Extensions:

ESLint
Prettier
TypeScript Importer
Path Intellisense
Git Graph
Todo Tree

Workspace Settings:

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

Development Workflow

# 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:

# 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:

Create Zoho Catalyst account
Register domain (suncube-ai.com)
Set up project and database

Deployment Commands:

# Install Catalyst CLI
npm install -g @zohocorp/catalyst-cli

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

Environment Configuration:

# .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:

Make changes to content files in data/ directory
Test content with localStorage-based application
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:

# 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)

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

Data & Environment (Items 4-6, 11, 15)

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

Infrastructure & Deployment (Items 12-13, 16, 20-21)

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

Business Features (Items 14, 19, 25)

Payment Gateway Integration Testing - Test Razorpay/Stripe in sandbox mode
Terms of Service & Privacy Policy - Draft legal documents, add consent checkbox
Email Notification System - Configure SendGrid/AWS SES for transactional emails

Testing & Quality Assurance (Items 22-24)

Content Review & Proofreading - Review all questions and chapters for accuracy
Mobile Responsiveness Testing - Test on iOS/Android, various screen sizes
Browser Compatibility Testing - Test on Chrome, Firefox, Safari, Edge

Current Business Focus

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

Deferred Features (Post-Launch Phase)

Account Sharing Prevention: Netflix-style device management and concurrent session limits
Advanced Fraud Controls: Geographic usage analysis and automated monitoring
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

# Pre-commit
npx lint-staged

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

CI/CD Quality Gates

GitHub Actions Workflow

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

Local Development: Run quality checks locally
Pre-commit: Automated checks prevent bad commits
Pull Request: Code review with quality checklist
CI/CD: Automated testing and validation
Merge: Only high-quality code gets merged

Quality Commands

{
  "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:

✅ Read relevant sections to understand current implementation
✅ Check "Current Development Status" for latest state
✅ Review "Recent Updates" for recent changes
✅ Understand architecture before making changes
✅ Follow established patterns and design principles

After Completing Any Development:

✅ Update relevant sections with new implementation details
✅ Add entry to "Recent Updates" with date and description
✅ Update "Current Development Status" to reflect new state
✅ Document new patterns in appropriate sections
✅ 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:

⏳ Hybrid Upload Tool Documentation: Create comprehensive verification workflow guide
⏳ Data Protection Mechanisms: Document 4-layer protection system
⏳ Paper 1 Content Upload: Upload remaining Paper 1 questions (Child Development complete with 24 questions)
⏳ 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

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

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

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:

[
  {
    "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

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

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

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: "admin@suncube.ai",
      uploadedAt: "2025-11-04T10:30:00Z"
    },
    ...
  ],
  totalCount: 5
}

Frontend Components

New Component: BulkUploadTool.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:

✅ Verify JSON file format matches expected structure
✅ Review validation results carefully
✅ Check preview statistics
✅ Backup database before large uploads
✅ Start with smaller files to test

After Upload:

✅ Review upload report for errors
✅ Navigate to Questions tab to verify data
✅ Spot-check random questions for accuracy
✅ Update question statuses as needed
✅ 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:

Go to Admin → Question Management → Bulk Upload
Upload Guide-Paper2-Dec24-D-CDP.json → Review → Upload
Upload Guide-Paper2-Dec24-D-ENG.json → Review → Upload
Upload Guide-Paper2-Dec24-D-Hindi.json → Review → Upload
Upload Guide-Paper2-Dec24-D-Maths-Sci.json → Review → Upload
Upload Guide-Paper2-Dec24-D-SST.json → Review → Upload
Verify in Questions tab: ~450 questions total

2. Update Existing Questions

Scenario: Question #123 has a typo in explanation

Steps:

Go to Admin → Question Management → Questions
Search for question #123
Click Edit icon
Update explanation text
Save changes
Status auto-updates to show modification timestamp

3. Review Pending Questions

Scenario: Bulk upload completed, need to review before publishing

Steps:

Go to Admin → Question Management → Questions
Filter by status: "pending"
Review each question
Update status to "verified" or "published"
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

Review this document for current architecture and patterns
Check related docs for specific technical details
Update "Pending Development" section with new plans
Document design decisions before implementation

During Development

Follow established patterns documented in this file
Reference technical docs for implementation details
Take notes of deviations or new patterns discovered
Test against documented workflows

After Completing Development

Update "Current Development Status" with new state
Add entry to "Recent Updates" with date, description, and impact
Update relevant sections (Architecture, Features, Database, etc.)
Update related technical docs if implementation differs from plan
Commit all documentation changes with descriptive message
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

# 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:

Automated Continuous Backups: Real-time/hourly backups for critical data
Scheduled Daily/Weekly Backups: Full system snapshots at regular intervals
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):

# 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):

# 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):

# 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:

{
  "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:

# 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):

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

{
  "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:

# 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:

# 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:

# 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:

# 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:

# 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

# === 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:

Create scripts/db-backup.ps1
Create scripts/db-restore.ps1
Schedule automated backups
Test restore procedure
Set up secondary Git remote

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

Essential Commands

# 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

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

Making Your First Contribution

Pick a task from "Pending Development" or create an issue
Create feature branch: git checkout -b feat/your-feature
Update this doc with your planned changes (Pending Development section)
Implement feature following established patterns
Write tests for new functionality
Run quality checks: npm run quality-check
Update documentation with implementation details
Commit with descriptive message following conventional commits
Create pull request with reference to documentation updates
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