1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
# 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.
|
