---
title: "Development Notes"
html_title: "Enroll Development Notes"
description: "Developer-oriented overview of Enroll architecture, collectors, safety helpers, renderers, and tests."
---
<header class="py-5 hero">
  <div class="container py-3">
    <div class="kicker mb-3"><i class="bi bi-diagram-3"></i> Development notes</div>
    <h1 class="display-6 fw-bold mb-2">How the codebase is structured</h1>
    <p class="lead mb-0">A compact web version of the current development guide for contributors and reviewers.</p>
  </div>
</header>

<main class="py-5">
  <div class="container">
    <div class="row g-4">
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Runtime flow</h2><p class="text-secondary">The CLI injects INI defaults, parses arguments, performs root PATH safety checks, then dispatches to harvest, manifest, diff, explain, or validate. Manifest and diff normalize directory/tar/SOPS inputs into private frozen working trees before consuming artifacts.</p></div></div>
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Harvest order</h2><p class="text-secondary mb-0">Platform detection and package indexing run first. Collectors then process runtime state, cron/logrotate, services/packages, users plus Flatpak/Snap, container images, package-manager config, remaining <code>/etc</code>, <code>/usr/local</code>, and extra paths. Parent directories and package inventory are appended before writing <code>state.json</code>.</p></div></div>
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Global de-duplication</h2><p class="text-secondary mb-0"><code>captured_global</code> keeps a destination path from being owned by two generated roles. New collectors should route file/link capture through the shared helpers rather than appending directly to snapshots.</p></div></div>
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Backends</h2><p class="text-secondary mb-0"><code>DpkgBackend</code> and <code>RpmBackend</code> implement ownership lookup, manual package listing, installed inventory, <code>/etc</code> indexing, modified config detection, and package-manager config exclusions. Add new backends behind <code>platform.get_backend()</code>.</p></div></div>
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Renderer-neutral model</h2><p class="text-secondary mb-0">Harvest snapshots are converted into <code>CMModule</code> objects before Ansible rendering. Common role grouping can combine package and systemd modules by Debian Section/RPM Group unless <code>--no-common-roles</code> or <code>--fqdn</code> is used.</p></div></div>
      <div class="col-lg-6"><div class="feature-card p-4 h-100"><h2 class="h5 fw-bold">Ansible renderer</h2><p class="text-secondary mb-0">The renderer writes scaffold, tasks, handlers, files/templates, variables, playbooks, inventory, requirements, and a generated README. It keeps harvested free text in data variables and only interpolates sanitized role/module tokens into task structure.</p></div></div>
    </div>

    <div class="feature-card p-4 mt-4">
      <h2 class="h4 fw-bold mb-3">Collector map</h2>
      <div class="table-responsive">
        <table class="table table-sm align-middle mb-0">
          <thead><tr><th>Collector</th><th>Purpose</th><th>Typical roles/snapshots</th></tr></thead>
          <tbody>
            <tr><td><code>RuntimeStateCollector</code></td><td>Root-only runtime sysctl and firewall fallback snapshots.</td><td><code>sysctl</code>, <code>firewall_runtime</code>, <code>enroll_runtime</code></td></tr>
            <tr><td><code>CronLogrotateCollector</code></td><td>Centralises cron and logrotate before package/service roles claim files.</td><td><code>cron</code>, <code>logrotate</code></td></tr>
            <tr><td><code>ServicePackageCollector</code></td><td>Enabled systemd services, related packages, config, drop-ins, env files, and enablement symlinks.</td><td>service and package roles</td></tr>
            <tr><td><code>UsersCollector</code></td><td>Non-system users, authorized keys, safe SSH material, shell dotfiles in dangerous mode, Flatpak/Snap discovery.</td><td><code>users</code>, <code>flatpak</code>, <code>snap</code></td></tr>
            <tr><td><code>ContainerImagesCollector</code></td><td>Docker/Podman image metadata, digest-pinned pull references, tag aliases, notes for non-reproducible local tags.</td><td><code>container_images</code></td></tr>
            <tr><td><code>PackageManagerConfigCollector</code></td><td>APT/DNF/YUM repo and keyring configuration.</td><td><code>apt_config</code>, <code>dnf_config</code></td></tr>
            <tr><td><code>UsrLocalCustomCollector</code></td><td><code>/usr/local/etc</code> and executable scripts under <code>/usr/local/bin</code>.</td><td><code>usr_local_custom</code></td></tr>
            <tr><td><code>ExtraPathsCollector</code></td><td>User requested include/exclude path capture.</td><td><code>extra_paths</code></td></tr>
          </tbody>
        </table>
      </div>
    </div>

    <div class="feature-card p-4 mt-4">
      <h2 class="h4 fw-bold mb-3">Testing focus</h2>
      <p class="text-secondary mb-0">The test suite covers CLI parsing and config injection, package backends, collectors, path filtering, secret detection, filesystem safety, SOPS helpers, remote extraction, manifest rendering, JinjaTurtle integration, validation, diff formatting, and output hardening. New features should usually add focused unit tests plus an end-to-end render or validation check where generated Ansible changes.</p>
    </div>
  </div>
</main>