<!--
SYNC IMPACT REPORT
==================
Version change: (unset) → 1.0.0
New file: first ratification, all placeholders filled.

Modified principles: N/A (initial ratification)

Added sections:
  - Core Principles (5 principles)
  - Technology Constraints
  - Development Workflow
  - Governance

Templates reviewed:
  - .specify/templates/plan-template.md        ✅ compatible (no amendments needed)
  - .specify/templates/spec-template.md        ✅ compatible (no amendments needed)
  - .specify/templates/tasks-template.md       ✅ compatible (no amendments needed)

Deferred TODOs:
  - TODO(RATIFICATION_DATE): exact project start date unknown; using today (2026-03-31) as ratification date.
-->

# AI Teacher Constitution

## Core Principles

### I. Keep It Simple Stupid (KISS)

Every design and implementation decision MUST default to the simplest viable option.
Complexity MUST be explicitly justified against a concrete, present need — not a hypothetical
future requirement. Gold-plating, speculative abstractions, and premature optimization are
non-compliant.

**Rules:**
- A feature MUST NOT be split into multiple layers/services unless a single layer is demonstrably insufficient.
- Dependencies MUST be chosen for their simplicity, not their feature count.
- If two approaches solve the problem equally well, the shorter one wins.

**Rationale**: This is a POC. Speed of learning and iteration matters more than architectural
elegance. Complexity kills POCs.

### II. Easy to Change

Code MUST be written with future modification in mind. High coupling between unrelated modules
is non-compliant.

**Rules:**
- Modules MUST communicate through clearly defined interfaces; internal implementation details
  MUST NOT leak across boundaries.
- Hardcoded values MUST be extracted to configuration at the boundary where they are consumed.
- A feature's core logic MUST be separable from its delivery mechanism (HTTP handler, CLI, etc.)
  without full rewrites.

**Rationale**: A POC that cannot pivot cheaply is a dead end. Changeability is the primary
competitive advantage of early-stage software.

### III. Web-First Architecture

The project is a web application. All architectural decisions MUST assume an HTTP
request/response model as the primary interface.

**Rules:**
- The backend MUST expose a REST (or equivalent HTTP) API as its public contract.
- The frontend MUST be a standalone client that communicates solely through the API;
  server-side rendering of business logic is non-compliant.
- API contracts MUST be versioned at the URL path level (`/api/v1/...`) from day one.

**Rationale**: Maintaining a clean client/server split allows each side to evolve independently,
which is critical for a project that is expected to change frequently.

### IV. Documentation as Architecture

The README.md MUST contain a living architecture overview using Mermaid diagrams. Diagrams MUST
be updated whenever the architecture changes; outdated diagrams are a compliance violation.

**Rules:**
- At minimum, a system-context diagram (components and their relationships) MUST exist in README.md.
- Each major subsystem added to the project MUST be reflected in the README diagram within the
  same PR that introduces it.
- Diagrams MUST use the `mermaid` fenced code block syntax so they render natively on GitHub/GitLab.

**Rationale**: For a POC with a small team, the README is the primary onboarding document.
Keeping diagrams co-located with code prevents documentation rot.


## Technology Constraints

- **Project type**: Web application (backend API + frontend client).
- **Structure**: `backend/` and `frontend/` at repository root (Option 2 in plan template).
- **Complexity ceiling**: Maximum two deployable units (one backend, one frontend) unless
  a concrete scaling need is demonstrated and documented.
- **External services**: MUST be wrapped behind an interface so they can be swapped without
  cascading changes.
- **Database**: A single relational or document store is sufficient for the POC; no distributed
  storage without explicit justification.

## Development Workflow

- Branch strategy: feature branches off `main`; short-lived (merge within one week).
- PR size: SHOULD be small enough to review in under 30 minutes; large PRs MUST be split.
- README MUST be updated in the same PR as any architectural change (Principle IV).
- The `Complexity Tracking` table in the plan template MUST be filled whenever a Principle I
  or II violation is introduced.
- No performance optimization pass before the first working end-to-end prototype is validated
  (Principle V gate).

## Governance

This constitution supersedes all informal conventions. Amendments MUST be proposed as a PR
that updates this file with an incremented version number and updated `LAST_AMENDED_DATE`.

**Amendment procedure:**
1. Open a PR with the proposed changes to this file.
2. The PR description MUST state which principle is affected and why the change is needed.
3. Merge after at least one reviewer approves.
4. All open feature branches MUST be rebased onto the updated `main` within 48 hours of merge.

**Versioning policy (semantic):**
- MAJOR: Removal or redefinition of an existing principle.
- MINOR: Addition of a new principle or section.
- PATCH: Clarifications, wording, or typo fixes.

**Compliance review**: Every PR review MUST include a check against the Constitution Check
section in the plan template. Non-compliant complexity MUST be logged in the Complexity
Tracking table before merge.

**Version**: 1.0.0 | **Ratified**: 2026-03-31 | **Last Amended**: 2026-03-31