ĀYŌDÈ Request For Comments (ARFC) Index

This directory contains technical proposals for the ĀYŌDÈ platform and Codermerlin Academy API.

What an ARFC Specifies

An ARFC describes a design at the functional and conceptual level, from the perspective of the people who use the platform — instructors, administrators, students, and the developers who integrate against the API. It states what becomes possible, what the rules are, and why the design is shaped the way it is.

An ARFC is not an implementation plan. Storage layout, internal code structure, and delivery mechanics are settled during implementation and recorded in GitHub issues, not here. A reader should be able to evaluate an ARFC without knowing how the platform is built.

Belongs in an ARFC

• The capabilities the design introduces, and who may exercise them
• The concepts it defines, and how they relate to one another
• Rules and invariants stated as behavior — “a plan is complete when every required objective is placed”
• States a user can observe, and what moves something between them
• What an institution may configure, and who is permitted to configure it
• The reasoning behind each choice, and what it protects against
• Version 1 scope: what is included, and what is deliberately excluded
• Effects on existing behavior that a current user or integrator would notice

Does not belong in an ARFC

• Database table and column definitions, keys, or indexes
• SQL of any kind, including DDL
• Stored-procedure names or signatures
• Source file paths, package structure, or internal code layering
• Storage formats, serialization shapes, caching or connection mechanics
• Migration steps and deployment sequencing

Matching detail to subject

Detail should follow what the ARFC actually proposes. Most ARFCs propose capabilities, and five of the nine published to date contain no table or procedure detail at all. ARFC-1007 is the reference example: a substantial feature specified entirely through core principles, primary objects, lifecycles, content rules, an authorization model, and an explicit included/excluded scope list.

ARFC-1004 is the exception, and legitimately so — its subject is a schema, as its title says, so structural detail is the proposal rather than an implementation leak. The rule is therefore not “never describe structure,” but “describe the thing you are proposing, at the altitude your readers can evaluate.” An ARFC proposing a capability should not read like an ARFC proposing a schema.

Where implementation detail goes instead

GitHub issues in codermerlin.academy-backend carry the implementation specification — table and column changes, procedure contracts, arithmetic, and sequencing. An ARFC establishes what is being built and why; the issues derived from it establish how.

Implementation Status Definitions

• Implemented: The backend repository contains an implementation that matches the ARFC’s core design.
• Implemented with modifications: The backend repository contains an implementation of the ARFC’s intent, but with material design or endpoint changes.
• Abandoned: The backend repository does not contain a matching implementation, and the proposal appears to have been superseded or not pursued.
• Draft: Proposal under initial review and not yet evaluated as implemented, implemented with modifications, or abandoned.

Active ARFCs

Implemented ARFCs

Abandoned ARFCs

Contributing

To propose a new ARFC:

1. Check the altitude first: read What an ARFC Specifies before drafting. Getting the level of detail wrong is the most common and most expensive revision.
2. Create a new file: ARFC-{number}.md with the next sequential number
3. Follow a comparable ARFC: use ARFC-1007 as the structural reference when proposing a capability, and ARFC-1004 when the proposal itself is a schema
4. Include required sections:
   • Status (Proposed/Draft)
   • Abstract
   • Motivation
   • Specification
   • Security Considerations
   • Backward Compatibility
   • References
5. State Version 1 scope explicitly: list what is included and what is deliberately excluded, so reviewers can judge the boundary rather than infer it
6. Submit for review: Create a pull request with your proposal
7. Update this index: Add your ARFC to the table above

ARFC Lifecycle

Draft (0-14 days)
    ↓
Last Call (14-21 days)
    ↓
Published (approved)
    ↓
Implemented (deployed)

Last Updated: 2026-09-07