Concepts

About 336 wordsAbout 1 min

The deep-dive reference for Spora’s internals. These pages were migrated from the numbered spora-core/docs/0X_*.md files, which have been retired in favour of this single audience-oriented site. For the procedural “how to install / configure / run” walkthrough, see Start → Operators.

Core architecture

Architecture — config priority, orchestrator loop, worker modes, plugin system, database
Database schema — tables, columns, version model, migration conventions
PHP interfaces — ToolInterface, OrchestratorInterface, LLMDriverConfigInterface, PluginInterface

Tools, drivers, plugins

LLM drivers — LLMDriverConfigInterface, OpenAICompatibleDriver, AnthropicCompatibleDriver, DriverFactory
Tool system — #[Tool], #[ToolOperation], #[ToolParameter], #[ToolSetting], settings cascade
Plugin system — manifest, auto-discovery, PluginLoader, conflicts, security model
App extensions — app/App.php, the SporaExtensionInterface hooks
Media assets — AssetStore, MediaEmbed, binary tool outputs
UTF-8 sanitizer — Utf8Sanitizer::scrubString / scrub, write-time sanitisation (core + plugins)

Operations

Deployment modes — server + Mercure, server + polling, client + polling (the three configurations)
Agent loop and async mode — tick() phases, task lifecycle, Mercure SSE
Worker deployment — server-mode cron and daemon patterns, reaping, single-instance lock
Client-worker mode — shared-host browser-driven worker (lives under Deploy; cross-linked here)
Logging — PSR-3, PII policy, what gets logged at which level
Error handling — error envelope, code registry, toast mapping

Frontend

Frontend architecture — Vue 3 + Vite + Tailwind + radix-vue, apps/ module pattern

Contributor standards

Code documentation — comment policy (delete / keep / add)
Testing — Pest, Vitest, SonarQube coverage gate

A note on WIP sections

The plugin system is currently a work-in-progress (see Architecture). The hook methods are declared and surfaced by the manifest, but the explicit PluginLoader → DI container injection path is not yet fully wired up. Three open PRs are landing this; we keep the WIP callout visible on the page so readers know the limitations.