Elonn Developer

MD

Review Guidelines

guides/review-guidelines.md

Review Guidelines

Version: 1.0
Project: Elonn
Status: Active

---

Purpose

This document defines the review philosophy and architectural expectations for the Elonn ecosystem.

The goal of code review is not cosmetic perfection.

The goal is to preserve:
- architectural integrity
- system clarity
- maintainability
- operational durability
- long-term extensibility

Reviews exist to prevent entropy.

---

Review Priority Order

Reviewers must prioritize issues in this order:

1. Architectural integrity
2. Correctness
3. Security
4. Maintainability
5. Operational durability
6. Performance characteristics
7. UX/system consistency
8. Style consistency

Style issues must never dominate a review.

---

Core System Philosophy

Elonn is a distributed service ecosystem with multiple runtimes.

The system is designed around:
- clear ownership boundaries
- composable services
- runtime independence
- durable APIs
- long-lived maintainability

Reviews must protect these properties.

---

Architectural Invariants

The following rules are considered system invariants.

Violations require strong justification.

Services Own Canonical Data

Each service owns its own data.

Examples:
- auth owns identity
- time owns calendars/tasks
- maps owns place data
- social owns conversations/social graphs

No service may become a hidden shared database.

---

Runtimes Do Not Own Business Logic

Web, mobile, XR, and future runtimes are consumers.

Runtimes:
- render interfaces
- manage interaction
- adapt input/output

Runtimes must not become canonical business logic owners.

---

World Aggregates But Does Not Own Source Data

World is an aggregation layer.

World may:
- compose
- position
- filter
- present
- spatialize

World must not:
- duplicate canonical datasets
- seed source data
- become a shadow database

---

Authentication Ownership Remains Centralized

Identity ownership remains centralized.

Rules:
- services validate identity through auth APIs
- services do not directly read auth databases
- duplicate auth/session systems are prohibited

---

Explicit Interfaces Over Hidden Coupling

Cross-service behavior must occur through explicit APIs or adapters.

Avoid:
- shared hidden assumptions
- direct DB reads across services
- implicit synchronization
- undocumented dependencies

---

Runtime Independence Must Be Preserved

Core services must remain usable from:
- web
- mobile
- XR
- CLI
- future runtimes

Avoid runtime-specific assumptions in core systems.

---

Review Categories

---

1. Architectural Review

Highest priority review category.

Reviewers must identify:

Questions:
- Does this reinforce or erode the architecture?
- Will this scale structurally?
- Does this create future migration difficulty?
- Is ownership obvious?

---

2. Correctness Review

Reviewers must verify:

Questions:
- Can invalid state occur?
- Is synchronization reliable?
- Are assumptions enforced?
- Is behavior deterministic?

---

3. Security Review

Security issues take precedence over maintainability concerns.

Reviewers must evaluate:

For WordPress-related systems:
- nonce usage
- capability checks
- escaping
- sanitization

---

4. Maintainability Review

Reviewers must optimize for long-term clarity.

Flag:
- ambiguous naming
- giant files/functions
- speculative abstractions
- duplicated logic
- inconsistent patterns
- hidden side effects
- excessive indirection
- unclear ownership

Questions:
- Will this still make sense in two years?
- Is behavior obvious?
- Is complexity localized?
- Is naming precise?

---

5. Operational Review

Reviewers must evaluate operational durability.

Review:
- deployment assumptions
- shared hosting compatibility
- migration safety
- backward compatibility
- logging
- monitoring hooks
- failure handling
- retry behavior
- memory usage
- resource cleanup
- dependency management

Questions:
- Will this fail safely?
- Is rollback possible?
- Does this assume unavailable infrastructure?
- Will this behave correctly under resource pressure?

---

6. Performance Review

Performance review should focus on system behavior, not micro-optimization.

Reviewers should identify:
- N+1 queries
- duplicated requests
- excessive rendering
- unnecessary rerenders
- blocking operations
- memory churn
- oversized payloads
- excessive DOM complexity
- unstable lifecycle behavior

Avoid premature optimization.

Prefer clarity until measurable bottlenecks exist.

---

7. UX/System Consistency Review

Reviewers should preserve coherent system behavior.

Evaluate:
- terminology consistency
- navigation consistency
- deterministic behavior
- interaction predictability
- persistence expectations
- layout/system coherence

Examples:
- conversations/events terminology
- carry vs field behavior
- stable embedded browser behavior
- deterministic social ordering

---

8. Mobile/XR/Spatial Runtime Review

Elonn is designed for future spatial runtimes.

Reviewers must avoid assumptions that block:
- mobile runtimes
- XR runtimes
- sensor-driven environments
- spatial interfaces

Evaluate:
- lifecycle stability
- WebView stability
- sensor coupling
- memory pressure
- rendering assumptions
- input abstraction quality

Questions:
- Does this depend on desktop assumptions?
- Will this survive constrained hardware?
- Is input abstraction preserved?

---

Prohibited Patterns

The following patterns are strongly discouraged or prohibited.

Cross-Service Database Access

Services must not directly query another service's database.

Use APIs.

---

Hidden Global State

Avoid:
- implicit mutable globals
- hidden singleton coupling
- invisible shared caches

State ownership must remain explicit.

---

Business Logic Inside Templates

Templates should present data.

Business logic belongs in services/controllers/domain layers.

---

Runtime-Specific Core Logic

Avoid embedding:
- browser assumptions
- Android assumptions
- XR assumptions

inside core services.

---

Duplicate Authentication Systems

Do not:
- recreate auth flows
- duplicate session logic
- fork identity handling

Identity remains centralized.

---

Speculative Abstractions

Avoid abstractions created for hypothetical future needs.

Prefer:
- simple structures
- clear ownership
- incremental evolution

---

Hardcoded Environment Assumptions

Avoid assumptions about:
- Composer availability
- VPS access
- GPU access
- filesystem layout
- memory availability
- network stability

---

CSS Leakage

Avoid:
- global style leakage
- unscoped styles
- runtime-wide overrides

Prefer isolated, reusable systems.

---

Naming Standards

Names must:
- reflect ownership
- reflect responsibility
- remain unambiguous
- scale with system growth

Avoid:
- generic names
- overloaded terminology
- runtime-dependent naming

Reviewers should flag unclear naming early.

Naming debt compounds rapidly.

---

Review Output Expectations

Reviews should:

Reviews should not:
- devolve into formatting debates
- prioritize lint over architecture
- recommend unnecessary abstractions
- impose framework dogma

---

Severity Levels

Critical

Must be fixed before merge.

Examples:
- security vulnerabilities
- architectural boundary violations
- canonical ownership violations
- data corruption risks

---

Major

Should be fixed soon.

Examples:
- maintainability risks
- hidden coupling
- operational fragility
- scaling risks

---

Minor

Improvement opportunities.

Examples:
- naming refinement
- code organization cleanup
- simplification opportunities

---

Review Philosophy

Code quality is not measured by cleverness.

Prefer:
- clarity
- durability
- explicit ownership
- predictable behavior
- operational realism

The system should age well.

Reviews exist to preserve that outcome.