docs: complete README rewrite with architecture, features, API, and setup
This commit is contained in:
renato97
298
README.md
298
README.md
@@ -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).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Stack
|
**AI-powered study platform. Chat with your notes, fork topics, track progress — all local, all yours.**
|
||||||
- **Backend**: Node.js + Express + SQLite (sql.js, WASM — sin compilación nativa)
|
|
||||||
- **Frontend**: React 18 + Vite
|
|
||||||
- **Streaming**: Server-Sent Events (SSE)
|
|
||||||
|
|
||||||
## Requisitos
|
</div>
|
||||||
- Node.js 18+
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
|
# 1. Install
|
||||||
cd studyos/server && npm install
|
cd studyos/server && npm install
|
||||||
cd studyos/client && 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
|
## Production
|
||||||
# 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd studyos/client && npm run build
|
cd studyos/client && npm run build
|
||||||
cd studyos/server && node index.js
|
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/
|
||||||
├── server/ # Backend Express
|
├── index.js # Express + WebSocket server, async DB init
|
||||||
│ ├── index.js # Servidor principal + init async
|
├── db.js # sql.js schema, migrations, seed
|
||||||
│ ├── db.js # Schema SQLite vía sql.js (WASM) + seed
|
├── systemPromptBuilder.js # Context-aware prompt: PDFs, progress, RAG, difficulty
|
||||||
│ ├── lib/llm.js # Adaptador SSE (Anthropic + OpenAI)
|
├── lib/
|
||||||
│ ├── routes/ # Endpoints REST
|
│ ├── llm.js # Dual SSE adapter (Anthropic SDK + OpenAI SDK)
|
||||||
│ └── systemPromptBuilder.js
|
│ ├── embeddings.js # @xenova/transformers pipeline (webgpu → wasm)
|
||||||
├── client/ # Frontend React + Vite
|
│ ├── rag.js # chunkText, cosineSimilarity, searchRelevant
|
||||||
│ └── src/
|
│ ├── broadcast.js # WebSocket broadcast with buddy support
|
||||||
│ ├── components/ # Sidebar, MainChat, ForkPanel, etc.
|
│ └── sm2.js # SM-2 spaced repetition algorithm
|
||||||
│ ├── hooks/ # useChat, usePdfs, useProgress
|
└── routes/
|
||||||
│ ├── pages/ # Settings
|
├── chat.js # SSE streaming, RAG pipeline, auto-fork, difficulty
|
||||||
│ └── lib/ # API client
|
├── conversations.js # CRUD, fork, merge, study buddy share/join
|
||||||
└── data/ # SQLite database (auto-creado)
|
├── 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)
|
client/src/
|
||||||
3. Configurá tus API keys en Settings → Modelos
|
├── components/
|
||||||
4. El endpoint VLM por defecto es `http://localhost:8080/vlm`
|
│ ├── 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)
|
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.
|
||||||
- 📄 Subida y procesamiento de PDFs
|
|
||||||
- 📊 Seguimiento de progreso por tema
|
---
|
||||||
- 🔀 Micro-chats temáticos (fork/merge)
|
|
||||||
- 🎨 Tema oscuro con diseño pulido
|
## API Overview
|
||||||
- ⚙️ Configuración de modelos y VLM
|
|
||||||
|
| 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
|
||||||
|
|||||||
Reference in New Issue
Block a user