📚 Nuba Santillana

Your Educational Library in the Cloud

A modern educational content platform for Santillana, providing students and educators with access to digital books and educational resources.

---

📖 Table of Contents

• ✨ Overview
• 🚀 Features
• 🛠️ Tech Stack
• 📁 Project Structure
• ⚙️ Prerequisites
• 📦 Installation
• 💻 Development
• 🏗️ Building for Production
• 📐 Architecture Guidelines
• 🎨 Design Resources
• 📄 License
• 💬 Support

---

✨ Overview

Nuba Santillana is a web application that allows users to register, activate books using codes, and access digital educational content. The platform includes features similar to existing Santillana platforms (TuCLase/ValeSaber) with enhanced capabilities for content management and expiration handling.

Key Highlights:

• 🎓 Educational content management system
• 🔐 Secure user authentication and authorization
• 📱 Fully responsive mobile-first design
• ♿ WCAG-compliant accessibility
• 🎨 Modern UI following Santillana brand guidelines

🚀 Features

🔑 Core Functionality

Feature	Description
👤 User Registration & Authentication	Secure user registration with email-based password recovery
📖 Book Activation	Code validation using the existing Claves Libros API
📚 Active Books Listing	Display of active books with beautiful cover images
🎬 Digital Content Access	Support for multiple content formats:
	• 📦 ZIP (HTML packages)
	• 📄 PDF documents
	• 🎵 MP3 audio files
	• 🎥 MP4 video files
🗂️ Content Sections	Configurable sections that can be enabled/disabled from the backend
⏰ Expiration Management	Flexible code expiration options:
	• ♾️ No expiration
	• 📅 Expires X days after activation
	• 🎄 Expires on December 31st of the activation year
📊 Access Analytics	User access tracking for:
	• 📈 Access per user to each book
	• 📉 Access per user to each content item
🛠️ Content Management BackOffice	Administrative interface for content management

🎨 User Experience

• 📱 Responsive Design: Mobile-first, fully responsive UX
• 🎨 Modern UI: Built with Tailwind CSS and following Santillana brand guidelines (Teal #00AEB6)
• ♿ Accessibility: WCAG-compliant with proper semantic HTML and keyboard navigation

🛠️ Tech Stack

Category	Technology	Version
🚀 Framework	Next.js (App Router)	14.2.5
💻 Language	TypeScript	5.4.5
🎨 Styling	Tailwind CSS	3.4.10
📝 Forms	React Hook Form + Zod	Latest
✨ Animations	Framer Motion, GSAP	Latest
🎯 Icons	Lucide React	Latest
📦 Package Manager	pnpm	9.0.0
🏗️ Architecture	Monorepo (pnpm workspaces)	-

📁 Project Structure

nuba/
├── 📦 packages/
│   └── 🌐 web/                    # Next.js web application
│       ├── 📱 app/                # App Router pages and layouts
│       │   ├── 👨‍💼 (admin)/        # Admin routes
│       │   ├── 🔐 (app)/          # Authenticated user routes
│       │   ├── 🔑 (auth)/         # Authentication routes
│       │   └── 🌍 (public)/       # Public routes
│       ├── 🧩 components/         # React components
│       │   ├── 🔐 auth/           # Authentication components
│       │   ├── 📚 books/          # Book-related components
│       │   ├── 🏠 site/           # Site-wide components
│       │   └── 🎨 ui/             # UI primitives
│       ├── 🛠️ lib/                # Utilities and helpers
│       ├── 📂 public/             # Static assets
│       └── 📧 templates/          # Email templates
├── 📄 package.json                # Root package.json
└── ⚙️ pnpm-workspace.yaml         # Workspace configuration

⚙️ Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Installation
🟢 Node.js	18.x or higher	Download
📦 pnpm	9.0.0 or higher	npm install -g pnpm@9.0.0

📦 Installation

Step 1: Clone the repository

git clone <repository-url>
cd nuba

Step 2: Install dependencies

pnpm install

💡 This will install dependencies for both the root workspace and the packages/web package.

💻 Development

🚀 Starting the Development Server

Option 1: From the root directory (Recommended)

pnpm dev

Option 2: Navigate to the web package

cd packages/web
pnpm dev

🌐 The application will be available at http://localhost:3000

📜 Available Scripts

From Root Directory

Command	Description
pnpm dev	🚀 Start the development server
pnpm build	🏗️ Build the application for production
pnpm start	▶️ Start the production server (requires build first)
pnpm lint	🔍 Run ESLint

From packages/web

Command	Description
pnpm dev	🚀 Start the development server
pnpm build	🏗️ Build for production
pnpm start	▶️ Start production server
pnpm lint	🔍 Run linting

🔐 Environment Variables

Create a .env.local file in packages/web/ with the necessary environment variables.

⚠️ Note: Check with the team for required configuration values.

Example structure:

# .env.local
NEXT_PUBLIC_API_URL=your_api_url
DATABASE_URL=your_database_url
# ... other variables

🏗️ Building for Production

Step 1: Build the application

pnpm build

Step 2: Start the production server

pnpm start

✅ Your production-ready application will be running!

📐 Architecture Guidelines

This project follows strict architectural guidelines documented in nested agents.md files:

Principle	Description
🖥️ Server Components First	Prefer Server Components; use "use client" only for interactive leaves
🔄 Server Actions	All mutations via Server Actions (no API routes)
📘 TypeScript	Strict typing with explicit interfaces for domain entities
🎨 Styling	Tailwind CSS with brand colors (Teal #00AEB6, hover #00959C) and 16px border radius
♿ Accessibility	Focus-visible, proper labels, semantic HTML

📚 Documentation Files

• 📄 agents.md - Root architecture overview
• 🌐 packages/web/agents.md - Web app standards
• 🛣️ packages/web/app/agents.md - Routing and component patterns
• 🧩 packages/web/components/agents.md - Component patterns

🎨 Design Resources

Resource	Link
📱 Figma Prototype (Mobile)	View Prototype
🎨 Figma Design File	View Design

---

📄 License

MIT License - Copyright (c) 2025 Baleares Group

💬 Support

For questions or issues, please contact the development team.

Made with ❤️ by Baleares Group

⬆ Back to Top