---

What is Shiori?

Shiori (栞, bookmark in Japanese) is an open-source AI study companion built for students who take their grades seriously. It combines AI-powered study tools, gamification, and productivity features into one beautiful dark-mode app.

No subscription required for core features. Bring your own free Gemini API key. Self-hostable in 5 minutes.

🎮 Try the live demo — no account, no API key needed.

---

✨ Features

Feature	Description
🤖 AI Quiz Generator	Generate MCQ quizzes from your notes with Gemini AI
🃏 AI Flashcards	Auto-generate spaced repetition flashcard decks
📊 Grade Tracker	Weighted grade calculator with GPA predictor
📅 Assignment Manager	Due dates, priorities, completion tracking
📝 Markdown Notes	Two-panel editor with live preview
🎯 Focus Mode	Pomodoro timer with task linking
🏆 Leaderboard	Compare XP and streaks with friends
📈 Analytics	Study time, grade trends, completion rates
🌱 Habit Tracker	Daily habit streaks with completion heatmap
🗓 Study Plans	AI-generated day-by-day study schedules
📚 Syllabus Import	Parse syllabi to auto-create assignments
⌨️ Keyboard Shortcuts	Power-user navigation (gh, ga, gn, gq...)
🎮 Gamification	XP system, levels (Freshman → Graduate), achievements

---

🚀 Quick Start

Option 1: Live demo (no setup)

👉 shiori-v1.vercel.app/demo

No account. No API key. Full experience.

Option 2: Deploy to Vercel (1 click)

Deploy with Vercel

Option 3: Self-host locally

Prerequisites: Node.js 18+, free Supabase account, free Gemini API key

# Clone
git clone https://github.com/kaorii-ako/Shiori-v1.git
cd Shiori-v1

# Configure
cp .env.example .env
# Edit .env with your Supabase URL + anon key

# Run Supabase schema
# → Open supabase/schema.sql in your Supabase SQL Editor and run it

# Install + start
npm install
npm run dev

Open http://localhost:5173 → click Try Demo or sign up.

Environment Variables

Variable	Required	Where to get
VITE_SUPABASE_URL	✅ Yes	supabase.com → Settings → API
VITE_SUPABASE_ANON_KEY	✅ Yes	supabase.com → Settings → API
VITE_GEMINI_API_KEY	Optional	aistudio.google.com/apikey (free)

---

🏗 Tech Stack

Frontend:   React 18 + Vite + Zustand
Database:   Supabase (PostgreSQL + Auth)
AI:         Google Gemini 1.5 Flash (client-side, BYOK)
Deployment: Vercel

---

⌨️ Keyboard Shortcuts

Shortcut	Action
g h	Go to Home
g a	Go to Assignments
g n	Go to Notes
g f	Go to Flashcards
g q	Go to Quiz
g g	Go to Grades
?	Show all shortcuts

---

📁 Project Structure

Shiori-v1/
├── client/               # React + Vite frontend
│   └── src/
│       ├── pages/        # 16 pages (Home, Assignments, Grades, Notes...)
│       ├── components/   # Shared components (Sidebar, GlassCard, AIChat...)
│       ├── stores/       # Zustand state management
│       ├── utils/        # theme.js, gemini.js, demoData.js
│       └── lib/          # supabase.js, db.js
├── server/               # Express.js backend (optional, for Stripe webhooks)
├── extension/            # Chrome MV3 extension
├── supabase/             # Database schema + setup guide
└── docs/                 # Screenshots, specs

---

🤝 Contributing

Contributions are welcome! Shiori is built by students for students.

1. Check good first issues
2. Read CONTRIBUTING.md
3. Fork → branch → PR

---

📄 License

MIT — free for personal and commercial use.

---