104 lines
4.6 KiB
Markdown
104 lines
4.6 KiB
Markdown
# Chitai
|
|
|
|
Self-hosted eBook library manager. Users organise eBook files into **libraries**, which contain
|
|
**books** (one book = one metadata record + one or more files on disk). Books carry authors,
|
|
publishers, tags, series and identifiers, can be grouped into per-user **bookshelves**, and are read
|
|
in-browser through built-in EPUB and PDF readers with reading-progress tracking. The catalogue is
|
|
also exposed as an **OPDS** feed for e-reader apps, and progress syncs with **KOReader** devices via
|
|
a KOSync-compatible endpoint.
|
|
|
|
## Layout
|
|
|
|
| Path | What |
|
|
| --- | --- |
|
|
| `backend/` | Litestar REST API + PostgreSQL. See `backend/AGENTS.md`. |
|
|
| `frontend/` | SvelteKit SSR web app. See `frontend/AGENTS.md`. |
|
|
| `docker-compose.yml` | Production stack: `db` (postgres:17), `backend`, `frontend`. |
|
|
| `docs/screenshots/` | Images used by `README.md`. |
|
|
| `shell.nix` | Root dev shell; composes the two sub-shells. |
|
|
|
|
## Development environment
|
|
|
|
`nix-shell` from the repo root is the intended entry point. It pulls in both
|
|
`backend/shell.nix` and `frontend/shell.nix`, whose `shellHook`s do real work as a side effect:
|
|
|
|
- **backend** — `uv venv` + `uv sync`, then `initdb` / `pg_ctl start` into `backend/.postgres/`
|
|
(socket dir, not TCP), `createdb chitai`, and finally applies migrations with
|
|
`alchemy --config chitai.database.config.config upgrade --no-prompt`.
|
|
`exitHook` stops PostgreSQL on shell exit.
|
|
- **frontend** — `pnpm install`.
|
|
|
|
So entering the shell gives you a running database with an up-to-date schema; you do not need to
|
|
start Postgres yourself. Both hooks `cd` around, which can be surprising in scripts.
|
|
|
|
Without Nix you need: Python 3.13 + `uv`, Node 24 + `pnpm`, and PostgreSQL 17 with the `pg_trgm`
|
|
extension available.
|
|
|
|
## Configuration
|
|
|
|
All backend settings are read by `backend/src/chitai/config.py` (`Settings`, pydantic-settings) with
|
|
the **`CHITAI_` prefix** from the repo-root `.env`. `.env.prod-example` is the template; copy it to
|
|
`.env` for a fresh deployment.
|
|
|
|
`.env` is gitignored and contains a real `CHITAI_TOKEN_SECRET` — do not print, copy or commit it.
|
|
|
|
The frontend reads exactly one variable, `VITE_BACKEND_API_URL`
|
|
(`frontend/src/lib/server/config.ts`, defaulting to `http://localhost:8000`).
|
|
|
|
## How a request flows
|
|
|
|
```
|
|
browser
|
|
└─ SvelteKit SSR node server
|
|
├─ hooks.server.ts reads `authToken` cookie, validates via GET /access/me,
|
|
│ populates locals.user / locals.api, redirects to /login otherwise
|
|
├─ $lib/api/*.remote.ts remote functions (query/command/form) → locals.api (ApiClient)
|
|
└─ routes/api/[...path] catch-all proxy, for browser-direct fetches (reader file streams)
|
|
└─ Litestar backend
|
|
└─ controllers/ → services/ → SQLAlchemy models → PostgreSQL
|
|
```
|
|
|
|
The JWT the frontend holds in the `authToken` cookie is the same bearer token the backend issues
|
|
from `POST /access/login`. The frontend never stores credentials beyond that cookie.
|
|
|
|
## Commands
|
|
|
|
Backend (from `backend/`):
|
|
|
|
```bash
|
|
uv run litestar --app-dir src/chitai/ run --reload # dev server on :8000
|
|
pytest tests/ # needs Docker (pytest-databases)
|
|
ruff format src/
|
|
alchemy --config chitai.database.config.config make-migrations
|
|
alchemy --config chitai.database.config.config upgrade
|
|
```
|
|
|
|
Frontend (from `frontend/`):
|
|
|
|
```bash
|
|
pnpm dev # vite dev server on :5173
|
|
pnpm build # adapter-node output in build/
|
|
pnpm check # svelte-check — run before finishing
|
|
pnpm lint # prettier --check + eslint
|
|
pnpm format # prettier --write
|
|
```
|
|
|
|
API docs are served by the running backend at `http://localhost:8000/schema/` (Swagger) and
|
|
`/schema/openapi.json`.
|
|
|
|
## Cross-cutting rules
|
|
|
|
- **Keep the two schema layers in sync.** Backend request/response shapes live in
|
|
`backend/src/chitai/schemas/` (Pydantic); the frontend mirrors them as Zod schemas in
|
|
`frontend/src/lib/schema/`. Changing one without the other produces runtime validation failures,
|
|
not type errors.
|
|
- **Regenerate the OpenAPI types** after changing API shapes.
|
|
`frontend/src/lib/schema/openapi/schema.d.ts` is generated from the backend's OpenAPI document
|
|
with `openapi-typescript` (a devDependency; there is no `package.json` script for it, so it is run
|
|
manually against a live backend).
|
|
- **Migrations are mandatory.** The app runs with `create_all=False`, so a model change without a
|
|
matching Alembic revision will not reach the database.
|
|
- **Commit messages** follow `type: summary` — `feat:`, `fix:`, `refactor:`, `chore:`.
|
|
- The three `README.md` files are user-facing. Agent-facing knowledge belongs in the `AGENTS.md`
|
|
files.
|