renato97/studyos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete README rewrite with architecture, features, API, and setup

Browse Source
This commit is contained in:
renato97
2026-06-08 18:20:43 -03:00
parent 4ff4302a8c
commit 49671bafe8
1 changed files with 247 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
README.md
View File

@@ -1,76 +1,272 @@
# StudyOS
<div align="center">
Plataforma de estudio personal con IA. Chat con streaming, seguimiento de progreso, procesamiento de PDFs, y micro-chats temáticos (fork/merge).
![StudyOS](https://img.shields.io/badge/StudyOS-7C3AED?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iMiI+PGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iMTAiLz48cGF0aCBkPSJNMTIgNmgtLjVhMy41IDMuNSAwIDEgMCAwIDdoMWMzLjE0IDAgMy41IDMgMS41IDUiLz48L3N2Zz4=)
![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)
![React](https://img.shields.io/badge/React-18-087ea4?logo=react)
![SQLite](https://img.shields.io/badge/SQLite-WASM-003b57?logo=sqlite&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-blue)
## Stack
- **Backend**: Node.js + Express + SQLite (sql.js, WASM — sin compilación nativa)
- **Frontend**: React 18 + Vite
- **Streaming**: Server-Sent Events (SSE)
**AI-powered study platform. Chat with your notes, fork topics, track progress — all local, all yours.**
## Requisitos
- Node.js 18+
</div>
## Instalación
---
## What StudyOS Does
Upload your PDFs, talk to an LLM that reads them, split conversations into topic-focused forks, do exercises, track your progress, review with flashcards, generate exams — all in one polished dark-UI interface. No cloud accounts, no data leaving your machine.
```
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ React 18 │────▶│ Express API │────▶│ SQLite (WASM) │
│ + Vite │◀────│ :3001 │ │ sql.js │
└─────────────┘ SSE └──────┬───────┘ └────────────────┘
│
┌─────────┼─────────┐
▼ ▼ ▼
┌────────┐ ┌──────┐ ┌──────────────┐
│ glm │ │ VLM │ │ Transformers │
│ 4.5-air│ │glm4.6v│ │ .js (local) │
└────────┘ └──────┘ └──────────────┘
```
## Features
### Chat & AI
- **Streaming chat** (SSE) — tokens appear in real time, dual adapter (Anthropic + OpenAI-compatible)
- **Multi-model** — configure any OpenAI-compatible endpoint, switch on the fly
- **Syntax highlighting** — `prismjs` with auto-language detection from code fences
- **LaTeX rendering** — `KaTeX` for all inline and block math
- **Graph rendering** — inline SVG coordinate planes via ` ```graph ` blocks
- **Voice input** — Web Speech API microphone to text
- **LaTeX editor** — real-time preview while typing
### PDF Processing
- **Upload & extract** — VLM extraction first (`glm-4.6v`), `pdfjs-dist` fallback
- **RAG search** — local embeddings via `@xenova/transformers` (ONNX Runtime + DirectML GPU), cosine similarity retrieval over chunks
- **Multi-PDF compare** — side-by-side view of two PDFs
- **Sidebar search** — FTS5 full-text search across all PDFs and messages, with LIKE fallback
### Study System
- **Conversations** — organized chat threads with file attachments
- **Forks** — branch any topic into a focused sub-chat, merge back when done
- **Auto-fork suggestion** — model detects when you're struggling and suggests a practice fork
- **Exercises** — model generates exercises, auto-detects correctness, logs to progress
- **Progress tracking** — per-topic stats (exercises done, correct, accuracy, difficulty)
- **Difficulty auto-adjust** — lowers difficulty after consecutive failures
- **Calendar heatmap** — GitHub-style study activity visualization
- **Pomodoro timer** — 25/5 minute cycles with browser notifications
### Exams & Flashcards
- **Exam generator** — AI generates exams from your progress data
- **Timed exams** — countdown timer, auto-submit on expiry, instant grading
- **Exam PDF export** — download any exam as printable PDF via `pdfkit`
- **Flashcard generator** — LLM creates Q&A cards from your PDFs and exercises
- **SM-2 spaced repetition** — science-backed review scheduling with ease factor
- **Review queue** — sidebar badge shows due cards
### Collaboration
- **Study buddy mode** — share a conversation via token, two users chat with AI referee
- **WebSocket real-time** — progress and buddy message push across tabs
### UI & UX
- **Dark/light theme** — toggle with CSS variables, persisted to localStorage, zero flash
- **Glassmorphism** — indigo/purple gradients, backdrop blur, micro-interactions
- **Sidebar** — collapsible sections, PDF reorder via drag-and-drop, search bar
- **Fork panel** — resizeable right panel, own chat context
- **Toasts** — context-based notification system for success/error feedback
- **Skeleton loading** — animated placeholders while data loads
- **Scroll-to-bottom FAB** — appears when scrolled up in chat
- **Keyboard shortcuts** — `Ctrl+N` new chat, `Ctrl+K` search, `Escape` close panels, `Ctrl+Enter` send
- **PWA** — install as native app via `vite-plugin-pwa`
- **Responsive** — sidebar auto-collapses on mobile with hamburger overlay
- **Message copy** — hover to reveal copy button on any message
### Infrastructure
- **Zero native deps** — `sql.js` WASM for SQLite, `@xenova/transformers` WASM for embeddings
- **Tests** — `vitest` (jsdom) on client, `node:test` on server
- **DB backup/restore** — download/upload SQLite file from Settings
- **Rate limiting** — client-side guard blocks concurrent sends
---
## Quick Start
```bash
# 1. Install
cd studyos/server && npm install
cd studyos/client && npm install
# 2. Run backend (terminal 1)
cd studyos/server && node index.js
# 3. Run frontend (terminal 2)
cd studyos/client && npm run dev
# 4. Open http://localhost:5173
```
## Desarrollo
First launch: the embeddings model (~118 MB) downloads automatically to `server/node_modules/.cache/transformers/`. Chat works immediately — embeddings are ready after the warmup completes (check server logs).
```bash
# Terminal 1 — Backend
cd studyos/server
node index.js
# Terminal 2 — Frontend
cd studyos/client
npm run dev
```
Abrí http://localhost:5173 en el navegador.
## Producción
## Production
```bash
cd studyos/client && npm run build
cd studyos/server && node index.js
# Everything served from http://localhost:3001
```
Todo se sirve desde http://localhost:3001.
## Configuration
## Estructura
Everything lives in the Settings page. No `.env` file needed.
| Setting | Default | Purpose |
|---------|---------|---------|
| Main model | None | LLM for chat (OpenAI-compatible endpoint) |
| Fork model | None | LLM used inside forks (falls back to main) |
| VLM endpoint | None | Vision model for PDF extraction |
| VLM API key | None | Key for the vision endpoint |
| Admin key | None | Required for DB backup/restore |
### Recommended: Z.ai
| Role | Model | Endpoint |
|------|-------|----------|
| Chat | `glm-4.5-air` | `https://api.z.ai/api/coding/paas/v4` |
| Vision | `glm-4.6v` | `https://api.z.ai/api/coding/paas/v4` |
StudyOS is provider-agnostic — any OpenAI-compatible endpoint works.
---
## Architecture
### Backend (`server/`)
```
studyos/
├── server/ # Backend Express
│ ├── index.js # Servidor principal + init async
│ ├── db.js # Schema SQLite vía sql.js (WASM) + seed
│ ├── lib/llm.js # Adaptador SSE (Anthropic + OpenAI)
│ ├── routes/ # Endpoints REST
│ └── systemPromptBuilder.js
├── client/ # Frontend React + Vite
│ └── src/
│ ├── components/ # Sidebar, MainChat, ForkPanel, etc.
│ ├── hooks/ # useChat, usePdfs, useProgress
│ ├── pages/ # Settings
│ └── lib/ # API client
└── data/ # SQLite database (auto-creado)
server/
├── index.js # Express + WebSocket server, async DB init
├── db.js # sql.js schema, migrations, seed
├── systemPromptBuilder.js # Context-aware prompt: PDFs, progress, RAG, difficulty
├── lib/
│ ├── llm.js # Dual SSE adapter (Anthropic SDK + OpenAI SDK)
│ ├── embeddings.js # @xenova/transformers pipeline (webgpu → wasm)
│ ├── rag.js # chunkText, cosineSimilarity, searchRelevant
│ ├── broadcast.js # WebSocket broadcast with buddy support
│ └── sm2.js # SM-2 spaced repetition algorithm
└── routes/
├── chat.js # SSE streaming, RAG pipeline, auto-fork, difficulty
├── conversations.js # CRUD, fork, merge, study buddy share/join
├── pdfs.js # Upload, VLM extraction, embedding generation
├── progress.js # Topic stats, study sessions, heatmap, exam PDF
├── exams.js # Generate, start, submit timed exams
├── flashcards.js # SSE generation, SM-2 reviews, due queue
├── search.js # FTS5 full-text search with LIKE fallback
├── models.js # LLM model CRUD, default exclusivity
├── config.js # Key-value config, VLM test, DB backup/restore
└── notes.js # Simple notes CRUD
```
## Configuración Inicial
### Frontend (`client/`)
1. La base de datos se crea automáticamente en `data/studyos.db`
2. El modelo por defecto es `claude-sonnet-4` (Anthropic)
3. Configurá tus API keys en Settings → Modelos
4. El endpoint VLM por defecto es `http://localhost:8080/vlm`
```
client/src/
├── components/
│ ├── Sidebar.jsx # Conv list, PDFs, search, theme toggle, nav
│ ├── MainChat.jsx # Chat area, graph panel, rename, scroll FAB
│ ├── MessageBubble.jsx # Markdown, KaTeX, Prism, reactions, copy
│ ├── ForkPanel.jsx # Resizeable fork chat panel
│ ├── ChatInput.jsx # Text area, voice input, LaTeX toggle, send
│ ├── SearchBar.jsx # FTS5 modal overlay with results
│ ├── ThemeToggle.jsx # Dark/light switch
│ ├── [17 more components] # All features listed above
├── hooks/
│ ├── useChat.js # SSE stream, send, fork/difficulty events
│ ├── useExam.js # Timer, auto-submit, navigation
│ ├── useFlashcards.js # Queue, review, due count
│ ├── usePdfs.js # Upload, reorder, delete, refresh
│ ├── useProgress.js # Stats, WebSocket subscription
│ ├── useSearch.js # Debounced FTS5 queries
│ ├── useStudyBuddy.js # Token join, WebSocket sync
│ └── [6 more hooks]
├── lib/
│ ├── api.js # All endpoint functions
│ └── sm2.js # Client-side SM-2 mirror
├── context/
│ └── ReactionsContext.jsx # 👍/👎 session-local state
├── pages/
│ └── Settings.jsx # Models, VLM, backup/restore, exam export, theme
└── data/
└── roadmap.json # Topic relationship graph
```
## Features
### Database
- 💬 Chat con streaming SSE (Anthropic + OpenAI-compatible)
- 📄 Subida y procesamiento de PDFs
- 📊 Seguimiento de progreso por tema
- 🔀 Micro-chats temáticos (fork/merge)
- 🎨 Tema oscuro con diseño pulido
- ⚙️ Configuración de modelos y VLM
SQLite via `sql.js` (WASM). Tables include `conversations`, `messages`, `pdfs`, `models`, `progress`, `exams`, `flashcards`, `flashcard_reviews`, `study_sessions`, `embeddings`, `shared_conversations`, `conversation_participants`, `topic_relationships`, plus FTS5 virtual tables for full-text search.
---
## API Overview
| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/api/chat/:id/stream` | SSE chat streaming |
| `GET/POST` | `/api/conversations` | List / create conversations |
| `POST` | `/api/conversations/:id/fork` | Create topic fork |
| `POST` | `/api/conversations/:id/merge` | Merge fork back |
| `POST` | `/api/conversations/:id/share` | Generate buddy token |
| `POST` | `/api/conversations/join` | Join buddy conversation |
| `POST` | `/api/pdfs/upload` | Upload PDF + extract + embed |
| `GET` | `/api/progress?main_id=:id` | Topic-level progress |
| `GET` | `/api/progress/heatmap?days=365` | Study activity data |
| `GET` | `/api/progress/exam/pdf` | Download exam as PDF |
| `POST` | `/api/exams/generate` | AI-generated exam |
| `POST` | `/api/exams/:id/submit` | Submit exam answers |
| `POST` | `/api/flashcards/generate` | SSE flashcard generation |
| `PUT` | `/api/flashcards/:id/review` | SM-2 review (quality 0-5) |
| `GET` | `/api/flashcards/reviews/due` | Due review queue |
| `GET` | `/api/search?q=term` | FTS5 search messages + PDFs |
| `GET` | `/api/config/backup` | Download DB (auth required) |
| `POST` | `/api/config/restore` | Upload DB (auth required) |
| `GET` | `/api/models` | Available chat models |
| `WS` | `ws://localhost:3001` | Progress push, buddy messages |
---
## Testing
```bash
# Client (vitest + jsdom)
cd studyos/client && npm test
# Server (node:test)
cd studyos/server && npm test
```
---
## Tech Stack
| Layer | Technology |
|-------|-----------|
| Runtime | Node.js 18+ |
| Backend | Express 4, `ws` |
| Database | SQLite via `sql.js` (WASM — zero native) |
| Frontend | React 18, Vite 5 |
| Routing | react-router-dom v6 |
| Markdown | react-markdown v9 |
| Math | KaTeX 0.17 |
| Syntax | Prism.js 1.30 |
| Charts | Recharts |
| Drag & drop | @dnd-kit |
| Icons | Lucide React |
| PWA | vite-plugin-pwa |
| Tests | Vitest + @testing-library/react (client), node:test (server) |
| LLM client | Anthropic SDK + OpenAI SDK |
| Embeddings | @xenova/transformers (local, WASM + DirectML) |
| PDF export | pdfkit |
| PDF extraction | pdfjs-dist |
## License
MIT