Nox

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