docs(architecture): say who decides what is open source, and why a feature's switch never touches its schema

[peteski22]

Description

Two additions to ARCHITECTURE.md. Neither changes any code or any behavior. Both write down something the document already assumed.

1. Who decides whether a feature is part of the open-source product. "Where new code goes" picks a home by what is being added, and every row of it assumes someone has already classified the thing: "an optional feature any deployment may run" goes to core, "only an overlay ships" goes to an overlay. Nothing said who makes that call, so the table could be read as making it. The new paragraph says the classification comes first, that it belongs to the project's product and engineering leads together, and that a feature not yet confirmed starts in an overlay. The reason for that default is that the move only works one way: a feature proven in an overlay can move here later, and a feature released here can never be withdrawn.

2. Why a feature's switch never touches its schema. Step 3 of "How to add a core feature" states the rule (switching a feature off leaves its tables in place, switching it on changes no schema) with no reasoning, so it reads as arbitrary and open to renegotiation. The new subsection gives the four reasons, each checked against the code as it is on main:

• Migrations run in-process at startup with no lock around them (_run_migrations in core/database.py), so a switch that created tables would have every replica run the same DDL at once.
• With one chain and one head, alembic_version is a function of the release. With a branch per feature it depends on the order switches were flipped.
• alembic/env.py refuses a database stamped with any revision the image does not know, so a feature switched on once would expose every later rollback.
• One chain means the suite tests the schema every deployment has. N independent features means 2^N schemas in the field.

The rule this adds, per the checklist: a feature's place in the open-source product is confirmed by the project's product and engineering leads before "Where new code goes" applies. The schema rule is not new. It has been in step 3 since #1279 and in #1173's acceptance criteria; this PR adds only its reasoning.

How to test it locally

Documentation only. make lint passes. The new in-page link from step 3 resolves to the new subsection's heading, and the existing links into this section from CONTRIBUTING.md and src/gateway/AGENTS.md still resolve, because the heading they target is unchanged.

Worth reading rather than running: the four claims in the new subsection, against src/gateway/core/database.py and alembic/env.py.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Relevant issues

Refs #1173, where the schema rule was set, and #1363, which proposes changing it and is the reason to put the reasoning on the record.

Checklist

• I understand the code I am submitting.
• I have added or updated tests that cover my change (tests/unit, tests/integration).
• I ran the Definition of Done checks locally (make lint, make typecheck, make test).
• Documentation was updated where necessary.
• If the API contract changed, I regenerated the OpenAPI spec (uv run python scripts/generate_openapi.py).
• If this changes a rule in ARCHITECTURE.md or scripts/check_architecture.py, the description names the rule and says why.

AI Usage

• No AI was used.
• AI was used for drafting/refactoring.
• This is fully AI-generated.

AI Model/Tool used:

Claude, via Claude Code.

Any additional AI details you'd like to share:

The wording is AI-written. The decisions in it are not: who decides, and the overlay-first default, were settled by a person before anything was drafted. Each technical claim was checked against main first, and one sentence in the draft was corrected as a result (the gateway does not inspect the schema when auto_migrate is off, so it would not refuse to start on its own).

• I am an AI Agent filling out this form (check box if true)

Summary

• Updated ARCHITECTURE.md with guidance on deciding whether features belong in the open-source product.
• Clarified that unconfirmed features should start in an overlay.
• Documented why feature switches must remain independent from database schemas.
• No code or behavior changes.

Validation

• make lint passes.
• Relevant documentation links resolve.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

Configuration used: Repository: mozilla-ai/otari/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 4961e043-1d78-44a9-98ef-14a1a7d4c4b8

📥 Commits

Reviewing files that changed from the base of the PR and between 298c00b and 444cc54.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: fec3bb1f-d06e-465c-9a54-491091e05c91

📥 Commits

Reviewing files that changed from the base of the PR and between b330b37 and 298c00b.

📒 Files selected for processing (1)

• ARCHITECTURE.md

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

Walkthrough

Changes

Architecture guidance

Layer / File(s)	Summary
Feature placement guidance ARCHITECTURE.md	Documents that product and engineering leads confirm whether a feature belongs in the open-source product. Unconfirmed features remain in an overlay and may later move to core.
Schema and switch boundary ARCHITECTURE.md	Explains why feature switches remain configuration and do not change database schemas, including migration, rollback, and test coverage constraints.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Suggested reviewers: njbrake

Merge Risk: ⚪ Minimal · up to 298c0

This documentation-only update does not alter runtime behavior or database schemas and is ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title describes the documentation change and uses an allowed Conventional Commit type, but it uses a scope instead of the required exact prefix format, exceeds the approximately 70-character limit…	Use a title that starts with an exact allowed prefix and stays under approximately 70 characters, such as "docs: document feature ownership and schema-switch rationale".

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is complete and relevant. It explains both documentation changes, gives testing information, identifies the documentation PR type, references related issues, completes the checklist, a…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title describes the documentation change and uses an allowed Conventional Commit type, but it uses a scope instead of the required exact prefix format, exceeds the approximately 70-character limit at 108 characters, and should be shortened.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

✨ Simplify code

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}