# Polymath — Architecture & Product Design Documentation

> **Polymath** (working title) is a free, community-owned, open-source platform for
> learning math, computer science, physics, and logic through interactive,
> community-authored problems and courses. Platform code is licensed under
> **AGPLv3**; all educational content contributed to the platform is licensed
> under **CC BY-SA 4.0**.

This `docs/` directory is the canonical technical design package for the project.
It is the deliverable of **Milestone 1: Architecture & Product Design Document**
and is intended to live at the root of the open-source monorepo. Every later
implementation milestone must trace back to a section or ADR here; substantive
design changes require a new or superseding ADR.

## Reading order

If you are new to the project, read in this order:

1. [`architecture/01-system-overview.md`](architecture/01-system-overview.md) — components, request flows, deployment topology.
2. [`architecture/02-data-model.md`](architecture/02-data-model.md) — entity-relationship model for every persistent entity.
3. [`architecture/03-content-format.md`](architecture/03-content-format.md) — the MDX/JSON content storage format for problems, hints, solutions, widgets, and courses.
4. [`architecture/04-versioning-and-forking.md`](architecture/04-versioning-and-forking.md) — immutable versions, changelogs, rollback, forks, and attribution.
5. [`architecture/05-rbac-permissions.md`](architecture/05-rbac-permissions.md) — the five roles and the full permission matrix.
6. [`architecture/06-review-workflow.md`](architecture/06-review-workflow.md) — the contribution state machine: draft → submitted → review → published.
7. [`architecture/07-widget-sandboxing.md`](architecture/07-widget-sandboxing.md) — the security model isolating untrusted interactive widgets and code execution.
8. [`architecture/08-audit-log.md`](architecture/08-audit-log.md) — tamper-evident audit logging design.
9. [`architecture/09-accessibility-i18n-bandwidth.md`](architecture/09-accessibility-i18n-bandwidth.md) — accessibility, internationalization, and low-bandwidth strategy.
10. [`architecture/10-api-design.md`](architecture/10-api-design.md) — public REST API conventions and surface.

## JSON Schemas

Machine-readable JSON Schema (draft 2020-12) definitions for all content
documents live in [`schemas/`](schemas/):

| Schema | Describes |
|---|---|
| `schemas/problem.schema.json` | A `ProblemVersion` content document |
| `schemas/answer-spec.schema.json` | Per-type answer specifications (shared `$defs`) |
| `schemas/course.schema.json` | A `CourseVersion` content document (modules, lessons, problem sets) |
| `schemas/widget-manifest.schema.json` | The manifest a sandboxed widget package must ship |
| `schemas/oer-export.schema.json` | The portable Open Educational Resource export envelope |

## Architecture Decision Records

ADRs live in [`adr/`](adr/) and follow the lightweight
[MADR](https://adr.github.io/madr/) format. Index: [`adr/README.md`](adr/README.md).
ADRs are **immutable once accepted**; to change a decision, write a new ADR
that supersedes the old one.

## Glossary

| Term | Meaning |
|---|---|
| **Content item** | A `Problem` or `Course` — the stable identity object that versions hang off |
| **Version** | An immutable snapshot of a content item's document (`ProblemVersion` / `CourseVersion`) |
| **Head** | The latest version on a content item's draft line |
| **Published version** | The single reviewed version currently served to learners |
| **Fork** | A new content item whose first version is copied from another item's version, with attribution preserved |
| **Widget** | An untrusted, community-authored interactive component executed in a sandboxed iframe origin |
| **Trusted component** | A first-party MDX component (KaTeX, plots, diagrams) shipped with the platform and rendered in the main origin |
| **AnswerSpec** | The structured, machine-checkable definition of a problem's correct answer(s) |
| **OER bundle** | A self-contained, versioned export of a course and its dependencies under CC BY-SA |

## Non-goals for the MVP

To keep scope honest, the following are explicitly **out of scope** for the MVP
(but the architecture leaves room for them):

- Real-time multiplayer/collaborative solving.
- Mobile native apps (the web app is responsive and installable as a PWA).
- Paid features, subscriptions, or any monetization machinery.
- ML-trained recommendation models (MVP uses transparent heuristic recommendations; see §9 of the system overview).
- Federation between Polymath instances (the OER export format is designed so this can come later).