roam/azosarchitecture.org

azos/architecture

• Architecture
  • Module registration pattern
  • Option namespace
  • File deployment
  • Claude Code integration
  • Packaging Emacs packages not in nixpkgs
  • LaTeX-to-SVG rendering (latex-to-svg-backend / agent-shell-math-renderer)

Architecture

azos is a NixOS/home-manager configuration repo with a two-tier feature system:

• azos-core/ — git submodule containing shared, reusable features (base, editor, claude-memory, claude-skills, dev, etc.)
• features/ — machine-specific features (claude, encryption, hyprland, audio, etc.)
• home-manager/home.nix — home-manager entry point; manually lists all modules to import
• _machines/ — per-machine NixOS configs; passes suiteModules as specialArgs

Feature auto-discovery is via import-tree in each flake.nix. Features from both azos-core/features/ and azos/features/ are collected into config.flake.modules.

Module registration pattern

Each feature's default.nix registers itself:

config.flake.modules.homeManager.<name> = { lib, config, pkgs, ... }: {
  options.azos.<name>.enable = lib.mkOption { ... };
  config = lib.mkIf config.azos.<name>.enable { ... };
};

Modules are then imported in home-manager/home.nix via:

imports = [ suiteModules.homeManager.<name> ... ];

Option namespace

azos.<feature-name>.<option-name>

Dependencies between features use lib.mkDefault true to auto-enable:

azos.claude-memory.enable = lib.mkDefault true;
azos.claude-skills.enable = lib.mkDefault true;

File deployment

• Static files: home.file."path".source = ./file;
• Generated text: home.file."path".text = "...";
• Runtime scripts (e.g. merging JSON): home.activation.<name> = lib.hm.dag.entryAfter ["writeBoundary"] ''...'';

Claude Code integration

Three azos-core features wire up Claude Code:

• claude-memory — registers org-roam-mcp as a global MCP server in ~/.claude.json
• claude-skills — deploys skills to ~/.claude/commands/ and content to ~/.claude/CLAUDE.md
• claude (azos/features) — installs claude-code, auto-enables the above two

Packaging Emacs packages not in nixpkgs

epkgs (passed into azos-core/features/editor/emacs/_pkg.nix) is pkgs.emacs.pkgs, i.e. nixpkgs' generated melpa package set — it lags real MELPA/GitHub by a while, so brand-new packages (e.g. from an active author) are often missing.

Pattern used for gptel, gptel-autocomplete, latex-to-svg-backend, agent-shell-math-renderer: define a let binding in _pkg.nix using epkgs.callPackage epkgs.trivialBuild { pname; version; src = pkgs.fetchFromGitHub {...}; buildInputs = [...]; }, then reference that binding in the packageRequires list. Get the rev via git ls-remote <url> HEAD, and the sha256 via nix-prefetch-url --unpack --type sha256 https://github.com/<owner>/<repo>/archive/<rev>.tar.gz then nix hash convert --hash-algo sha256 --to sri <hash> to get the SRI form used elsewhere in the repo. Inter-package deps (e.g. agent-shell-math-renderer needs agent-shell + latex-to-svg-backend) go in that package's buildInputs.

Sandbox note: during the trivialBuild native-compile step you'll see "Failed to install <pkg>: Creating directory: Permission denied, /homeless-shelter" — this is benign sandbox noise (no HOME during build), not a build failure; the derivation still completes and installs correctly. Same warning already appears for gptel-autocomplete.

LaTeX-to-SVG rendering (latex-to-svg-backend / agent-shell-math-renderer)

latex-to-svg-backend compiles equations with \documentclass[varwidth,border=2pt]{standalone} plus \usepackage{amsmath,amssymb,xcolor}. The system texlive (azos-core/features/editor/_pkg.nix, overlay pkgs.azos-tex, a texliveSmall.withPackages closure used for org-mode LaTeX export too) did NOT originally include the standalone document class or its varwidth dependency — this caused silent "LaTeX-to-SVG compile failed" warnings in agent-shell with no equation rendered. Fixed by adding standalone, varwidth, amsfonts (provides amssymb.sty), xcolor, and mylatexformat (optional but enables the package's precompiled-preamble speedup; latex-to-svg-backend-precompile defaults to t and falls back gracefully if missing) to that package list. Verified by hand: latex (from pkgs.azos-tex) then dvisvgm on a test equation with the exact preamble above.

General gotcha: if a new agent-shell/org LaTeX-preview package starts throwing "compile failed" / missing .sty errors, check azos-core/features/editor/_pkg.nix (azos-tex overlay) for the missing texlive package name — the error log path is printed in the Emacs warning (e.g. ~/.cache/emacs/latex-to-svg/svg/<hash>.log) and gives the exact missing file.