Quietude transforms how you learn by combining artificial intelligence with thoughtful design. Upload any study material, and watch as it becomes an interactive learning journey with AI-generated quizzes, personalized study notes, and progress tracking — all wrapped in a calming, adaptive interface that shifts with the time of day.
Getting Started · Features · Architecture · Documentation · Contributing
"In the midst of movement and chaos, keep stillness inside of you." — Deepak Chopra
Modern learning tools often overwhelm with notifications, gamification, and visual noise. Quietude takes a different path — one of intentional simplicity and focused calm. The application adapts to your natural rhythm, shifting its visual atmosphere from morning mist to midnight study, ensuring your environment supports rather than distracts from deep learning.
|
Upload PDFs, images, audio files, or paste text directly. Quietude's AI engine analyzes your material, identifies topics, and automatically structures a personalized study plan. Supported Formats:
|
Three question types tailored to your content:
Pass at 75% to unlock the next topic, or Dig Deeper for advanced challenges. |
||||||||||||||||||
|
The interface naturally transitions through five time-based themes:
Plus five mood overrides: Sage, Storm, Sand, Plum, and Ink. |
When you score below 75%, Quietude generates comprehensive study notes featuring:
Notes are cached for 24 hours to minimize API usage. |
||||||||||||||||||
|
Study anywhere, even without internet:
|
Track your progress with detailed statistics:
|
┌─────────────────────────────────────────────────────────────────────────────┐
│ QUIETUDE ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Landing │ │ Dashboard │ │ Learn │ │ Quiz │ │
│ │ Page │───▶│ Page │───▶│ Page │───▶│ Page │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ZUSTAND STATE LAYER │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Auth │ │ Quiz │ │ Notes │ │Sessions │ │ Paths │ ... │ │
│ │ │ Store │ │ Store │ │ Store │ │ Store │ │ Store │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ └───────┼──────────┼──────────┼──────────┼──────────┼─────────────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PERSISTENCE & SYNC LAYER │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ localStorage │ │ IndexedDB │ │ Firebase │ │ │
│ │ │ (Zustand) │ │ (idb-keyval) │ │ (Firestore) │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ GEMINI AI ENGINE │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Multi-Key Pool Manager │ │ │
│ │ │ • 6 API keys with automatic rotation │ │ │
│ │ │ • 24-hour exhaustion cooldown │ │ │
│ │ │ • Instant failover on quota errors │ │ │
│ │ │ • Smart retry with key switching │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Analysis │ │ Quiz │ │ Notes │ │ │
│ │ │ Prompts │ │ Prompts │ │ Prompts │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ │ │ │ │ │
│ User Upload │─────▶│ Gemini Analyze │─────▶│ Topic Map │
│ (PDF/Image/ │ │ (content → │ │ Generated │
│ Audio/Text) │ │ topics) │ │ │
│ │ │ │ │ │
└──────────────────┘ └──────────────────┘ └────────┬─────────┘
│
▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ │ │ │ │ │
│ Study Notes │◀─────│ Score < 75% │◀─────│ Take Quiz │
│ Generated │ │ │ │ (10 questions) │
│ │ │ │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│
│ Score ≥ 75%
▼
┌──────────────────┐
│ │
│ Next Topic │
│ Unlocked │
│ │
└──────────────────┘
| Category | Technology | Purpose |
|---|---|---|
| Framework | React 18 + TypeScript | Component architecture with type safety |
| Build Tool | Vite 5 | Lightning-fast HMR and optimized builds |
| Styling | TailwindCSS + CSS Variables | Utility-first with dynamic theming |
| UI Components | Radix UI + shadcn/ui | Accessible, unstyled primitives |
| Animation | Framer Motion | Declarative animations and gestures |
| State Management | Zustand | Lightweight stores with persistence |
| AI Integration | Google Gemini 2.5 Flash | Content analysis, quiz generation, notes |
| Backend | Firebase (Firestore) | Database, auth infrastructure, sync |
| EmailJS | OTP delivery for passwordless auth | |
| Offline Storage | idb-keyval (IndexedDB) | Client-side persistence |
| PWA | vite-plugin-pwa + Workbox | Service worker and caching |
| Charts | Recharts | Statistics visualization |
| Forms | React Hook Form + Zod | Form handling with validation |
| Testing | Vitest + Testing Library | Unit and integration testing |
- Node.js 18.x or higher
- pnpm (recommended) or npm
- Firebase project (free tier works)
- Google AI Studio API keys
- EmailJS account (for OTP emails)
# Clone the repository
git clone https://github.com/Ns81000/quietude.git
cd quietude
# Install dependencies
pnpm install
# Copy environment template
cp .env.example .envCreate a .env file with the following variables:
# Firebase Configuration
VITE_FIREBASE_API_KEY=your-firebase-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id
# Gemini API Keys (supports up to 6 for load balancing)
VITE_GEMINI_KEY_1=your-gemini-key-1
VITE_GEMINI_KEY_2=your-gemini-key-2
VITE_GEMINI_KEY_3=your-gemini-key-3
VITE_GEMINI_KEY_4=your-gemini-key-4
VITE_GEMINI_KEY_5=your-gemini-key-5
VITE_GEMINI_KEY_6=your-gemini-key-6
# EmailJS Configuration
VITE_EMAILJS_SERVICE_ID=your-service-id
VITE_EMAILJS_TEMPLATE_ID=your-template-id
VITE_EMAILJS_PUBLIC_KEY=your-public-key
# Security
VITE_OTP_SALT=your-random-salt-string# Start development server
pnpm dev
# Run tests
pnpm test
# Build for production
pnpm build
# Preview production build
pnpm previewDetailed documentation for each system component:
| Document | Description |
|---|---|
| Architecture Overview | System design, component relationships, data flow |
| Gemini AI Mechanism | Key pool management, prompts, parsers, caching |
| Theme System | Time-based themes, mood overrides, CSS variables |
| Quiz Mechanism | Learning phases, question types, answer matching |
| State Management | Zustand stores, persistence, selectors |
| Authentication | OTP flow, session management, security |
| Sync Mechanism | Offline-first sync, queue processing, conflict resolution |
| PWA Features | Service worker, caching strategies, offline storage |
| Database Schema | Tables, relationships, RLS policies |
quietude/
├── public/ # Static assets
│ ├── robots.txt
│ └── site.webmanifest
├── src/
│ ├── components/ # React components
│ │ ├── auth/ # Authentication components
│ │ ├── dashboard/ # Dashboard widgets
│ │ ├── layout/ # Shell, navigation, theming
│ │ ├── learn/ # Study plan, topic roadmap
│ │ ├── notes/ # Note cards, viewer
│ │ ├── quiz/ # Quiz components
│ │ ├── stats/ # Charts, calendar, tables
│ │ ├── ui/ # shadcn/ui components
│ │ └── upload/ # Drop zone, paste area
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Core utilities
│ │ ├── gemini/ # AI integration
│ │ ├── pwa/ # Service worker, offline
│ │ └── firebase/ # Firestore client, sync
│ ├── pages/ # Route pages
│ ├── store/ # Zustand state stores
│ ├── test/ # Test utilities
│ └── types/ # TypeScript definitions
├── docs/ # Documentation
└── package.json
Quietude implements a sophisticated state machine for the learning journey:
IDLE ──▶ UPLOADING ──▶ ANALYSING ──▶ TOPIC_MAP_READY
│
▼
TOPIC_COMPLETE ◀── NOTES_READY ◀── QUIZ_RESULT_FAIL
│ │
│ QUIZ_RESULT_PASS
│ │
▼ ▼
DIG_DEEPER_ACTIVE NOTES_GENERATING
│ │
└────────────────────────────────────┘
│
▼
TOPIC_SELECTED ──▶ CONFIGURING ──▶ QUIZ_GENERATING
│
▼
QUIZ_ACTIVE
│
▼
QUIZ_SUBMITTING
Quietude implements production-grade API key rotation:
// Key Pool Features:
• Supports 1-6+ API keys
• Automatic rotation based on usage
• Instant failover on quota errors
• 24-hour cooldown for exhausted keys
• Smart retry with key switching
• Usage tracking per key
• Health monitoringWhen all keys are exhausted, the system gracefully falls back to demo mode with mock data.
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow TypeScript strict mode
- Use conventional commits
- Write tests for new features
- Update documentation as needed
This project is licensed under the MIT License — see the LICENSE file for details.
