The official repository for the toolAssisted.run web platform.
An open, community-driven archive dedicated to preserving tool-assisted speedruns, score attacks, and superplays.
Important
Archival comes first; curation emerges from the community afterwards.
Every verifiable work is preserved the moment it arrives, and merit is decided in the open by the people who care about it. The community constitution outranks every implementation choice: when code and constitution disagree, the code is wrong.
This repository powers toolAssisted.run. The platform is divided into two programs sharing one single source of truth:
- The Static Site Generator (
generator/): A fast Python and Jinja2 generator that ingests facts from the archive repository, computes derivations (rankings, points, verification states), and renders the static site published to GitHub Pages. - The Archivist Service (
archivist/): A lightweight Flask application running on the community server. It manages intake, member authentication via forum SSO, reviews, and git-backed updates with public audit logging.
flowchart LR
Archive[("ToolAssisted-run/archive<br/>Raw facts: runs, games, roles")]
Generator["Static Generator<br/>(Python + Jinja2)"]
Archivist["Archivist Service<br/>(Flask JSON API)"]
Pages["GitHub Pages<br/>toolassisted.run"]
Browser(("Browser Client<br/>app.js + ES Modules"))
Archive -->|reads facts| Generator
Generator -->|emits static site| Pages
Pages -->|serves assets| Browser
Browser <-->|authenticated actions| Archivist
Archivist -->|logged commits| Archive
Note
Design Record: DESIGN.md is the canonical living snapshot of the site's rationale and decisions. It is continuously maintained to describe the present state rather than serving as a changelog. For code structure, consult ARCHITECTURE.md.
| Path | Component | Description |
|---|---|---|
generator/ |
Model & Generator | Reads archive facts, computes derivations (rankings, states), and compiles Jinja2 templates into static HTML. |
archivist/ |
Archivist Service | Flask API backend handling authentication, submission intakes, expert edits, and git-backed logs. |
assets/ |
Frontend Runtime | Modular ES scripts (app.js, page-*.js) and stylesheets (style.css). Shipped directly with zero bundler friction. |
tests/ |
Hermetic Test Suites | Rigorous test suites covering movie parsers, generator invariants, security policies, and layout fidelity. |
infra/ |
Infrastructure | Discourse forum themes, server configurations, and operational scripts. |
tools/ |
Utilities | Automation and diagnostic tools (zap, validation helpers, benchmarks). |
serve_local.py |
Dev Server | Local development server with live reload, archive discovery, and archivist API mocks. |
- Zero Server-Side Emulation: Emulation is never executed server-side. Encodes and movie files are preserved, verified, and reproduced through transparent community workflows.
- Decoupled Architecture: Frontend and backend communicate only through static JSON blobs embedded on pages and authenticated REST calls to the archivist API.
- Auditability and Integrity: Member content is modified only by responsible experts inside their jurisdiction, with every change logged in
edits.jsonand traceable in git history. - Universal Verification: One verification from any community member marks a run as verified; an expert can invalidate a flawed verification if needed.
- Privacy and Independence: No third-party analytics, tracking scripts, or ad networks.
Local Development Server
- Python 3.10 or newer
- Git checkout of
ToolAssisted-run/archive(placed in~/ToolAssisted-archiveor next to this repository) - Node.js (for running frontend tests and formatting via Biome)
Run the integrated development server (starts in logged-out mode by default):
python serve_local.pyCommand-line flags can be combined freely depending on what you are testing:
# Example: rebuild site, point to local archive, and log in as site-wide expert GMP
python serve_local.py --rebuild --archive ../ToolAssisted-archive --user GMP
# Example: start logged in as a specific user on a custom port and launch the browser
python serve_local.py --user eien86 --port 8080 --open| Flag | Description |
|---|---|
-u, --user <name> |
Explicitly log in as a member (e.g. --user eien86 or --user GMP) |
-b, --rebuild |
Rebuild static HTML from archive data before serving |
-a, --archive <path> |
Path to archive checkout (default: auto-detected in parent or home folder) |
-p, --port <port> |
Port to listen on (default: 8000) |
-o, --open |
Open site in default browser on launch |
--logged-out |
Explicitly enforce logged-out mode (already default) |
[!TIP]
serve_local.pyincludes a built-in mock archivist API, so you can test expert tools, category creation, and run inspection locally without requiring remote server access.
Running Hermetic Tests
All tests are hermetic: they run against temporary synthetic fixtures, mock all external services, and never touch real archive data.
# Movie file parser tests
python tests/test_movieparse.py
# Derivation and ranking parity tests
python tests/test_derivation.py
# Markup preview and wikitext tests
python tests/test_preview_parity.py
python tests/test_wikitext.py
# Output invariant tests (requires archive checkout or fixture)
python tests/test_output.py ../ToolAssisted-archive
# Archivist service end-to-end suite
python tests/test_archivist.pyDeployment Process
- Continuous Deployment: Pushes to the
mainbranch trigger the Build and deploy workflow, which validates tests, generates static pages, and deploys to GitHub Pages. - Content Synchronization: When new runs or edits land in the archive repository, a workflow dispatch initiates a site rebuild so the live site always matches the archive.
- Website: toolassisted.run
- Forum: forum.toolassisted.run
- Constitution: Governance & Principles
- Archive: ToolAssisted-run/archive
- Discord: Join the Discord Community
- Code: Licensed under the MIT License.
- Archive Content: Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0) (see the archive repository).