#Architecture
#Layers
aegis/ public facade (aegis install, aegis cubes, …)app/├── core/ aegis.system, aegis.storage, hardware, network, sys├── helpers/ cli, config, files, process, template, toml, geoip, result├── modules/│ ├── thor/ catalog, downloads, runtime, build engine, installer│ ├── keeper/ process supervision, heartbeats, scheduled jobs│ ├── tasker/ the task queue: one row per action, and its daemon│ ├── pulse/ area samplers for the live feed│ ├── bird/ WebSocket transport (publish side)│ ├── collector/ counters and their storage│ ├── monitor/ realtime connections, requests and deliveries│ ├── web_admin/ the panel: routes, templates, JSON endpoints│ ├── web/ vhost model, rendering, apply│ ├── dns/ zones, records, repairs, state│ ├── ssl/ certificate resolution and generation│ ├── uapi/ one API for OS operations (packages, users, services…)│ ├── db/ SQLite lifecycle, migrations, seeders│ ├── geoip/ MaxMind database download and status│ ├── net/ interfaces, addresses, peers, ports│ ├── health/ the checks behind `aegis check`│ └── docs/ Markdown → HTML documentation site└── cubes/ one management module per application (bind, nginx, …)aegis is only a facade: implementations live under app/, and call sites — including the CLI — import through aegis where a public entry point exists.
#The root is never hardcoded
app/core/system.py resolves the project root from its own file location:
app/core/system.py → parents[2] → /etc/aegis (or wherever it was copied)Everything else is relative to that root:
aegis.system.path("config", "aegis.toml") # <root>/config/aegis.tomlaegis.system.vendor_path("apps") # <root>/vendor/appsaegis.storage.data.app("nginx").templates_dir # <root>/storage/data/apps/nginx/templatesDestination paths for installed software come from configuration, with fallbacks derived from the root as well:
aegis root = "/aegis" install root for apps/data/logsapps install_path = "/aegis/apps"nginx config_dir = "/aegis/config/nginx"Remove those keys and the defaults become <root>/apps, <root>/config/nginx and so on — the tree stays self-contained wherever it lives.
#Storage, split by purpose
aegis.storage is a package with one submodule per data area:
storage/├── data/ shipped with the panel: build profiles, templates, patches│ └── apps/<name>/{build.toml,templates/,patches/}├── temp/ scratch: extracted sources, downloads (safe to delete)├── apps/ installer state (state.json)└── media/ user media (future)from app.core import aegisaegis.storage.data.app("bind").templates_diraegis.storage.data.app("bind").build_profileaegis.storage.temp("build", "nginx-1.30.6", create=True)aegis.storage.data.apps() # ["bind", "nginx", …]Adding cache/ later means adding storage.cache, never a path spelled by hand at a call site.
#Installer steps
A step is a named container of tasks with a failure policy:
class ServerInfo(Step): def name(self) -> str: return "verification/server" def tasks(self) -> Sequence[Task]: ... def on_fail(self) -> Failure: return Failure.BREAKA task is one unit that returns a TaskResult. Failure is either BREAK (stop the run) or CONTINUE. Tasks can post a live status line through context.report(...), which the console renderer shows in the spinner instead of printing a new line (a printed line would break the in-place header rewrite).
#Build engine
plan.resolve(app) depth-first over [dependencies] libs, dependencies firstplan.prefix(config, app) the one place that knows <apps>/<group>/<name>/<series>Builder resolve libs, extract, configure, compile, installVerifier [verify] rules: binaries, libraries, commandsmodules third-party sources added with --add-modulepatches profile patches applied once after extractionBuilder._env() gives every build the same view of the world:
CPPFLAGS / LDFLAGS every declared libraryPKG_CONFIG_PATH their pkgconfig directoriesCMAKE_PREFIX_PATH CMake ignores CPPFLAGSPATH runtime bin first, then librariesLD_LIBRARY_PATH only for verification and tools#Cubes
A cube owns the runtime side of one application: configuration files, the validation command, the reload path, and (optionally) a service() definition for the keeper. Building belongs to the installer; a cube never compiles.
class Nginx(Cube): def name(self) -> str: return "nginx" def configure(self) -> str: ... def validate(self) -> str: ... def reload(self) -> str: ... def service(self) -> keeper.Service: ...Discovery is from disk: every app/cubes/<name>/cube.py with a Cube subclass is mounted under aegis cubes <name>, and appears in keeper services when it exposes service().
#Where a write happens
A request never changes the host. The panel validates the form, stores a task in database/storage/tasker/tasker.db, and returns; the tasker daemon executes it in a worker and records the outcome. The same row is what the task window, the task page and the CLI read, so there is one history instead of one log per section.
That matters for operations that are slow or dangerous: a vhost render runs nginx -t and reloads, a mail domain also writes a DKIM key and a DNS record, a DNS change rewrites a zone file. Each of them needs a place where the failure stays readable afterwards, and a rollback step when the second half fails.
#Keeper
keeper service.py Service(name, command, pid_file, log_file, environment)keeper manager.py start / stop / restart / statuskeeper registry.py collects service() from the installed cubeskeeper daemon.py loop that restarts whatever is down (10 s)keeper boot.py /etc/init.d/aegis-keeperNo systemd: the platform supervises its own processes. A pid file and a log file per service live under <root>/run and <root>/logs.
#uapi
app/modules/uapi is the only place that talks to the distribution. Domains: commands, packages, services, users, groups, host, network. Platforms: ubuntu, debian (both delegating to debian_family), with run_<version> overrides resolved automatically.