Architecture Review Checklist

Purpose: Establish objective criteria for code reviews.
Mandatory For: All Plugin PRs and Core Refactors.

1. Constitution Compliance (PASS / FAIL)

Every PR must satisfy these binary checks. If ANY check fails, the PR cannot be merged.

C-1. Optionality

  • [ ] Is the core usable without this change?

  • [ ] Does import structum.core work if this plugin is missing?

  • [ ] Are dependencies declared as extra (optional)?

C-2. Explicitness

  • [ ] Are side-effects strictly opt-in?

  • [ ] Does import structum.[plugin] avoid running layout detection/initialization?

  • [ ] Are implicit defaults documented and overridable?

C-3. Boundaries

  • [ ] Are implementation details leaking?

  • [ ] Are internal objects (e.g., sqlalchemy.Session) wrapped or exposed via Protocol?

  • [ ] Is the plugin interacting only via public interfaces of other plugins?

C-6. Fail-Fast

  • [ ] Does it crash early?

  • [ ] Are invalid configurations caught at initialization time (startup)?

  • [ ] Are error messages actionable (what failed + how to fix)?

2. Design & API

  • [ ] Naming: Do exported symbols follow structum.[naming_convention]?

  • [ ] Typing: Is mypy --strict passing without type: ignore?

  • [ ] Async: If I/O bound, is there an async equivalent?

  • [ ] Context: Is context (e.g., Request ID) propagated correctly?

3. Resilience & Quality

  • [ ] Continuity: Does the system behave correctly (fallback) if the backing service is down?

  • [ ] Performance: Are expensive operations lazy-loaded?

  • [ ] Testing: Are there tests for the “happy path” AND “missing dependency” path?

4. Documentation

  • [ ] README: Does it use the Standard Plugin Template?

  • [ ] Compliance: Is the “Constitution Compliance” table filled out?

  • [ ] Examples: strictly copy-pasteable runnable code?