Skip to content

Latest commit

 

History

History

docs

README.md

TextStack Documentation

Free book library with Kindle-like reader. EPUB/PDF/FB2 upload, parsing, SEO pages, and offline reading.

Live: textstack.app (public) · textstack.dev (admin)

Quick Links

Document Description
CLAUDE.md AI assistant context (commands, key files, concepts)
CHANGELOG.md Version history and recent changes
Vision Goals, principles, stack
Architecture System design
Database Schema, entities
API Docs http://localhost:8080/scalar/v1 (live)
Local Dev Docker, migrations
Environment Variables Complete env var reference
Production Deployment Cloudflare tunnel, nginx, Docker
E2E Testing Guide Playwright setup, UI mode, troubleshooting

Core Features

Feature Description Docs
Reader Kindle-like reading (settings, navigation, mobile) reader.md
Offline IndexedDB caching, download manager offline-reading.md
Auth Google OAuth, JWT, user features user-auth.md
Search PostgreSQL FTS, fuzzy search feat-0006
Vocabulary SRS vocab builder + Ollama LLM vocabulary-srs.md
Ingestion EPUB parsing, chapter extraction ingestion.md

Structure

docs/
├── 00-vision/          # Why: goals, roadmap
├── 01-architecture/    # How: design, ADRs
├── 02-system/          # What: schemas, APIs
├── 03-ops/             # Run: setup, deploy
├── 04-dev/             # Build: test, security
└── 05-features/        # Feature PDDs

Features

Implemented

Feature Docs
Kindle-like Reader reader.md
Offline Reading offline-reading.md
User Auth & Library user-auth.md
Full-text Search feat-0006
Text Extraction feat-0003
Observability feat-0005
i18n (EN/UK) Full Ukrainian translation for all pages
E2E Testing Playwright e2e tests with CI pipeline
Text Selection Highlights, translate, dictionary in reader
Vocabulary SRS Spaced repetition vocab builder with Ollama LLM distractors
Reading Stats Heatmap, streaks, goals, achievements

Reading Order

  1. New to project: Vision → Architecture → Local Dev
  2. Backend work: Database → Ingestion → API Docs (Scalar)
  3. Frontend work: Reader → Offline → Auth
  4. Ops: Local Dev → Production Deployment → Backup

ADRs (Architectural Decisions)

ADR Title
001 Storage via bind mounts (superseded by ADR-007)
002 Google OAuth only
003 Work/Edition data model
004 PostgreSQL FTS
005 Multisite via Host (superseded by ADR-007)
006 Modular monolith
007 Single domain consolidation

Governance

When to Update Docs

Event Update
Entity added database.md
Endpoint added (auto in Scalar)
Architecture decision New ADR
Migration created Mention if significant
New page type (indexable/not) seo-implementation.md

When ADR Required

  • Choosing between 2+ valid approaches
  • Decision affects multiple modules
  • Hard to reverse
  • Security implications