Century Architecture Patterns

Century Architecture Patterns

Building systems designed to operate without code changes for 100+ years. Not a metaphor — concrete architectural patterns that survive technology churn, schema evolution, platform migration, and developer turnover.

When to Use

• Designing systems that must outlive their original framework
• Building tool platforms intended for external contribution
• Creating stateful systems where data longevity matters
• Architecting agent tool systems meant for multi-framework consumption
• Any system where the cost of migration exceeds the cost of foresight

Core Principles

1. Zero Hardcoded Values

Every configurable value loads from external config files — never embedded in code. New plugins, ecosystems, or patterns = new config file, not new code.

# ❌ Brittle: hardcoded patterns
ECOSYSTEMS = {"kubernetes": {"patterns": ["pod", "deployment"]}}

# ✅ 100-year: loaded from config/ JSON files
config_dir = os.path.join(APP_DIR, 'config')
for fname in os.listdir(config_dir):
    if fname.endswith('.json'):
        ecosystems[fname.replace('.json','')] = json.load(open(os.path.join(config_dir, fname)))

Why: In year 47 when quantum kubernetes replaces container kubernetes, adding a new config file requires zero code changes.

2. Schema Versioning

Every state file carries a schema_version field. On load, auto-migrate from any older version. Unknown fields preserved — never dropped.

STATE_SCHEMA = {"schema_version": "2.0.0", "created_at": None}

def load_state(path):
    try:
        data = json.load(open(path))
        v = data.get("schema_version", "1.0.0")
        if v != CURRENT_VERSION:
            data = migrate(data, v, CURRENT_VERSION)
        # Forward compat: preserve unknown keys
        for k, default in STATE_SCHEMA.items():
            data.setdefault(k, default)
        return data
    except (json.JSONDecodeError, FileNotFoundError):
        return repair_from_backup(path)

def migrate(data, from_v, to_v):
    chain = {
        "1.0.0": lambda d: {**d, "schema_version": "2.0.0", "errors_recovered": 0},
        "2.0.0": lambda d: {**d, "schema_version": "3.0.0", "tools_used": {}},
    }
    cursor = from_v
    while cursor in chain:
        data = chain[cursor](data)
        cursor = data.get("schema_version", cursor)
    return data

Why: In year 23 when someone upgrades the schema format, all existing state files automatically migrate. Old data is never lost — every migration is a function in the chain.

3. Self-Healing State

Detect corruption, repair from backup, or recreate from defaults automatically. Never crash with a corrupt state file — always heal.

def load_or_repair(path):
    if not os.path.exists(path):
        return create_fresh_state()
    try:
        return json.load(open(path))
    except (json.JSONDecodeError, KeyError):
        backup = path + ".bak"
        if os.path.exists(backup):
            try: return json.load(open(backup))
            except: pass
        return create_fresh_state()

Why: In year 14 when a cosmic ray flips a bit in the state file, the system doesn't die — it heals and logs the event.

4. Atomic Writes

Write to .tmp, then os.replace() — never half-written state, even on power failure.

def save_state(path, data):
    tmp = path + ".tmp"
    with open(tmp, 'w') as f:
        json.dump(data, f)
    if os.path.exists(path):
        shutil.copy2(path, path + ".bak")  # Keep previous backup
    os.replace(tmp, path)  # Atomic on same filesystem

Why: In year 62 when the datacenter loses power mid-write, the state file is either the complete previous version or the complete new version — never a corrupted partial write.

5. Plugin-Based Architecture

New capabilities come as plugins (config files, scripts, modules) — not code changes to the core.

plugin-based-ecosystem/
├── core/              # Never changes
├── plugins/
│   ├── ecosystem-a/   # Added in year 3
│   ├── ecosystem-b/   # Added in year 15
│   └── quantum-x/     # Added in year 47 — no core changes
└── config/
    ├── ecosystems/
    │   ├── default.json    # Shipped with v1.0
    │   └── custom.json     # User added in year 22

6. Forward Compatibility

Never drop unknown fields. Preserve everything you don't understand. A system from year 1 must still work with data written by year 50's version.

class ForwardCompatibleConfig:
    def __init__(self, data):
        self.known = self._extract_known(data)
        self.unknown = {k: v for k, v in data.items() 
                       if k not in self.known}
    
    def serialize(self):
        return {**self.known, **self.unknown}

7. Graceful Degradation

Each subsystem fails independently. If one component is corrupt, others still work.

class SkillGenesisModel:
    def discover(self, ecosystems):
        try:
            return self.gap_detector.find_gaps(ecosystems)
        except Exception as e:
            self.memory.record_error("discover", str(e))
            return []  # Return empty, don't crash

Reference Implementation

See references/genesis-model-architecture.md for the complete reference implementation — the Skill Genesis Model v3.0 built entirely on these principles.

Common Pitfalls

1. Over-engineering — not every system needs 100-year architecture. Apply where data longevity matters (state files, user data, configuration registries). Don't use for ephemeral computation.

2. Migration chain breaks — if a migration function has a bug, all subsequent migrations fail. Test every migration path. Keep old migration functions even after they're superseded.

3. No rollback plan — migration should have a rollback path. Keep the .bak file from before migration. Test rollback as rigorously as migration.

4. Silent data loss — preserving unknown fields means bugs in unknown fields persist. Log the presence of unknown fields during migration so operators know they exist.

5. Backup pollution — every atomic write creates a .bak file. Implement retention policy (keep last 3-5 backups, oldest weekly backup).

Verification Checklist

• Every configurable value loads from external files, not code
• State files carry schema_version with auto-migration chain
• Corrupt state self-heals from backup or defaults
• All state writes use atomic .tmp + replace pattern
• New capabilities require config changes, not code changes
• Unknown fields preserved during load/save cycles
• Subsystems fail independently (try/except each component)
• Migration chain tested for every version jump
• Backup retention policy implemented
• Graceful degradation: partial results > no results

See Also

• system-design-patterns — general distributed system patterns
• software-design-patterns — classic GoF patterns
• hexagonal-architecture — port/adapter separation
• domain-driven-design-tactical — bounded contexts and aggregates