System Architecture#
The system architecture is designed to be entirely client-side, interacting directly with GitHub for content management and being integrated into TeachBooks via a Sphinx extension. It consists of three main components:
Client-Side editor: This is the core component that runs entirely in the user’s web browser. It contains the user interface built with SolidJS, the editor powered by ProseMirror text editing based on a custom MyST schema and a MyST Parser (using MystMD) for converting content between Markdown and the editor’s internal model (see Functional Reuirements).
Sphinx extension: This Python-based component serves as the bridge, enabling the editor to be seamlessly integrated into an existing TeachBook. Its main responsibilities are injecting the editor’s JavaScript and CSS bundles into the HTML pages generated by Sphinx, and adding custom UI elements (such as the “Edit this Page” button) which, when activated, launches the editor (see Sphinx Editor research).
GitHub Repository: The GitHub repository acts as the backend and storage for all TeachBooks content. The editor directly fetches Markdown files from, and writes changes back to, the user’s chosen repository. All version control operations, including branching, committing, and managing pull requests, are handled through GitHub’s established infrastructure. With the editor requesting these actions via the GitHub API on behalf of an authenticated user (see GitHub Integration).