https://github.com/po4yka/ratatoskr-web
React/TypeScript web client for Ratatoskr — read summaries, manage collections, and trigger on-demand summarization from your browser or Telegram Mini App.
https://github.com/po4yka/ratatoskr-web
information-retrieval react reader-app self-hosted spa summarization telegram-webap typescript vite
Last synced: 17 days ago
JSON representation
React/TypeScript web client for Ratatoskr — read summaries, manage collections, and trigger on-demand summarization from your browser or Telegram Mini App.
- Host: GitHub
- URL: https://github.com/po4yka/ratatoskr-web
- Owner: po4yka
- License: bsd-3-clause
- Created: 2026-05-09T05:38:25.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-25T13:05:17.000Z (24 days ago)
- Last Synced: 2026-05-25T15:12:12.513Z (24 days ago)
- Topics: information-retrieval, react, reader-app, self-hosted, spa, summarization, telegram-webap, typescript, vite
- Language: TypeScript
- Homepage:
- Size: 39 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Ratatoskr Web
React/TypeScript/Vite frontend for the Ratatoskr summarization platform.
[](https://github.com/po4yka/ratatoskr-web/actions/workflows/ci.yml) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](LICENSE)
---
Ratatoskr Web is the web interface for the [Ratatoskr](https://github.com/po4yka/ratatoskr) summarization platform. It is built as a standalone Vite SPA and served same-host by the Ratatoskr backend FastAPI at `/web/*`. Source code lives here; build artifacts are deployed into the backend's `app/static/web/` directory.
## Quick start
```bash
npm ci
cp .env.example .env # set VITE_API_BASE_URL for local dev
npm run dev # Vite dev server at http://localhost:5173
```
A running backend is required for API calls. Set `VITE_API_BASE_URL=http://localhost:8000` in `.env` to point the dev server at a local backend instance.
## Deployment
`npm run build` produces a `dist/` directory. That directory must be placed into the backend's `app/static/web/` before deploying the backend container — FastAPI then serves it at `/web` and `/web/*`, with assets at `/static/web/`.
In the monorepo era this copy step was performed by a `Dockerfile COPY` instruction. Now that the repos are separate, it is a CI/CD pipeline step: the pipeline builds ratatoskr-web, copies `dist/` into the backend workspace, then builds and pushes the backend container.
## Environment variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `VITE_API_BASE_URL` | No | `` (empty) | Backend origin. Empty means same-origin (used when served by FastAPI). Set to `http://localhost:8000` for local dev. |
| `VITE_TELEGRAM_BOT_USERNAME` | No | `` (empty) | Telegram bot username for Mini App WebApp auth. Required for the Telegram Login Widget in JWT mode. |
| `VITE_ROUTER_BASENAME` | No | `/web` | Router basename. Must match the FastAPI serving path. |
| `VITE_SENTRY_DSN` | No | `` (empty) | Sentry DSN for error tracking. Leave empty to disable. |
## Design system
The frontend uses the Frost design system (`src/design/`): editorial monospace minimalism with a two-color rule (ink + page) and a single critical accent (spark). All tokens are prefixed `--frost-*`. Read `DESIGN.md` at the repo root before making any UI changes. Never use raw hex values; always use `var(--frost-*)` custom properties.
## Testing
```bash
npm run check:static # TypeScript + ESLint (required before any PR)
npm run test # Vitest unit tests
npm run test:e2e # Playwright E2E (requires a running server)
npm run test:visual # Visual regression (Playwright snapshots)
npm run test:visual:update # Update baselines — commit together with the code change
```
Visual baseline PNGs are committed to the repository alongside their specs under `src/tests/e2e/`. See `docs/reference/visual-regression.md` for the full baseline workflow and CI behavior.
## OpenAPI types
TypeScript types in `src/api/` are generated from the local OpenAPI spec at `docs/openapi/mobile_api.yaml`. When the backend contract changes, update the spec file then run `npm run generate:api` to regenerate. Never hand-edit the generated files in `src/api/` directly — they will be overwritten on the next generation run.
## Architecture map
Auth lives in `src/auth/` plus refresh handling in `src/api/client.ts`; generated API contracts live in `docs/openapi/mobile_api.yaml` and `src/api/generated.ts`; curated API wrappers live in `src/api/*.ts`; request-progress streaming lives in `src/api/streamRequest.ts`, `src/hooks/useRequestStream.ts`, and `src/features/submit/SubmitPage.tsx`. To refresh contracts, bump `tools/openapi.lock`, run `npm run generate:api`, then verify with `npm run check:api`, `npm run check:api-types`, and `npm run check:static`.
## Links
| Topic | Link |
|---|---|
| Backend repo | |
| Frontend architecture guide | [docs/reference/frontend-web.md](docs/reference/frontend-web.md) |
| Visual regression guide | [docs/reference/visual-regression.md](docs/reference/visual-regression.md) |
| Frost design system spec | [DESIGN.md](DESIGN.md) |
| API contract (OpenAPI) | [docs/openapi/mobile_api.yaml](docs/openapi/mobile_api.yaml) |
---
Released under the terms of [LICENSE](LICENSE). Bug reports and pull requests are welcome at [github.com/po4yka/ratatoskr-web/issues](https://github.com/po4yka/ratatoskr-web/issues).