Skip to content

README.md

Latest commit

 

History

History
80 lines (64 loc) · 3.64 KB

README.md

File metadata and controls

80 lines (64 loc) · 3.64 KB
Raw

TextStack docs

TextStack is a free reading app: upload a book, read it on the web or on Android, save words, talk about a chapter with your AI assistant. These pages are for people who run the code or change it. Readers find help inside the app at textstack.app.

What do you want to do?

Run it locally

From a clone to the app running on your machine with Docker.

Ship a first PR

Branch, change, checks, area label, pull request.

Self-host

It runs locally today. Production self-hosting is not packaged yet: what works, what is missing.

Understand the architecture

The services, how a book moves through them, and why they are built this way.

Where the project is now

TextStack is moving to V2: a second database, a new reader, one cutover. Part of it is live and part is behind a flag.

  • STATUS.md: what is in flight, what is known broken, what we decided not to do.
  • V2 architecture: the map of V2 and its boundaries.
  • Changelog: merged pull requests by week.

Architecture

Page What it answers
Overview Which services exist and what each one does
Flows How a request moves between them, one diagram per scenario
Data model Every table: purpose, status, personal data
Data access The rules for repositories and SQL
Frontend The apps and the shared packages
Delivery How a commit reaches production
Decisions (ADRs) Why each load-bearing choice was made; read the status line first

Guides

Reference

  • Environment variables
  • MCP server: connect TextStack to an AI assistant
  • API reference: generated from the code. Run the app, then open http://localhost:8080/scalar/v1.

Rules for these docs

  • A change to a command, an environment variable, a route, a flag or a setup step edits the page that states it, in the same pull request.
  • One home per fact. The API reference and the changelog are generated, never written by hand.
  • A new decision that is hard to reverse, or that touches several modules, gets an ADR.
  • Links are checked in CI: node scripts/check-doc-links.mjs.

Internal notes

internal/ holds the maintainer's working material: operations of the production server, incident postmortems, V2 design drafts, feature specs, QA reports, the frozen changelog archive and legacy/ (what the V2 cutover removes). It is public, but not written for a first read.