@digitalpaws/starr 0.0.1

package/README.rst

@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: 0BSD
+.. SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+============
+starr
+============
+
+The Starr host is the core runtime of the St\*arr media automation platform.
+It loads plugins from a configurable directory, provides them with an event
+bus, configuration, storage, and logging services, and exposes a Fastify-based
+web server with REST and SSE endpoints for the Svelte-based web UI.
+
+Architecture
+============
+
+::
+
+   ┌──────────────────────────────────────────────────┐
+   │                   Starr Host                      │
+   │  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+   │  │  Config   │  │  State   │  │   Auth/ OIDC   │  │
+   │  │  Service  │  │  Store   │  │   Services     │  │
+   │  └──────────┘  └──────────┘  └────────────────┘  │
+   │  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
+   │  │  Event   │  │  Importer│  │  Library/Cache │  │
+   │  │   Bus    │  │          │  │  Scanner       │  │
+   │  └──────────┘  └──────────┘  └────────────────┘  │
+   │  ┌────────────────────────────────────────────┐  │
+   │  │           Plugin Loader                     │  │
+   │  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐   │  │
+   │  │  │ Vid  │ │Books │ │Indxer│ │Downloader│ …  │  │
+   │  │  └──────┘ └──────┘ └──────┘ └──────────┘   │  │
+   │  └────────────────────────────────────────────┘  │
+   │  ┌────────────────────────────────────────────┐  │
+   │  │          Web Server (Fastify)              │  │
+   │  │  REST API · SSE · Static (web-ui dist)    │  │
+   │  └────────────────────────────────────────────┘  │
+   └──────────────────────────────────────────────────┘
+
+Dependencies
+============
+
+- **Runtime**: Fastify, better-sqlite3, argon2, openid-client, semver
+- **Types**: ``starr-types-core``
+- **Dev**: TypeScript, vitest, tsx (for development runner)
+
+Scripts
+=======
+
+============================  ===================================================
+Script                        Description
+============================  ===================================================
+``pnpm build``                Compile TypeScript to ``dist/``
+``pnpm dev``                  Run with ``tsx watch`` for development
+``pnpm test``                 Run Vitest test suite
+============================  ===================================================
+
+Environment Variables
+=====================
+
+See the root ``readme.rst`` for full documentation.
+
+Plugin API
+==========
+
+The host exports all types and utilities plugin authors need:
+
+- ``PluginContext`` — the context object passed to each plugin's ``register()``
+- ``EventBus`` — publish/subscribe on spine events
+- ``ConfigSchema`` / ``ConfigField`` — declarative config schemas
+- ``StateStore`` — durable state for requests and traces
+- ``AuthService`` — authentication and session management
+
+Plugins are loaded automatically from the directory pointed to by
+``STARR_PLUGINS_DIR`` (defaults to ``./plugins``).