NACODEX

This document is not final. It is current.

NACODEX is updated whenever an architectural discovery warrants it. Every rule reflects the best understanding at the time of its integration. A later update may refine a rule’s domain, add conditions to its application, or define its boundary with another rule. This is expected and correct behaviour — not a sign that the earlier rule was wrong.

Every software project that grows feature by feature eventually encounters the same failure mode: divergent duplication. A function is written in Class A. Later, Class B needs it and copies it with slight adaptations. Two independent copies now exist, maintained independently. A bug fixed in one is not fixed in the other — because the other is not remembered.

This is not a failure of discipline. It is a structural failure. The codebase has no mechanism to prevent duplication and no mechanism to enforce that a fix propagates. The framework in this document solves this structurally by ensuring every function, constant, and piece of logic has exactly one home.

Empirical observations derived from observation rather than theory. The rules that follow are grounded in these premises.

Behavioral rules that all code following this framework obeys. A violation is a defect, not a style difference.

Every function belongs to exactly one of five categories. The test for each is applied in order; the first that fits is correct.

Every class belongs to exactly one layer. Dependencies only flow downward. A violation is always a design error, always fixable by introducing a callback interface or splitting the violating class.

InstantCompactValueUpdate (ICVU) — a write pattern for values that must remain consistent across multiple storage media at all times. Instant: the update happens synchronously. Compact: both media are updated in a single method call. The caller has no knowledge of the two-medium write.

Apply when ALL are true: (1) the value is written by more than one component; (2) read by more than one component; (3) an incorrect read causes a user-visible failure; (4) the failure may occur silently without any error or warning.

// Atomic setter — the only location where both writes occur
private void setValue(float x, float y) {
    fieldX = x; fieldY = y;          // 1. update in-memory
    storage.save(this, x, y);        // 2. update persistent storage
    updateDisplay();                 // 3. optional: refresh derived display
}

// Sync-from-storage — called at component resume points
private void syncFromStorage() {
    fieldX = storage.getX(this, fieldX);
    fieldY = storage.getY(this, fieldY);
    updateDisplay();
}

Domain boundary (Update 2): ICVU governs application-layer value consistency only. Window dimensions live in the compositor domain and are governed by AX12 instead.

The problem: An overlay window whose content changes size at runtime produces a diagonal positional artifact on every resize call, equal to the size delta per axis. The artifact is in the system compositor — not in application code. No application-layer fix can prevent a compositor-layer timing artifact.

The rule: Size the window once at addView() to the maximum content it will ever display. Only x and y change through updateViewLayout(). Content size changes via invalidate() only.

// Attach — size ONCE at maximum content dimensions
int fixedSize = maxContentSize;
if (fixedSize % 2 == 0) fixedSize += 1;  // force odd → half-integer center

params = buildParams(centerX, centerY, fixedSize);
windowManager.addView(view, params);      // surface allocated once

// Content size change (slider, animation, theme)
content.update(newSize, newRadius);       // sets fields, calls invalidate()
// NO updateViewLayout — surface NOT reallocated

// Position change only
params.x = (int)(targetCenterX - fixedSize / 2f);
params.y = (int)(targetCenterY - fixedSize / 2f);
windowManager.updateViewLayout(view, params);

The test gap indicator: If a function cannot be tested without instantiating a Category E class, the function is in the wrong place. Extract it to a lower layer.

An architectural rule, when applied to a domain for which it was not designed, may produce correct behaviour in the domain it governs and incorrect behaviour in the adjacent domain it does not govern. The evidence of this situation is: following the rule correctly makes something worse.

When this occurs, the correct response is: (1) do not abandon the rule; (2) define the domain boundary of the rule explicitly; (3) identify the adjacent domain and find or create the governing rule for it; (4) document both the rule and its boundary in the Codex.

This Codex has now accumulated two updates. The ICVU rule (Update 1) was correct and applied broadly. Applied to overlay window dimensions, it produced correct values but worsened visual behaviour through increased compositor write frequency. Update 2 defines the domain boundary of ICVU and adds AX12 to govern the compositor domain. Both rules — ICVU and the Fixed Surface Rule — are now in the Codex with their domains defined. Neither one alone is sufficient. Both are correct.

The rules in this document were not designed in advance. They were extracted from working software after observing what broke and why. What good architecture actually requires is systematic observation and extraction. The developer who watches which functions get copied, which constants get misspelled, which interface boundaries collapse under load — and then responds by extracting, formalising, and enforcing — will produce better architecture than the developer who designs the perfect system in advance and struggles to fit reality into it.

Theory produces elegant architecture. Practice produces correct architecture. The gap between them is smaller than it appears, but it only closes through observation — not through reasoning alone.

Is it a pure computation with no state?
  → Category A. Lives in the foundation utilities file.

Is it a group of related fields that travel together?
  → Category B. Lives in a dedicated data container class with a Builder.

Does it own a resource lifecycle, needed by multiple consumers?
  → Category C. Lives in a dedicated manager class.

Does it wrap a platform API to hide its complexity?
  → Category D. Lives in a dedicated bridge class.

Does it respond to user input or own a visible surface?
  → Category E. Lives in an activity, fragment, or service.

Does it identify a persistent value or inter-component message?
  → It is a constant. Lives in the constants file. Always.

Is it a value written by more than one component?
  → It is an ICVU value. It gets an atomic setter and sync-from-storage method.
    [Added in Update 1]

Does this code call updateViewLayout() with new width or height while visible?
  → It violates AX12. Size the window at addView() time to the maximum content
    size. Only pass position changes to updateViewLayout() after that.
    [Added in Update 2]

A function appears in more than one class?
  → Violation of AX1. Extract to the appropriate category.

A manager imports a concrete consumer class?
  → Violation of AX2. Introduce a callback interface.

A string literal identifies a key or action in more than one file?
  → Violation of AX3. Declare in constants file and reference by name.

A consumer builds its own inter-component message inline?
  → Violation of AX4. Add a method to the appropriate sender class.

A value is written in one place without updating persistent storage?
  → ICVU anti-pattern 1. The value requires an atomic setter. [Update 1]

A value is written to storage without updating the in-memory field?
  → ICVU anti-pattern 2. The value requires an atomic setter. [Update 1]

updateViewLayout() is called with new width or height while visible?
  → Violation of AX12. Resize only at addView(). Use invalidate()
    for content changes. [Update 2]

Two overlay windows kept in sync through sequential updateViewLayout calls?
  → Dead End DE24. Merge into a single window. [Update 2]