The Three Primary Layers of the CareerOps System Design Explained

The CareerOps system design consists of three primary layers: the User Layer (personal data and customizations), the System Layer (executable scripts and templates), and the Source-of-Truth Boundary (rules that enforce data integrity). This architecture ensures your CV and profile remain protected while the automation logic evolves independently.

The santifer/career-ops repository implements this strict separation of concerns to prevent accidental data loss during updates. Understanding these three primary layers allows you to safely customize your career materials without interfering with core system functionality.

The User Layer: Immutable Personal Assets

The User Layer contains all personal data and customizations that define your professional narrative. According to the CareerOps source code, this layer includes critical files such as cv.md, config/profile.yml, modes/_profile.md, modes/_custom.md, and interview preparation assets like interview-prep/story-bank.md.

These files are designated as immutable by system updates. When CareerOps releases new versions, the automation explicitly skips these paths to prevent accidental overwrites of your curated experience. This safety mechanism ensures that your CV narrative, custom archetypes, and interview stories remain exactly as you authored them.

To modify your professional profile, edit the files in this layer directly:

<!-- Path: modes/_profile.md -->
<!-- This file lives in the User Layer and persists across updates -->

Archetype: Senior Backend Engineer
Narrative: Focus on scalable micro-services, cloud-native design, and performance-critical systems.

The System Layer: Auto-Updatable Logic

The System Layer encompasses all executable scripts, shared utilities, and templates that power the CareerOps automation. This layer includes *.mjs scripts, modes/_shared.md, templates/*, and providers/* files that handle scanning, evaluation, and PDF generation.

Unlike the User Layer, the System Layer is fully auto-updatable. During each release, CareerOps replaces these files with improved versions, ensuring you receive bug fixes and new features without manual intervention. The system logic operates on your data without ever modifying it.

When extending functionality, you interact with files like modes/_shared.md:

// Path: modes/_shared.md
// This lives in the System Layer and updates automatically

score += experienceYears > 5 ? 1.5 : 0.5;

The Source-of-Truth Boundary: Data Integrity Rules

The Source-of-Truth Boundary is the architectural constraint that determines which files CareerOps treats as authoritative when generating outputs. Defined in DATA_CONTRACT.md and enforced throughout the codebase, this boundary dictates that only specific User Layer files—primarily cv.md, config/profile.yml, and modes/_profile.md—serve as factual sources.

Derived files such as interview-prep/story-bank.md are never used as primary factual sources unless they explicitly reference data from the designated primary files. This prevents "hallucinated" claims in generated cover letters or reports. The boundary ensures that every output is grounded in your verified data.

For example, when generating application materials, the system reads exclusively from cv.md:

<!-- Path: cv.md (User Layer, authoritative source) -->

# Experience

- Company A – Lead Engineer (2020-2023)

Any statistics appearing only in interview-prep/story-bank.md are ignored unless corroborated by cv.md, preserving factual integrity across all generated content.

Summary

• The User Layer protects immutable personal assets like cv.md and config/profile.yml from automatic updates, ensuring your career narrative remains under your exclusive control.
• The System Layer delivers auto-updatable automation through files like *.mjs and modes/_shared.md, providing the logic for evaluation and generation without touching user data.
• The Source-of-Truth Boundary enforces data integrity via DATA_CONTRACT.md, restricting authoritative sources to designated primary files and preventing fabricated claims in outputs.

Frequently Asked Questions

Which files belong to the User Layer in CareerOps?

The User Layer includes cv.md, config/profile.yml, modes/_profile.md, modes/_custom.md, and all interview preparation files such as interview-prep/story-bank.md. These files are explicitly protected from automatic updates and persist across system releases.

How does the System Layer update without breaking my data?

CareerOps treats System Layer files—such as *.mjs scripts, modes/_shared.md, and templates—as disposable and auto-replaceable. The architecture strictly separates these from User Layer paths, ensuring updates overwrite only automation logic while preserving your personal content in cv.md and related files.

What happens if I store facts only in interview preparation files?

The Source-of-Truth Boundary ignores isolated data in interview-prep/story-bank.md when generating official outputs. For information to appear in generated cover letters or CV variants, it must exist in an authoritative source like cv.md or modes/_profile.md, preventing unverified claims from entering professional documents.

Where is the Source-of-Truth Boundary documented?

The boundary rules are codified in DATA_CONTRACT.md within the santifer/career-ops repository, with additional implementation details in AGENTS.md. These files define which paths CareerOps recognizes as primary factual sources versus derived or secondary content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}