docs

Scope Documentation

Central documentation hub for the Scope platform — an AI coding agent benchmarking system.

Architecture & Design

Document	Description
System Overview	High-level architecture, component interactions, data flow
Architecture Layers	5-layer responsibility model — from cloud foundation to app workloads
Application Design	Data models, API design, judge pipeline, queue patterns, criteria system
Prompt Evaluations	Static prompt quality, user-controlled surface red teaming, datasets, commands, and maintenance
VS Code Web Worker	XState chat machine, GitHub auth flow, ARIA snapshots, AI dev loop
Token Manager	Capability-based token management, validation, round-robin distribution
Authentication & RBAC	Explicit-login IdP authentication, Redis user-access caching, Portal handshake; deferred RBAC roadmap
Worker Requirements	Requirements checklist for coding agent workers
Worker Compliance	Per-worker compliance matrix against requirements
Database Migrations	Lightweight MongoDB migration framework, writing and running migrations
Database Collection Scaling	Per-collection autoscale throughput, ASO reconcile policy, operator runbook
GitOps & Deployment	FluxCD design, kustomization phases, variable substitution

Infrastructure

Document	Description
AKS Node Pool Separation	Taints, tolerations, node selectors for workload isolation
Azure Developer CLI	Provisioning with azd up, feature flags, environment variables

Responsible AI

Document	Description
Responsible AI FAQ	Intended uses, limitations, AI capabilities, risks and mitigations for the OneRAI transparency documentation

Operations

Document	Description
Cosmos DB Backup & Restore	pnpm db:dump / pnpm db:restore rollback tooling, presets, verification, Cosmos caveats

Research

Document	Description
Delta Storage	Approaches for space-efficient storage of coding agent iteration snapshots

Tips & Tricks

Document	Description
Developer Tips & Tricks	Short, practical tips for working productively in this repo (one file per tip)

Decisions

Architecture Decision Records (ADRs) capture significant design choices and their rationale.

Document	Description
ADR Template	Template for new ADRs

---

Where else is documentation?

• Sub-project READMEs — Quick-start and setup guides:
  • scope-mt-app/README.md — Application setup, Docker Compose, features
  • scope-mt-infra/README.md — Azure infrastructure overview
• scope-mt-app/ENV_VARIABLES.md — Environment variable reference for the criteria/judge system
• scope-mt-app/config/ — Domain knowledge encoded as YAML (scenarios, personas, criteria, traits)
• .github/copilot-instructions.md — Development conventions and patterns for AI assistants