OSEM Yearbook 2025

Interactive 3D Yearbook Application with Mobile Support

Om Shanti English Medium School - Grade 12th Batch of 2025

📖 Table of Contents

Overview
Features
Book Structure
Technology Stack
How It Works
Setup & Installation
Project Architecture
Data Structure
Deployment
Future Enhancements

🎯 Overview

OSEM Yearbook 2025 is an interactive, 3D digital yearbook application that provides an immersive book-reading experience. The application features realistic page-turning animations, student profiles, and memorable moments from the graduating class.

Dual Interface System:

Desktop (≥768px): Full 3D flipbook with realistic page-turning animation
Mobile (<768px): Swipe-based single-page view optimized for touch devices

✨ Features

Desktop Version (3D Flipbook)

3D Flipbook Animation: Realistic page-turning with CSS 3D transforms
Dual Page View: See left and right pages simultaneously
Visual Effects: Leather-bound book cover, paper textures, shadows
Smooth Animations: 1200ms cubic-bezier transitions
Interactive Elements: Click to turn pages, close book button

Mobile Version (Touch Optimized)

Swipe Navigation: Left/right swipe gestures to turn pages
Touch Controls: Large, accessible navigation buttons
Page Indicators: Visual progress dots at bottom
Responsive Typography: Scales perfectly on small screens
Swipe Hints: Guidance for first-time users

Common Features

Student Profiles: Individual pages for each graduating student
Multiple Page Layouts:
- Student Profile Layout (photo + quote)
- Full Image Layout (large photo with caption)
- Standard Chapter Layout (text + illustration)
Dynamic Image Loading: Images from keywords or direct URLs
Elegant Typography: Custom fonts (Cinzel, Playfair Display, Caveat, Crimson Pro)
Paper Texture Effects: Realistic book appearance with overlays
Memorable Quotes: Each student has a personalized message

📚 Book Structure

The yearbook follows this flow:

Front Matter

Cover Page: OSEM logo with "Grade 12th • 2025"
Principal's Message: Inspirational message from school leadership
Class Photo: Group photo of all students
Cultural Memories: Highlights of events and activities

Student Profiles (Alphabetical Order)

Each student has a dedicated profile page containing:

Name: Full name of the student
Photo: Portrait image
Quote: Personal message or memorable quote
Nickname: Optional nickname (if applicable)
Future Goals: Career aspirations
Memorable Moments: Special memories from school

Back Matter

Farewell Chapter: Closing message to the batch
Credits: Production credits and acknowledgments

Sample Student Profile Structure:

{
  "id": 1,
  "name": "Student Name",
  "quote": "Personal message or favorite quote",
  "imageKeyword": "Used to fetch relevant image",
  "imageUrl": "Direct image path (optional)",
  "futureGoal": "Career aspiration",
  "nickname": "Nickname (optional)",
  "memorable": "Special memory from school"
}

🛠 Technology Stack

Frontend

React 19.2.3: UI framework with hooks
TypeScript: Type safety
Tailwind CSS: Utility-first styling
Vite: Build tool and development server

3D & Animations

CSS 3D Transforms: Hardware-accelerated page flipping
Tailwind Animations: Smooth transitions and effects
Cubic-Bezier Curves: Natural motion timing

Data & Assets

Static JSON: Yearbook data storage
Assets: Local images and audio files
Unsplash/Picsum: Dynamic image generation

Development

TypeScript: Type-safe development
ESLint: Code quality
GitHub Actions: CI/CD pipeline

🎮 How It Works

Desktop 3D Flipbook

The desktop version uses CSS 3D transforms to create realistic page-turning:

Book Structure: Multiple sheets with front/back faces
Page Mapping: Each sheet shows 2 pages (left/right)
3D Rotation: Pages rotate around Y-axis (0deg to -180deg)
Z-Indexing: Proper stacking order for authentic look
Perspective: 1500px perspective for natural view
Transform Origin: Pages rotate from the spine (left edge)

Animation Flow:

User clicks → Audio plays → Page rotates → Z-index updates → Animation completes

Mobile Swipe Navigation

The mobile version simplifies the experience:

Single Page View: Shows one page at a time
Swipe Detection: Tracks touch start/end positions
Threshold Check: Minimum 50px swipe distance
Direction Detection: Left swipe = next, Right swipe = previous
Animation: Fade + slide effect (500ms)
Buttons Fallback: Navigation buttons always available

Touch Flow:

Touch start → Track position → Touch end → Calculate distance → Check threshold → Navigate

🚀 Setup & Installation

Prerequisites

Node.js 18+
npm or yarn

Installation Steps

Clone the repository

git clone https://github.com/yourusername/OSEM-YearBook.git
cd OSEM-YearBook

Install dependencies

npm install

Run development server

npm run dev

Build for production

npm run build

Preview production build

npm run preview

Configuration

GitHub Pages Setup

The project is configured for GitHub Pages deployment:

Update vite.config.ts:

export default defineConfig({
  base: '/OSEM-YearBook/', // Your repo name
  plugins: [react()],
})

GitHub Actions (.github/workflows/deploy.yml):
- Automatically deploys on push to main branch
- Builds and deploys to gh-pages branch

🏗 Project Architecture

OSEM-YearBook/
├── public/
│   ├── images/
│   │   ├── chapters/          # Chapter images
│   │   └── students/          # Student photos
│   └── sounds/
│       └── page-flip.mp3      # Page turn audio
├── src/
│   ├── components/
│   │   ├── Home.tsx           # Landing page
│   │   ├── Flipbook.tsx       # Desktop 3D version
│   │   ├── MobileFlipbook.tsx # Mobile version
│   │   ├── BookPage.tsx       # Individual page component
│   │   └── BookCover.tsx      # Cover design
│   ├── data/
│   │   └── yearbook-data.json # All book content
│   ├── utils/
│   │   └── imageUtils.ts      # Image path resolution
│   ├── services/
│   │   └── geminiService.ts   # AI service (deprecated)
│   ├── types.ts               # TypeScript interfaces
│   └── App.tsx                # Main app component
├── index.html                 # Entry HTML
├── package.json               # Dependencies
├── vite.config.ts             # Build configuration
├── tsconfig.json              # TypeScript config
└── tailwind.config.js         # Styling config

📊 Data Structure

Main Structure (`yearbook-data.json`)

interface YearbookData {
  metadata: {
    schoolName: string;
    yearbook: {
      title: string;
      subtitle: string;
      year: number;
      batch: string;
    }
  };
  chapters: Chapter[];      // Front matter chapters
  students: Student[];      // Student profiles
  farewell: Chapter;        // Closing chapter
  credits?: Chapter;        // Optional credits
}

interface Chapter {
  type: 'chapter';
  chapterTitle: string;
  text: string;
  imageKeyword?: string;
  imageUrl?: string;
  layout?: 'standard' | 'full-image';
  order?: number;
}

interface Student {
  id: number;
  name: string;
  quote: string;
  imageKeyword: string;
  imageUrl?: string;
  futureGoal?: string;
  nickname?: string;
  memorable?: string;
}

Component Props

interface FlipbookProps {
  story: Story;
  onClose: () => void;
}

interface Story {
  title: string;
  author: string;
  pages: StoryPage[];
}

interface StoryPage {
  type?: 'chapter' | 'profile';
  layout?: 'standard' | 'full-image';
  text: string;
  imageKeyword?: string;
  imageUrl?: string;
  chapterTitle?: string;
  studentName?: string;
}

📦 Deployment

GitHub Pages (Recommended)

The project uses GitHub Actions for automatic deployment:

Workflow file: .github/workflows/deploy.yml
Trigger: Push to main branch
Process:
- Checks out code
- Sets up Node.js
- Installs dependencies
- Builds project
- Deploys to gh-pages branch
Result: Site available at https://yourusername.github.io/OSEM-YearBook/

Manual Deployment

# Build the project
npm run build

# Deploy using gh-pages
npm run deploy

Netlify/Vercel Alternative

Connect repository to Netlify/Vercel
Build command: npm run build
Publish directory: dist
Environment variable: BASE_URL=/

🎓 Customization Guide

Adding New Students

Add student data to data/yearbook-data.json:

{
  "id": 25,
  "name": "New Student",
  "quote": "Favorite quote or message",
  "imageKeyword": "portrait_student",
  "futureGoal": "Career aspiration",
  "nickname": "Nickname (optional)",
  "memorable": "Special memory"
}

Add student photo to public/images/students/:
- Name format: student-name.jpg
- Update imageUrl in data: /images/students/student-name.jpg
Rebuild and deploy

Adding New Chapters

Add chapter to chapters array in JSON:

{
  "type": "chapter",
  "chapterTitle": "New Chapter",
  "text": "Chapter content here",
  "imageKeyword": "chapter_theme",
  "layout": "full-image"
}

Add image to public/images/chapters/
Update order property for sequencing

Styling Changes

Modify Tailwind classes in components:

Colors: Edit color values in component files
Fonts: Update font families in Tailwind config
Animations: Modify transition classes and duration

🔮 Future Enhancements

Planned Features

Technical Improvements

Service worker for offline support
Image optimization and lazy loading
Performance monitoring
Accessibility enhancements (ARIA labels)
Unit tests with Jest/React Testing Library
E2E tests with Cypress/Playwright

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature-name
Make changes and test
Commit: git commit -m "Add feature"
Push: git push origin feature-name
Create Pull Request

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Om Shanti English Medium School
Class of 2025
All teachers and staff
Contributors (Teachers) and developer (Trinno)

📞 Support

For support or questions:

Create an issue on GitHub
Contact: none!

Made with ❤️ for OSEM Class of 2025

May your journey ahead be as inspiring as your time here

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
components		components
data		data
dist		dist
public		public
services		services
utils		utils
.gitignore		.gitignore
App.tsx		App.tsx
CHANGES-SUMMARY.md		CHANGES-SUMMARY.md
DEPLOYMENT.md		DEPLOYMENT.md
QUICK-DEPLOY.md		QUICK-DEPLOY.md
README.md		README.md
SIMPLE-GUIDE.md		SIMPLE-GUIDE.md
index.html		index.html
index.tsx		index.tsx
metadata.json		metadata.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
types.ts		types.ts
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation