# Modular Emacs Architecture Design

**Date:** 2026-04-09

## Goal

Refactor the repository from a single literate `config.org` source into a
hand-edited modular Emacs configuration built around `init.el`,
`early-init.el`, and a small set of domain-based Lisp modules under `lisp/`,
while preserving existing behavior as closely as possible.

## Scope

This change is an architectural refactor, not a workflow redesign. Existing
startup behavior, packages, capture flows, agenda rules, CRM commands,
completion setup, and keybindings should remain materially the same unless a
small structural adjustment is required by the new module boundaries.

## Architecture

### Entry points

- `early-init.el` remains a standalone file and contains only true early
  startup concerns that must exist before the first GUI frame.
- `init.el` becomes the hand-edited runtime entry point.
- `init.el` adds `lisp/` to `load-path`, defines a central
  `ss-enabled-features` list, requires `ss-core`, and conditionally loads and
  sets up each high-level feature module.

### Module boundaries

- `lisp/ss-core.el`
  Owns Emacs version checks, package bootstrap, shared constants and helper
  functions, note-system paths, and small shared editor defaults that other
  modules depend on.
- `lisp/ss-ui.el`
  Owns theme, fonts, frame behavior, modeline, and terminal-versus-GUI UI
  setup.
- `lisp/ss-org.el`
  Owns base Org configuration, shared Org helpers, startup MOC behavior, and
  note-opening helpers.
- `lisp/ss-agenda.el`
  Owns agenda file discovery rules and agenda command setup.
- `lisp/ss-capture.el`
  Owns journal capture helpers and `org-capture` templates.
- `lisp/ss-denote.el`
  Owns Denote configuration and note creation helpers.
- `lisp/ss-crm.el`
  Owns all people CRM logic, including parsing, cache management, abbrevs,
  CAPF, lookup, open/find/insert/add/report commands, and prompt helpers.
- `lisp/ss-gptel.el`
  Owns the experimental `gptel` integration.
- `lisp/ss-keys.el`
  Owns central global keybindings only.

### Dependency shape

- `ss-core` is the only unconditional module.
- Other modules may depend on `ss-core` helpers and shared path constants.
- `ss-keys` binds commands provided by other modules but should not implement
  workflow logic itself.
- Side effects should happen in each module's `ss-...-setup` function rather
  than during `require`, except for definitions that are harmless at load time.

## Migration decisions

- Remove `config.org` entirely after extraction. There will be no transitional
  dual system and no compatibility tangling layer.
- Keep `build` only if it remains useful for the modular setup; otherwise
  remove or repurpose it truthfully.
- Keep `reset` only if it still aligns with the hand-edited architecture;
  update it so it no longer treats `init.el` or `early-init.el` as generated
  artifacts.

## Validation

- Primary validation: `emacs --batch -Q --load ./init.el`
- If the refactor preserves terminal-specific UI behavior, also verify in a
  real `emacs -nw` session when practical.
- Documentation must be updated in the same change so `README.md` and
  `AGENTS.md` describe the modular architecture truthfully.