Skip to content

README.md

Latest commit

 

History

History
151 lines (113 loc) · 4.15 KB

README.md

File metadata and controls

151 lines (113 loc) · 4.15 KB

Nox Books Platform

Stremio-inspired discovery and reading platform for books with plugin-based sources.

1. Full System Architecture

  • Frontend: dark-themed dashboard and reader (desktop + responsive mobile)
  • Backend API: FastAPI
  • Data: PostgreSQL for persistence, Redis for cache/rate limiting
  • Metadata providers:
    • Primary: Open Library API
    • Fallback: Google Books API
  • Plugin system:
    • Install by plugin manifest URL
    • Resource endpoints: /catalog, /meta, /sources
    • Per-user plugin enable/disable
    • Runtime dynamic resolution without restart

2. Folder Structure

  • backend/ FastAPI app, SQLAlchemy models, provider integration, plugin orchestrator
  • frontend/ dashboard and reader UI
  • plugin-sdk/ manifest schema and sample plugin
  • deploy/ nginx config
  • docker-compose.yml full local stack

3. Backend Implementation

  • Auth: register/login with JWT
  • Discovery: rails for trending/popular/recommended/new releases
  • Search: title/author/ISBN/subject through local + provider merge
  • Library: bookmark/reading/completed
  • Reader APIs: progress updates and retrieval
  • Caching: Redis-backed search/discovery caching
  • Rate limiting: per-IP middleware

4. Plugin System Implementation

  • Install plugin with POST /api/v1/plugins/install
  • Manifest validation for required fields
  • Source and metadata aggregation from enabled plugins
  • Per-user enable/disable state via POST /api/v1/plugins/state

5. API Integration

  • Open Library:
    • search: /search.json
    • details: /works/{id}.json
    • subject rails: /subjects/{subject}.json
  • Google Books fallback:
    • search/details from /volumes

6. Database Schema

Implemented in SQLAlchemy and mirrored in backend/schema.sql.

Core tables:

  • users
  • books_cache
  • user_library
  • reading_progress
  • collections
  • collection_books
  • reading_history
  • installed_plugins
  • user_plugin_state

7. Frontend Implementation

  • UI based on provided design layout:
    • left navigation panel
    • central discovery + synopsis area
    • right quick library panel
  • Search has a dedicated results section and does not overwrite Continue Reading
  • Clicking a book opens a rich detail view with synopsis, metadata, plugin sources, and external read or buy links
  • dark theme with high contrast and matching density
  • responsive behavior for tablet/mobile

8. Reader Implementation

  • Supports:
    • EPUB through epub.js
    • PDF through pdf.js
    • TXT directly
  • Features:
    • adjustable font size
    • dark mode toggle
    • chapter list (EPUB)
    • progress slider and progress save API
    • Stremio-like source-first flow: reader is effectively unlocked when plugin sources are available

9. Plugin SDK

See plugin-sdk/README.md:

  • manifest specification
  • endpoint contracts
  • sample plugin and run instructions

10. Deployment Instructions

Local Docker Deployment

  1. docker compose up --build
  2. Frontend: http://localhost:8080
  3. Backend health: http://localhost:8000/health
  4. API docs: http://localhost:8000/docs

Manual Backend Run (No Docker)

  1. cd backend
  2. python -m venv .venv
  3. Copy-Item .env.example .env -Force
  4. .venv\\Scripts\\python.exe -m pip install -r requirements.txt
  5. .venv\\Scripts\\python.exe -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Defaults are local-friendly:

  • DATABASE_URL=sqlite:///./nox.db
  • REDIS_URL=redis://localhost:6379/0

If Redis is not running, the app falls back to an in-memory cache automatically.

Manual Frontend Run (No Docker)

  1. cd frontend
  2. python -m http.server 8080
  3. Open http://localhost:8080

One-Command Windows Scripts

  • Backend: ./scripts/start-backend.ps1
  • Frontend: ./scripts/start-frontend.ps1
  • Smoke test: ./scripts/smoke-test.ps1

Sample Plugin Run

  1. cd plugin-sdk/sample-plugin
  2. pip install -r requirements.txt
  3. uvicorn main:app --reload --port 9001
  4. Install via API using http://localhost:9001/manifest.json

Security and Scale Notes

  • Input validation on all API payloads
  • per-IP request throttling
  • plugin timeout and payload size controls
  • Redis cache layer for hot endpoints
  • stateless API for horizontal scaling
  • CDN-ready static frontend and cover URLs